mdat 2.1.0 → 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, mdatCollapse, mdatExpand, mdatSplit, mdatStrip, 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.1.0";
+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();
@@ -883,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]) => ({
@@ -949,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);
@@ -1087,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

@@ -127,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
 /**
@@ -180,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, strip, stripString };
+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, mdatCollapse, mdatExpand, mdatSplit, mdatStrip, 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();
@@ -883,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]) => ({
@@ -972,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, strip, stripString };
+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.1.0",
+  "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",
@@ -58,7 +58,7 @@
     "pretty-ms": "^9.3.0",
     "remark": "^15.0.1",
     "remark-gfm": "^4.0.1",
-    "remark-mdat": "^2.1.0",
+    "remark-mdat": "^2.2.0",
     "to-vfile": "^8.0.0",
     "type-fest": "^5.5.0",
     "unified-engine": "^11.2.2",
@@ -74,11 +74,12 @@
     "@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

@@ -413,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'
@@ -435,8 +425,6 @@ const [file] = await expand('readme.md')
 await write(file)
 ```
 
-#### `expandString`
-
 ```ts
 function expandString(
   markdown: string,
@@ -445,8 +433,6 @@ 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`.
@@ -457,17 +443,9 @@ Strips all MDAT comment tags (both opening and closing) while preserving expande
 
 This is useful for producing a "clean" Markdown file that no longer depends on MDAT for future updates.
 
-#### `check`
-
-```ts
-function check(
-  files?: string | string[],
-  config?: ConfigToLoad,
-  options?: { format?: boolean },
-): Promise<{ inSync: boolean; results: VFile[] }>
-```
+#### `check` / `checkString`
 
-Dry-run expand and compare with the file on disk. Returns `inSync: false` if the file would change.
+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`
 
@@ -816,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.