mdat 2.0.0 → 2.0.1

package/dist/bin/cli.js

@@ -7,9 +7,9 @@ import { TypeScriptLoader } from "cosmiconfig-typescript-loader";
 import fs from "node:fs/promises";
 import path from "node:path";
 import plur from "plur";
-import { defineTemplate, getMetadata, helpers, setLogger as setLogger$1, templates } from "metascope";
 import { deepmerge } from "deepmerge-ts";
 import { createLogger, getChildLogger, injectionHelper } from "lognow";
+import { defineTemplate, getMetadata, helpers, setLogger as setLogger$1, templates } from "metascope";
 import { z } from "zod";
 import { globby } from "globby";
 import { isFile, isFileSync } from "path-type";
@@ -27,65 +27,6 @@ import { confirm, group, intro, note, outro, select } from "@clack/prompts";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 
-//#region src/lib/context.ts
-let metascopeMetadata;
-/**
-* Get a bunch of platform-agnostic local metadata via metascope, exposed
-* primarily for plugin developers.
-* Result is memoized the result.
-* @throws {Error} If no package.json is found
-*/
-async function getContextMetadata() {
-	if (metascopeMetadata !== void 0) return metascopeMetadata;
-	metascopeMetadata = await getMetadata({
-		absolute: false,
-		offline: true
-	});
-	return metascopeMetadata;
-}
-/**
-* Reset
-*/
-function resetContextMetadata() {
-	metascopeMetadata = void 0;
-}
-const readmeMetadataTemplate = defineTemplate((context) => {
-	const { githubActions, licenseFile, metascope, nodePackageJson } = context;
-	const codemeta = templates.codemetaJson(context, {});
-	const nodePackage = helpers.firstOf(nodePackageJson)?.data;
-	const licenseFileData = helpers.firstOf(licenseFile);
-	const ciActionFilePath = helpers.ensureArray(githubActions).find((entry) => entry.data.name.toLowerCase() === "ci")?.source;
-	const repositoryOwner = codemeta.codeRepository ? new URL(codemeta.codeRepository).pathname.split("/")[1] : void 0;
-	return {
-		author: helpers.firstOf(helpers.mixedStringsToArray(helpers.toBasicNames(codemeta.author))),
-		ciActionFileName: ciActionFilePath ? path.basename(ciActionFilePath) : void 0,
-		description: codemeta.description,
-		isPublicNpmPackage: !nodePackage?.name.startsWith("@") || nodePackage.publishConfig?.access === "public",
-		issuesUrl: codemeta.issueTracker,
-		license: helpers.toBasicLicense(helpers.firstOf(helpers.ensureArray(codemeta.license))),
-		licenseFilePath: licenseFileData?.source,
-		name: codemeta.name,
-		projectDirectory: metascope?.data.options.path === void 0 ? void 0 : `file://${metascope.data.options.path}`,
-		repositoryOwner
-	};
-});
-let readmeMetadata;
-/**
-* Nice data for readme rules
-*/
-async function getReadmeMetadata() {
-	if (readmeMetadata !== void 0) return readmeMetadata;
-	readmeMetadata = readmeMetadataTemplate(await getContextMetadata(), {});
-	return readmeMetadata;
-}
-/**
-* Reset
-*/
-function resetReadmeMetadata() {
-	readmeMetadata = void 0;
-}
-
-//#endregion
 //#region src/lib/deep-merge-defined.ts
 function stripUndefinedDeep(object) {
 	if (Array.isArray(object)) return object.map((v) => v && typeof v === "object" ? stripUndefinedDeep(v) : v).filter((v) => v !== void 0);
@@ -101,7 +42,7 @@ function deepMergeDefined(...objects) {
 //#endregion
 //#region package.json
 var name = "mdat";
-var version = "2.0.0";
+var version = "2.0.1";
 
 //#endregion
 //#region src/lib/log.ts
@@ -146,6 +87,87 @@ function flattenJson(jsonObject, parentKey = "", result = {}) {
 	return result;
 }
 
+//#endregion
+//#region src/lib/context.ts
+let metascopeMetadata;
+/**
+* Get a bunch of platform-agnostic local metadata via metascope, exposed
+* primarily for plugin developers. Result is memoized the result.
+*
+* @throws {Error} If no package.json is found
+*/
+async function getContextMetadata() {
+	if (metascopeMetadata !== void 0) return metascopeMetadata;
+	metascopeMetadata = await getMetadata({
+		absolute: false,
+		offline: true,
+		sources: [
+			"arduinoLibraryProperties",
+			"cinderCinderblockXml",
+			"codemetaJson",
+			"gitConfig",
+			"githubActions",
+			"goGoMod",
+			"goGoreleaserYaml",
+			"javaPomXml",
+			"licenseFile",
+			"metadataFile",
+			"metascope",
+			"nodePackageJson",
+			"obsidianPluginManifestJson",
+			"openframeworksAddonConfigMk",
+			"openframeworksInstallXml",
+			"processingLibraryProperties",
+			"processingSketchProperties",
+			"publiccodeYaml",
+			"pythonPkgInfo",
+			"pythonPyprojectToml",
+			"pythonSetupCfg",
+			"pythonSetupPy",
+			"readmeFile",
+			"rubyGemspec",
+			"rustCargoToml",
+			"xcodeInfoPlist",
+			"xcodeProjectPbxproj"
+		]
+	});
+	return metascopeMetadata;
+}
+const GIT_PREFIX_REGEX = /^git\+/;
+const GIT_SUFFIX_REGEX = /\.git$/;
+const TRAILING_SLASH_REGEX = /\/$/;
+const readmeMetadataTemplate = defineTemplate((context) => {
+	const { githubActions, licenseFile, metascope, nodePackageJson } = context;
+	const codemeta = templates.codemetaJson(context, {});
+	const nodePackage = helpers.firstOf(nodePackageJson)?.data;
+	const licenseFileData = helpers.firstOf(licenseFile);
+	const ciActionFilePath = helpers.ensureArray(githubActions).find((entry) => entry.data.name.toLowerCase() === "ci")?.source;
+	const repositoryUrl = codemeta.codeRepository?.replace(GIT_PREFIX_REGEX, "").replace(GIT_SUFFIX_REGEX, "").replace(TRAILING_SLASH_REGEX, "");
+	return {
+		author: helpers.firstOf(helpers.mixedStringsToArray(helpers.toBasicNames(codemeta.author))),
+		ciActionFileName: ciActionFilePath ? path.basename(ciActionFilePath) : void 0,
+		description: codemeta.description,
+		isPublicNpmPackage: !nodePackage?.name.startsWith("@") || nodePackage.publishConfig?.access === "public",
+		issuesUrl: codemeta.issueTracker,
+		license: helpers.toBasicLicense(helpers.firstOf(helpers.ensureArray(codemeta.license))),
+		licenseFilePath: licenseFileData?.source,
+		name: codemeta.name,
+		projectDirectory: metascope?.data.options.path === void 0 ? void 0 : `file://${metascope.data.options.path}`,
+		repositoryUrl
+	};
+});
+let readmeMetadata;
+/**
+* Nice data for readme rules
+*
+* @public
+*/
+async function getReadmeMetadata() {
+	if (readmeMetadata !== void 0) return readmeMetadata;
+	readmeMetadata = readmeMetadataTemplate(await getContextMetadata(), {});
+	return readmeMetadata;
+}
+
 //#endregion
 //#region src/lib/readme/rules/badges.ts
 var badges_default = { badges: { async content(options) {
@@ -157,13 +179,13 @@ var badges_default = { badges: { async content(options) {
 		npm: z.array(z.string()).optional()
 	}).optional().parse(options);
 	const metadata = await getReadmeMetadata();
-	const { ciActionFileName, license, name, repositoryOwner } = metadata;
+	const { ciActionFileName, license, name, repositoryUrl } = metadata;
 	const badges = [];
 	if (validOptions?.npm === void 0) {
 		if (metadata.isPublicNpmPackage) badges.push(`[![NPM Package ${name}](https://img.shields.io/npm/v/${name}.svg)](https://npmjs.com/package/${name})`);
 	} else for (const name of validOptions.npm) badges.push(`[![NPM Package ${name}](https://img.shields.io/npm/v/${name}.svg)](https://npmjs.com/package/${name})`);
 	if (license !== void 0) badges.push(`[![License: ${license}](https://img.shields.io/badge/License-${license.replaceAll("-", "--")}-yellow.svg)](https://opensource.org/licenses/${license})`);
-	if (ciActionFileName !== void 0 && repositoryOwner !== void 0) badges.push(`[![CI](https://github.com/${repositoryOwner}/${name}/actions/workflows/${ciActionFileName}/badge.svg)](https://github.com/${repositoryOwner}/${name}/actions/workflows/${ciActionFileName})`);
+	if (ciActionFileName !== void 0 && repositoryUrl !== void 0) badges.push(`[![CI](${repositoryUrl}/actions/workflows/${ciActionFileName}/badge.svg)](${repositoryUrl}/actions/workflows/${ciActionFileName})`);
 	if (validOptions?.custom !== void 0) for (const [name, { image, link }] of Object.entries(validOptions.custom)) badges.push(`[![${name}](${image})](${link})`);
 	return badges.join("\n");
 } } };
@@ -231,24 +253,21 @@ function isUrl(text, lenient = true) {
 	if (typeof text !== "string") throw new TypeError("Expected a string");
 	text = text.trim();
 	if (text.includes(" ")) return false;
-	try {
-		new URL(text);
-		return true;
-	} catch {
-		if (lenient) return isUrl(`https://${text}`, false);
-		return false;
-	}
+	if (URL.canParse(text)) return true;
+	if (lenient) return isUrl(`https://${text}`, false);
+	return false;
 }
 
 //#endregion
 //#region src/lib/readme/rules/code.ts
+const LEADING_DOT_REGEX = /^\./;
 var code_default = { code: { async content(options) {
 	const validOptions = z.object({
 		file: z.string(),
 		language: z.string().optional(),
 		trim: z.boolean().default(true)
 	}).parse(options);
-	const lang = (path.extname(validOptions.file) ?? "").replace(/^\./, "");
+	const lang = (path.extname(validOptions.file) ?? "").replace(LEADING_DOT_REGEX, "");
 	const exampleCode = await fs.readFile(path.join(process.cwd(), validOptions.file), "utf8");
 	return `\`\`\`${lang}\n${validOptions.trim ? exampleCode.trim() : exampleCode}\n\`\`\``;
 } } };
@@ -309,8 +328,9 @@ var title_default = { title: {
 	},
 	order: 2
 } };
+const SPLIT_FOR_TITLE_CASE_REGEX = /[ _-]+/;
 function makeTitleCase(text) {
-	return text.split(/[ _-]+/).filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+	return text.split(SPLIT_FOR_TITLE_CASE_REGEX).filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
 }
 
 //#endregion
@@ -497,6 +517,19 @@ var rules_default = {
 
 //#endregion
 //#region src/lib/config.ts
+let _configExplorer;
+let _additionalConfigExplorer;
+function getConfigExplorer() {
+	_configExplorer ??= cosmiconfig("mdat", { loaders: { ".ts": TypeScriptLoader() } });
+	return _configExplorer;
+}
+function getAdditionalConfigExplorer() {
+	_additionalConfigExplorer ??= cosmiconfig("mdat", { loaders: {
+		".json": mdatJsonLoader,
+		".ts": TypeScriptLoader()
+	} });
+	return _additionalConfigExplorer;
+}
 /**
 * Load and validate mdat configuration.
 * Uses cosmiconfig to search in the usual places.
@@ -504,11 +537,9 @@ var rules_default = {
 */
 async function loadConfig(options) {
 	const { additionalConfig, defaults = rules_default, searchFrom } = options ?? {};
-	resetReadmeMetadata();
-	resetContextMetadata();
 	let finalConfig = { mdat: `Powered by the Markdown Autophagic Template system: [mdat](https://github.com/kitschpatrol/mdat).` };
 	if (defaults) finalConfig = deepMergeDefined(finalConfig, defaults);
-	const results = await cosmiconfig("mdat", { loaders: { ".ts": TypeScriptLoader() } }).search(searchFrom);
+	const results = await getConfigExplorer().search(searchFrom);
 	if (results) {
 		const { config, filepath } = results;
 		let possibleRules = config;
@@ -523,10 +554,6 @@ async function loadConfig(options) {
 	}
 	if (additionalConfig !== void 0) {
 		const additionalConfigArray = Array.isArray(additionalConfig) ? additionalConfig : [additionalConfig];
-		const configExplorer2 = cosmiconfig("mdat", { loaders: {
-			".json": mdatJsonLoader,
-			".ts": TypeScriptLoader()
-		} });
 		for (const configOrPath of additionalConfigArray) {
 			let loaded;
 			if (typeof configOrPath === "string") {
@@ -535,7 +562,7 @@ async function loadConfig(options) {
 					config: mdatJsonLoader(configOrPath, await fs.readFile(configOrPath, "utf8")),
 					filepath: configOrPath
 				};
-				else results = await configExplorer2.load(configOrPath);
+				else results = await getAdditionalConfigExplorer().load(configOrPath);
 				if (results === null || results === void 0) continue;
 				const { config: loadedConfig, filepath } = results;
 				log.debug(`Loaded additional config from "${filepath}"`);
@@ -559,20 +586,26 @@ function validateConfig(value) {
 
 //#endregion
 //#region src/lib/format.ts
+let cachedPrettier;
+const configCache = /* @__PURE__ */ new Map();
 /**
 * Format a markdown string with Prettier, using config discovered from the file path.
 * Requires `prettier` to be installed as a peer dependency.
 */
 async function formatWithPrettier(content, filePath) {
-	let prettier;
-	try {
-		prettier = await import("prettier");
+	if (cachedPrettier === void 0) try {
+		cachedPrettier = await import("prettier");
 	} catch {
 		throw new Error("The --format flag requires `prettier` to be installed. Run: pnpm add -D prettier");
 	}
-	const config = await prettier.resolveConfig(filePath ?? process.cwd());
-	if (config) log.debug(`Using Prettier config from "${config.filepath}" for "${filePath ?? process.cwd()}"`);
-	return prettier.format(content, {
+	const configKey = filePath ? path.dirname(filePath) : process.cwd();
+	let config = configCache.get(configKey);
+	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()}"`);
+	}
+	return cachedPrettier.format(content, {
 		...config,
 		filepath: filePath,
 		parser: "markdown"
@@ -614,12 +647,13 @@ function ensureArray(value) {
 	if (value === void 0 || value === null) return [];
 	return Array.isArray(value) ? value : [value];
 }
+const README_SEARCH_REGEX = /^readme(?:\.\w+)?$/i;
 /**
 * Finds a readme file in the current working directory (case-insensitive).
 */
 async function findReadme() {
 	log.debug("Searching for readme in current directory...");
-	const readme = (await fs.readdir(process.cwd())).find((entry) => /^readme(?:\.\w+)?$/i.test(entry));
+	const readme = (await fs.readdir(process.cwd())).find((entry) => README_SEARCH_REGEX.test(entry));
 	if (readme !== void 0) {
 		const absolutePath = path.resolve(readme);
 		log.debug(`Found readme at "${absolutePath}"`);
@@ -635,7 +669,9 @@ async function findReadmeThrows() {
 	if (readme === void 0) throw new Error("No readme found");
 	return readme;
 }
+let cachedAmbientRemarkConfig;
 async function loadAmbientRemarkConfig() {
+	if (cachedAmbientRemarkConfig !== void 0) return cachedAmbientRemarkConfig;
 	const ambientConfig = new Configuration({
 		cwd: process.cwd(),
 		detectConfig: true,
@@ -656,32 +692,47 @@ async function loadAmbientRemarkConfig() {
 		const { filePath } = configResult;
 		if (filePath === void 0) log.debug("No ambient Remark configuration file found");
 		else log.debug(`Found and loaded ambient Remark configuration from "${filePath}"`);
-		return configResult;
+		cachedAmbientRemarkConfig = stripLintPlugins(configResult);
+		return cachedAmbientRemarkConfig;
 	}
 	log.debug("No ambient Remark configuration found");
-	return {
+	cachedAmbientRemarkConfig = {
 		filePath: void 0,
 		plugins: [],
 		settings: {}
 	};
+	return cachedAmbientRemarkConfig;
+}
+/**
+* Strip remark-lint plugins from an ambient config. Lint plugins only produce
+* VFile warnings and never modify the AST or output — running them during
+* expansion is pure overhead.
+*/
+function stripLintPlugins(config) {
+	return {
+		...config,
+		plugins: config.plugins.filter((entry) => {
+			const plugin = Array.isArray(entry) ? entry[0] : entry;
+			if (typeof plugin !== "function") return true;
+			const { name } = plugin;
+			return name !== "remarkLint" && !name.startsWith("remark-lint:") && name !== "remarkValidateLinks";
+		})
+	};
 }
 
 //#endregion
 //#region src/lib/processors.ts
 async function processFiles(files, loader, processorGetter, name, output, config) {
-	const resolvedConfig = await loader({ additionalConfig: config });
-	const localRemarkConfiguration = await loadAmbientRemarkConfig();
+	const [resolvedConfig, localRemarkConfiguration] = await Promise.all([loader({ additionalConfig: config }), loadAmbientRemarkConfig()]);
 	const inputOutputPaths = await getInputOutputPaths(ensureArray(files), output, name, "md");
-	const results = [];
 	const resolvedProcessor = processorGetter(resolvedConfig, localRemarkConfiguration);
-	for (const { input, name, output } of inputOutputPaths) {
+	return await Promise.all(inputOutputPaths.map(async ({ input, name, output }) => {
 		const inputFile = await read(input);
 		const result = await resolvedProcessor.process(inputFile);
 		result.dirname = output;
 		result.basename = name;
-		results.push(result);
-	}
-	return results;
+		return result;
+	}));
 }
 function getExpandProcessor(config, ambientRemarkConfig) {
 	return remark().use({ settings: {
@@ -870,11 +921,10 @@ async function check(files, config, options) {
 	files ??= await findReadmeThrows();
 	const { read } = await import("to-vfile");
 	const resolvedFiles = Array.isArray(files) ? files : [files];
-	const originals = await Promise.all(resolvedFiles.map(async (f) => read(f)));
-	const results = await processFiles(files, loadConfig, getExpandProcessor, void 0, void 0, config);
+	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() === result.toString(),
+		inSync: originals[i].toString().replaceAll("\r\n", "\n") === result.toString(),
 		result
 	}));
 }
@@ -961,7 +1011,11 @@ try {
 		setLogger$2(createLogger({
 			name,
 			verbose: argv.verbose ?? false,
-			logToConsole: { showTime: false }
+			logToConsole: {
+				showLevel: false,
+				showName: false,
+				showTime: false
+			}
 		}));
 	}).command(["$0 [files..] [options]", "expand [files..] [options]"], "Expand MDAT placeholder comments. If no files are provided, the closest readme.md is expanded.", (yargs) => yargs.positional(...filesPositional).option(configOption).option(outputOption).option(nameOption).option(printOption).option(formatOption), async ({ config, files, format, name, output, print }) => {
 		logConflicts({
@@ -987,14 +1041,14 @@ try {
 		reporterMdat(results);
 		log.debug(`Collapsed 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 are out of sync.", (yargs) => yargs.positional(...filesPositional).option(configOption).option(formatOption), async ({ config, files, format }) => {
+	}).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;
 		for (const { inSync, result } of results) {
 			const filePath = result.path || "unknown";
-			if (inSync) log.info(`${picocolors.green("in sync")}: ${filePath}`);
+			if (inSync) log.debug(`${picocolors.green("Up to date")}: ${filePath}`);
 			else {
-				log.info(`${picocolors.red("out of sync")}: ${filePath}`);
+				log.warn(`${picocolors.red("Stale content")}: ${filePath}`);
 				allInSync = false;
 			}
 		}

package/dist/lib/index.d.ts

@@ -1,7 +1,7 @@
 import { Rule, Rule as Rule$1 } from "remark-mdat";
+import { ILogBasic, ILogLayer } from "lognow";
 import * as _$metascope from "metascope";
 import { MetadataContext } from "metascope";
-import { ILogBasic, ILogLayer } from "lognow";
 import { VFile } from "vfile";
 
 //#region src/lib/config.d.ts
@@ -111,8 +111,8 @@ declare function check(files?: string | string[], config?: ConfigToLoad, options
 //#region src/lib/context.d.ts
 /**
  * Get a bunch of platform-agnostic local metadata via metascope, exposed
- * primarily for plugin developers.
- * Result is memoized the result.
+ * primarily for plugin developers. Result is memoized the result.
+ *
  * @throws {Error} If no package.json is found
  */
 declare function getContextMetadata(): Promise<MetadataContext>;
@@ -126,11 +126,13 @@ declare const readmeMetadataTemplate: _$metascope.Template<{
   licenseFilePath: string | undefined;
   name: string | undefined;
   projectDirectory: string | undefined;
-  repositoryOwner: string | undefined;
+  repositoryUrl: string | undefined;
 }>;
 type ReadmeMetadata = ReturnType<typeof readmeMetadataTemplate>;
 /**
  * Nice data for readme rules
+ *
+ * @public
  */
 declare function getReadmeMetadata(): Promise<{
   author: string | undefined;
@@ -142,8 +144,13 @@ declare function getReadmeMetadata(): Promise<{
   licenseFilePath: string | undefined;
   name: string | undefined;
   projectDirectory: string | undefined;
-  repositoryOwner: string | undefined;
+  repositoryUrl: string | undefined;
 }>;
+/**
+ * Reset all cached metadata. Call between tests or when the underlying project
+ * files may have changed on disk.
+ */
+declare function resetMetadataCaches(): void;
 //#endregion
 //#region src/lib/log.d.ts
 /**
@@ -153,4 +160,4 @@ declare function getReadmeMetadata(): Promise<{
  */
 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, setLogger };
+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 };

package/dist/lib/index.js

@@ -5,9 +5,9 @@ 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 { defineTemplate, getMetadata, helpers, setLogger as setLogger$2, templates } from "metascope";
 import { deepmerge } from "deepmerge-ts";
 import { createLogger, getChildLogger, injectionHelper } from "lognow";
+import { defineTemplate, getMetadata, helpers, setLogger as setLogger$2, templates } from "metascope";
 import { z } from "zod";
 import { globby } from "globby";
 import { isFile, isFileSync } from "path-type";
@@ -22,24 +22,111 @@ import { VFile } from "vfile";
 import { Configuration } from "unified-engine";
 import untildify from "untildify";
 import { confirm, group, intro, note, outro, select } from "@clack/prompts";
+//#region src/lib/deep-merge-defined.ts
+function stripUndefinedDeep(object) {
+	if (Array.isArray(object)) return object.map((v) => v && typeof v === "object" ? stripUndefinedDeep(v) : v).filter((v) => v !== void 0);
+	return Object.entries(object).map(([k, v]) => [k, v && typeof v === "object" ? stripUndefinedDeep(v) : v]).reduce((acc, [k, v]) => v === void 0 ? acc : {
+		...acc,
+		[k]: v
+	}, {});
+}
+function deepMergeDefined(...objects) {
+	return deepmerge(...objects.map((v, i) => i === 0 ? v : stripUndefinedDeep(v)));
+}
+//#endregion
+//#region src/lib/log.ts
+/**
+* The default logger instance for the library.
+*/
+let log = createLogger({
+	logToConsole: { showTime: false },
+	name: "mdat"
+});
+setLogger$1(getChildLogger(log, "remark-mdat"));
+setLogger$2(getChildLogger(log, "metascope"));
+/**
+* Set the logger instance for the module.
+* Export this for library consumers to inject their own logger.
+* @param logger - Accepts either a LogLayer instance or a Console- or Stream-like log target
+*/
+function setLogger(logger) {
+	log = injectionHelper(logger);
+	setLogger$1(getChildLogger(log, "remark-mdat"));
+	setLogger$2(getChildLogger(log, "metascope"));
+}
+//#endregion
+//#region src/lib/mdat-json-loader.ts
+/**
+* Lets arbitrary JSON objects (like from package.json) become reasonably good mdat rule sets
+* HOWEVER cosmiconfig treats package.json as a special case and will always load only specific keys from it
+* So we have to intercept and load them manually in config.ts
+*/
+function mdatJsonLoader(filePath, content) {
+	const defaultJsonLoader = defaultLoaders[".json"];
+	return flattenJson(defaultJsonLoader(filePath, content));
+}
+function flattenJson(jsonObject, parentKey = "", result = {}) {
+	for (const [key, value] of Object.entries(jsonObject)) {
+		const fullPath = parentKey ? `${parentKey}.${key}` : key;
+		if (typeof value === "object" && value !== null && !Array.isArray(value)) flattenJson(value, fullPath, result);
+		else if (value === null) result[fullPath] = "null";
+		else result[fullPath] = value.toString();
+	}
+	return result;
+}
+//#endregion
 //#region src/lib/context.ts
 let metascopeMetadata;
 /**
 * Get a bunch of platform-agnostic local metadata via metascope, exposed
-* primarily for plugin developers.
-* Result is memoized the result.
+* primarily for plugin developers. Result is memoized the result.
+*
 * @throws {Error} If no package.json is found
 */
 async function getContextMetadata() {
 	if (metascopeMetadata !== void 0) return metascopeMetadata;
 	metascopeMetadata = await getMetadata({
 		absolute: false,
-		offline: true
+		offline: true,
+		sources: [
+			"arduinoLibraryProperties",
+			"cinderCinderblockXml",
+			"codemetaJson",
+			"gitConfig",
+			"githubActions",
+			"goGoMod",
+			"goGoreleaserYaml",
+			"javaPomXml",
+			"licenseFile",
+			"metadataFile",
+			"metascope",
+			"nodePackageJson",
+			"obsidianPluginManifestJson",
+			"openframeworksAddonConfigMk",
+			"openframeworksInstallXml",
+			"processingLibraryProperties",
+			"processingSketchProperties",
+			"publiccodeYaml",
+			"pythonPkgInfo",
+			"pythonPyprojectToml",
+			"pythonSetupCfg",
+			"pythonSetupPy",
+			"readmeFile",
+			"rubyGemspec",
+			"rustCargoToml",
+			"xcodeInfoPlist",
+			"xcodeProjectPbxproj"
+		]
 	});
 	return metascopeMetadata;
 }
+const GIT_PREFIX_REGEX = /^git\+/;
+const GIT_SUFFIX_REGEX = /\.git$/;
+const TRAILING_SLASH_REGEX = /\/$/;
 /**
 * Reset
+*
+* @public
 */
 function resetContextMetadata() {
 	metascopeMetadata = void 0;
@@ -50,7 +137,7 @@ const readmeMetadataTemplate = defineTemplate((context) => {
 	const nodePackage = helpers.firstOf(nodePackageJson)?.data;
 	const licenseFileData = helpers.firstOf(licenseFile);
 	const ciActionFilePath = helpers.ensureArray(githubActions).find((entry) => entry.data.name.toLowerCase() === "ci")?.source;
-	const repositoryOwner = codemeta.codeRepository ? new URL(codemeta.codeRepository).pathname.split("/")[1] : void 0;
+	const repositoryUrl = codemeta.codeRepository?.replace(GIT_PREFIX_REGEX, "").replace(GIT_SUFFIX_REGEX, "").replace(TRAILING_SLASH_REGEX, "");
 	return {
 		author: helpers.firstOf(helpers.mixedStringsToArray(helpers.toBasicNames(codemeta.author))),
 		ciActionFileName: ciActionFilePath ? path.basename(ciActionFilePath) : void 0,
@@ -61,12 +148,14 @@ const readmeMetadataTemplate = defineTemplate((context) => {
 		licenseFilePath: licenseFileData?.source,
 		name: codemeta.name,
 		projectDirectory: metascope?.data.options.path === void 0 ? void 0 : `file://${metascope.data.options.path}`,
-		repositoryOwner
+		repositoryUrl
 	};
 });
 let readmeMetadata;
 /**
 * Nice data for readme rules
+*
+* @public
 */
 async function getReadmeMetadata() {
 	if (readmeMetadata !== void 0) return readmeMetadata;
@@ -75,62 +164,19 @@ async function getReadmeMetadata() {
 }
 /**
 * Reset
+*
+* @public
 */
 function resetReadmeMetadata() {
 	readmeMetadata = void 0;
 }
-//#endregion
-//#region src/lib/deep-merge-defined.ts
-function stripUndefinedDeep(object) {
-	if (Array.isArray(object)) return object.map((v) => v && typeof v === "object" ? stripUndefinedDeep(v) : v).filter((v) => v !== void 0);
-	return Object.entries(object).map(([k, v]) => [k, v && typeof v === "object" ? stripUndefinedDeep(v) : v]).reduce((acc, [k, v]) => v === void 0 ? acc : {
-		...acc,
-		[k]: v
-	}, {});
-}
-function deepMergeDefined(...objects) {
-	return deepmerge(...objects.map((v, i) => i === 0 ? v : stripUndefinedDeep(v)));
-}
-//#endregion
-//#region src/lib/log.ts
-/**
-* The default logger instance for the library.
-*/
-let log = createLogger({
-	logToConsole: { showTime: false },
-	name: "mdat"
-});
-setLogger$1(getChildLogger(log, "remark-mdat"));
-setLogger$2(getChildLogger(log, "metascope"));
-/**
-* Set the logger instance for the module.
-* Export this for library consumers to inject their own logger.
-* @param logger - Accepts either a LogLayer instance or a Console- or Stream-like log target
-*/
-function setLogger(logger) {
-	log = injectionHelper(logger);
-	setLogger$1(getChildLogger(log, "remark-mdat"));
-	setLogger$2(getChildLogger(log, "metascope"));
-}
-//#endregion
-//#region src/lib/mdat-json-loader.ts
 /**
-* Lets arbitrary JSON objects (like from package.json) become reasonably good mdat rule sets
-* HOWEVER cosmiconfig treats package.json as a special case and will always load only specific keys from it
-* So we have to intercept and load them manually in config.ts
+* Reset all cached metadata. Call between tests or when the underlying project
+* files may have changed on disk.
 */
-function mdatJsonLoader(filePath, content) {
-	const defaultJsonLoader = defaultLoaders[".json"];
-	return flattenJson(defaultJsonLoader(filePath, content));
-}
-function flattenJson(jsonObject, parentKey = "", result = {}) {
-	for (const [key, value] of Object.entries(jsonObject)) {
-		const fullPath = parentKey ? `${parentKey}.${key}` : key;
-		if (typeof value === "object" && value !== null && !Array.isArray(value)) flattenJson(value, fullPath, result);
-		else if (value === null) result[fullPath] = "null";
-		else result[fullPath] = value.toString();
-	}
-	return result;
+function resetMetadataCaches() {
+	resetContextMetadata();
+	resetReadmeMetadata();
 }
 //#endregion
 //#region src/lib/readme/rules/badges.ts
@@ -143,13 +189,13 @@ var badges_default = { badges: { async content(options) {
 		npm: z.array(z.string()).optional()
 	}).optional().parse(options);
 	const metadata = await getReadmeMetadata();
-	const { ciActionFileName, license, name, repositoryOwner } = metadata;
+	const { ciActionFileName, license, name, repositoryUrl } = metadata;
 	const badges = [];
 	if (validOptions?.npm === void 0) {
 		if (metadata.isPublicNpmPackage) badges.push(`[![NPM Package ${name}](https://img.shields.io/npm/v/${name}.svg)](https://npmjs.com/package/${name})`);
 	} else for (const name of validOptions.npm) badges.push(`[![NPM Package ${name}](https://img.shields.io/npm/v/${name}.svg)](https://npmjs.com/package/${name})`);
 	if (license !== void 0) badges.push(`[![License: ${license}](https://img.shields.io/badge/License-${license.replaceAll("-", "--")}-yellow.svg)](https://opensource.org/licenses/${license})`);
-	if (ciActionFileName !== void 0 && repositoryOwner !== void 0) badges.push(`[![CI](https://github.com/${repositoryOwner}/${name}/actions/workflows/${ciActionFileName}/badge.svg)](https://github.com/${repositoryOwner}/${name}/actions/workflows/${ciActionFileName})`);
+	if (ciActionFileName !== void 0 && repositoryUrl !== void 0) badges.push(`[![CI](${repositoryUrl}/actions/workflows/${ciActionFileName}/badge.svg)](${repositoryUrl}/actions/workflows/${ciActionFileName})`);
 	if (validOptions?.custom !== void 0) for (const [name, { image, link }] of Object.entries(validOptions.custom)) badges.push(`[![${name}](${image})](${link})`);
 	return badges.join("\n");
 } } };
@@ -216,23 +262,20 @@ function isUrl(text, lenient = true) {
 	if (typeof text !== "string") throw new TypeError("Expected a string");
 	text = text.trim();
 	if (text.includes(" ")) return false;
-	try {
-		new URL(text);
-		return true;
-	} catch {
-		if (lenient) return isUrl(`https://${text}`, false);
-		return false;
-	}
+	if (URL.canParse(text)) return true;
+	if (lenient) return isUrl(`https://${text}`, false);
+	return false;
 }
 //#endregion
 //#region src/lib/readme/rules/code.ts
+const LEADING_DOT_REGEX = /^\./;
 var code_default = { code: { async content(options) {
 	const validOptions = z.object({
 		file: z.string(),
 		language: z.string().optional(),
 		trim: z.boolean().default(true)
 	}).parse(options);
-	const lang = (path.extname(validOptions.file) ?? "").replace(/^\./, "");
+	const lang = (path.extname(validOptions.file) ?? "").replace(LEADING_DOT_REGEX, "");
 	const exampleCode = await fs.readFile(path.join(process.cwd(), validOptions.file), "utf8");
 	return `\`\`\`${lang}\n${validOptions.trim ? exampleCode.trim() : exampleCode}\n\`\`\``;
 } } };
@@ -287,8 +330,9 @@ var title_default = { title: {
 	},
 	order: 2
 } };
+const SPLIT_FOR_TITLE_CASE_REGEX = /[ _-]+/;
 function makeTitleCase(text) {
-	return text.split(/[ _-]+/).filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+	return text.split(SPLIT_FOR_TITLE_CASE_REGEX).filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
 }
 //#endregion
 //#region src/lib/readme/rules/header.ts
@@ -467,6 +511,19 @@ var rules_default = {
 };
 //#endregion
 //#region src/lib/config.ts
+let _configExplorer;
+let _additionalConfigExplorer;
+function getConfigExplorer() {
+	_configExplorer ??= cosmiconfig("mdat", { loaders: { ".ts": TypeScriptLoader() } });
+	return _configExplorer;
+}
+function getAdditionalConfigExplorer() {
+	_additionalConfigExplorer ??= cosmiconfig("mdat", { loaders: {
+		".json": mdatJsonLoader,
+		".ts": TypeScriptLoader()
+	} });
+	return _additionalConfigExplorer;
+}
 /**
 * Load and validate mdat configuration.
 * Uses cosmiconfig to search in the usual places.
@@ -474,11 +531,9 @@ var rules_default = {
 */
 async function loadConfig(options) {
 	const { additionalConfig, defaults = rules_default, searchFrom } = options ?? {};
-	resetReadmeMetadata();
-	resetContextMetadata();
 	let finalConfig = { mdat: `Powered by the Markdown Autophagic Template system: [mdat](https://github.com/kitschpatrol/mdat).` };
 	if (defaults) finalConfig = deepMergeDefined(finalConfig, defaults);
-	const results = await cosmiconfig("mdat", { loaders: { ".ts": TypeScriptLoader() } }).search(searchFrom);
+	const results = await getConfigExplorer().search(searchFrom);
 	if (results) {
 		const { config, filepath } = results;
 		let possibleRules = config;
@@ -493,10 +548,6 @@ async function loadConfig(options) {
 	}
 	if (additionalConfig !== void 0) {
 		const additionalConfigArray = Array.isArray(additionalConfig) ? additionalConfig : [additionalConfig];
-		const configExplorer2 = cosmiconfig("mdat", { loaders: {
-			".json": mdatJsonLoader,
-			".ts": TypeScriptLoader()
-		} });
 		for (const configOrPath of additionalConfigArray) {
 			let loaded;
 			if (typeof configOrPath === "string") {
@@ -505,7 +556,7 @@ async function loadConfig(options) {
 					config: mdatJsonLoader(configOrPath, await fs.readFile(configOrPath, "utf8")),
 					filepath: configOrPath
 				};
-				else results = await configExplorer2.load(configOrPath);
+				else results = await getAdditionalConfigExplorer().load(configOrPath);
 				if (results === null || results === void 0) continue;
 				const { config: loadedConfig, filepath } = results;
 				log.debug(`Loaded additional config from "${filepath}"`);
@@ -541,20 +592,26 @@ function defineConfig(config) {
 }
 //#endregion
 //#region src/lib/format.ts
+let cachedPrettier;
+const configCache = /* @__PURE__ */ new Map();
 /**
 * Format a markdown string with Prettier, using config discovered from the file path.
 * Requires `prettier` to be installed as a peer dependency.
 */
 async function formatWithPrettier(content, filePath) {
-	let prettier;
-	try {
-		prettier = await import("prettier");
+	if (cachedPrettier === void 0) try {
+		cachedPrettier = await import("prettier");
 	} catch {
 		throw new Error("The --format flag requires `prettier` to be installed. Run: pnpm add -D prettier");
 	}
-	const config = await prettier.resolveConfig(filePath ?? process.cwd());
-	if (config) log.debug(`Using Prettier config from "${config.filepath}" for "${filePath ?? process.cwd()}"`);
-	return prettier.format(content, {
+	const configKey = filePath ? path.dirname(filePath) : process.cwd();
+	let config = configCache.get(configKey);
+	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()}"`);
+	}
+	return cachedPrettier.format(content, {
 		...config,
 		filepath: filePath,
 		parser: "markdown"
@@ -595,12 +652,13 @@ function ensureArray(value) {
 	if (value === void 0 || value === null) return [];
 	return Array.isArray(value) ? value : [value];
 }
+const README_SEARCH_REGEX = /^readme(?:\.\w+)?$/i;
 /**
 * Finds a readme file in the current working directory (case-insensitive).
 */
 async function findReadme() {
 	log.debug("Searching for readme in current directory...");
-	const readme = (await fs.readdir(process.cwd())).find((entry) => /^readme(?:\.\w+)?$/i.test(entry));
+	const readme = (await fs.readdir(process.cwd())).find((entry) => README_SEARCH_REGEX.test(entry));
 	if (readme !== void 0) {
 		const absolutePath = path.resolve(readme);
 		log.debug(`Found readme at "${absolutePath}"`);
@@ -616,7 +674,9 @@ async function findReadmeThrows() {
 	if (readme === void 0) throw new Error("No readme found");
 	return readme;
 }
+let cachedAmbientRemarkConfig;
 async function loadAmbientRemarkConfig() {
+	if (cachedAmbientRemarkConfig !== void 0) return cachedAmbientRemarkConfig;
 	const ambientConfig = new Configuration({
 		cwd: process.cwd(),
 		detectConfig: true,
@@ -637,34 +697,50 @@ async function loadAmbientRemarkConfig() {
 		const { filePath } = configResult;
 		if (filePath === void 0) log.debug("No ambient Remark configuration file found");
 		else log.debug(`Found and loaded ambient Remark configuration from "${filePath}"`);
-		return configResult;
+		cachedAmbientRemarkConfig = stripLintPlugins(configResult);
+		return cachedAmbientRemarkConfig;
 	}
 	log.debug("No ambient Remark configuration found");
-	return {
+	cachedAmbientRemarkConfig = {
 		filePath: void 0,
 		plugins: [],
 		settings: {}
 	};
+	return cachedAmbientRemarkConfig;
+}
+/**
+* Strip remark-lint plugins from an ambient config. Lint plugins only produce
+* VFile warnings and never modify the AST or output — running them during
+* expansion is pure overhead.
+*/
+function stripLintPlugins(config) {
+	return {
+		...config,
+		plugins: config.plugins.filter((entry) => {
+			const plugin = Array.isArray(entry) ? entry[0] : entry;
+			if (typeof plugin !== "function") return true;
+			const { name } = plugin;
+			return name !== "remarkLint" && !name.startsWith("remark-lint:") && name !== "remarkValidateLinks";
+		})
+	};
 }
 //#endregion
 //#region src/lib/processors.ts
 async function processFiles(files, loader, processorGetter, name, output, config) {
-	const resolvedConfig = await loader({ additionalConfig: config });
-	const localRemarkConfiguration = await loadAmbientRemarkConfig();
+	const [resolvedConfig, localRemarkConfiguration] = await Promise.all([loader({ additionalConfig: config }), loadAmbientRemarkConfig()]);
 	const inputOutputPaths = await getInputOutputPaths(ensureArray(files), output, name, "md");
-	const results = [];
 	const resolvedProcessor = processorGetter(resolvedConfig, localRemarkConfiguration);
-	for (const { input, name, output } of inputOutputPaths) {
+	return await Promise.all(inputOutputPaths.map(async ({ input, name, output }) => {
 		const inputFile = await read(input);
 		const result = await resolvedProcessor.process(inputFile);
 		result.dirname = output;
 		result.basename = name;
-		results.push(result);
-	}
-	return results;
+		return result;
+	}));
 }
 async function processString(markdown, loader, processorGetter, config) {
-	return processorGetter(await loader({ additionalConfig: config }), await loadAmbientRemarkConfig()).process(new VFile(markdown));
+	const [resolvedConfig, localRemarkConfiguration] = await Promise.all([loader({ additionalConfig: config }), loadAmbientRemarkConfig()]);
+	return processorGetter(resolvedConfig, localRemarkConfiguration).process(new VFile(markdown));
 }
 function getExpandProcessor(config, ambientRemarkConfig) {
 	return remark().use({ settings: {
@@ -860,11 +936,10 @@ async function check(files, config, options) {
 	files ??= await findReadmeThrows();
 	const { read } = await import("to-vfile");
 	const resolvedFiles = Array.isArray(files) ? files : [files];
-	const originals = await Promise.all(resolvedFiles.map(async (f) => read(f)));
-	const results = await processFiles(files, loadConfig, getExpandProcessor, void 0, void 0, config);
+	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() === result.toString(),
+		inSync: originals[i].toString().replaceAll("\r\n", "\n") === result.toString(),
 		result
 	}));
 }
@@ -872,4 +947,4 @@ 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, setLogger };
+export { check, collapse, collapseString, createReadme as create, createReadmeInteractive as createInteractive, defineConfig, expand, expandString, getContextMetadata, getReadmeMetadata, loadConfig, mergeConfig, resetMetadataCaches, setLogger };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdat",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "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",
@@ -48,9 +48,9 @@
     "cosmiconfig-typescript-loader": "^6.2.0",
     "deepmerge-ts": "^7.1.5",
     "globby": "^16.2.0",
-    "lognow": "^0.5.2",
+    "lognow": "^0.6.0",
     "mdast-util-toc": "^7.1.0",
-    "metascope": "^0.4.0",
+    "metascope": "^0.5.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.0",
+    "remark-mdat": "^2.0.2",
     "to-vfile": "^8.0.0",
     "type-fest": "^5.5.0",
     "unified-engine": "^11.2.2",
@@ -69,13 +69,16 @@
   },
   "devDependencies": {
     "@arethetypeswrong/core": "^0.18.2",
-    "@kitschpatrol/shared-config": "^6.2.0",
+    "@kitschpatrol/shared-config": "^7.0.0",
     "@types/mdast": "^4.0.4",
     "@types/node": "~22.17.2",
     "@types/unist": "^3.0.3",
     "@types/yargs": "^17.0.35",
     "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",
     "nanoid": "^5.1.7",
     "prettier": "^3.8.1",
     "publint": "^0.3.18",
@@ -102,11 +105,13 @@
     }
   },
   "scripts": {
+    "bench": "vitest bench --run --compare test/benchmarks/baseline.json",
+    "bench:baseline": "vitest bench --run --outputJson test/benchmarks/baseline.json",
     "build": "tsdown",
     "clean": "git rm -f pnpm-lock.yaml ; git clean -fdX",
     "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",
-    "test": "vitest run --no-file-parallelism"
+    "test": "vitest run"
   }
 }

package/readme.md

@@ -1,5 +1,3 @@
-<!--+ Warning: Content inside HTML comment blocks was generated by mdat and may be overwritten. +-->
-
 <!-- title -->
 
 # mdat
@@ -10,6 +8,7 @@
 
 [![NPM Package mdat](https://img.shields.io/npm/v/mdat.svg)](https://npmjs.com/package/mdat)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/kitschpatrol/mdat/actions/workflows/ci.yml/badge.svg)](https://github.com/kitschpatrol/mdat/actions/workflows/ci.yml)
 
 <!-- /badges -->
 
@@ -229,7 +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.                   |
-| `check`    | `[files..]` `[options]` | Check if MDAT placeholder comments are up to date. Exits with code 1 if any files are out of sync.                  |
+| `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.                                                                         |
 
 _See the sections below for more information on each subcommand._
@@ -285,7 +284,7 @@ mdat collapse [files..] [options]
 
 #### Subcommand: `mdat check`
 
-Check if MDAT placeholder comments are up to date. Exits with code 1 if any files are out of sync.
+Check if MDAT placeholder comments are up to date. Exits with code 1 if any files have stale or unexpanded content.
 
 Usage:
 
@@ -587,7 +586,7 @@ See the [Examples section](https://github.com/kitschpatrol/remark-mdat#examples)
   | File       | Original | Gzip   | Brotli |
   | ---------- | -------- | ------ | ------ |
   | .gitignore | 305 B    | 245 B  | 216 B  |
-  | readme.md  | 18.1 kB  | 6.4 kB | 5.4 kB |
+  | readme.md  | 34.4 kB  | 8.3 kB | 6.9 kB |
 
   <!-- /size-table -->
 
@@ -738,9 +737,9 @@ In 2.x, arguments **must** use function-call syntax with parentheses
 
 ### New functionality
 
-- The new --format flag runs expanded output through Prettier with local configuration before writing.
+- The new `--format` flag runs expanded output through Prettier with local configuration before writing.
 - The badges rule now detects GitHub Actions CI workflows and includes a CI status badge automatically.
-- Check command re-implemented as a simplified dry-run expand + diff (exits 1 if out of sync)
+- Check command reimplemented as a simplified dry-run expand and diff and reporting if content is unexpanded or out of date. Respects the `--format` flag.
 
 ### Rule shape changes
 
@@ -756,14 +755,52 @@ MDAT solves this by turning HTML comments in Markdown into placeholders for dyna
 
 ### Similar projects
 
-- Benjamin Lupton's [projectz](https://github.com/bevry/projectz)
-- David Wells' [Markdown Magic](https://github.com/DavidWells/markdown-magic)
-- Titus Wormer's [mdast-zone](https://github.com/syntax-tree/mdast-zone)
+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/)
+
+- [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)
+
+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