mdat
Version:
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.
1,200 lines (1,163 loc) • 55.2 kB
JavaScript
#!/usr/bin/env node
import { createLogger, getChildLogger, injectionHelper } from "lognow";
import picocolors from "picocolors";
import prettyMilliseconds from "pretty-ms";
import { getMdatReports, getSoleRule, mdatCollapse, mdatDiff, mdatExpand, mdatSplit, mdatStrip, reporterMdat, rulesSchema, setLogger } from "remark-mdat";
import { read, write } from "to-vfile";
import yargs from "yargs";
import { hideBin } from "yargs/helpers";
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";
import path from "node:path";
import plur from "plur";
import { deepmerge } from "deepmerge-ts";
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";
import { promisify } from "node:util";
import { brotliCompress, gzip } from "node:zlib";
import prettyBytes from "pretty-bytes";
import { toc } from "mdast-util-toc";
import "vfile";
import { Configuration } from "unified-engine";
import untildify from "untildify";
import { confirm, group, intro, note, outro, select } from "@clack/prompts";
//#region package.json
var name = "mdat";
var version = "3.0.0";
//#endregion
//#region src/lib/deep-merge-defined.ts
function stripUndefinedDeep(object) {
if (Array.isArray(object)) return object.map((v) => v !== null && typeof v === "object" ? stripUndefinedDeep(v) : v).filter((v) => v !== void 0);
return Object.entries(object).map(([k, v]) => [k, v !== null && 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
});
setLogger(getChildLogger(log, "remark-mdat"));
setLogger$1(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$2(logger) {
log = injectionHelper(logger);
setLogger(getChildLogger(log, "remark-mdat"));
setLogger$1(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 === "" ? key : `${parentKey}.${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.
*
* @throws {Error} If no package.json is found
*/
async function getContextMetadata() {
if (metascopeMetadata !== void 0) return metascopeMetadata;
metascopeMetadata = await getMetadata({
absolute: false,
offline: true,
recursive: false,
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\+/v;
const GIT_SUFFIX_REGEX = /\.git$/v;
const TRAILING_SLASH_REGEX = /\/$/v;
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 repoUrl = codemeta.codeRepository?.replace(GIT_PREFIX_REGEX, "").replace(GIT_SUFFIX_REGEX, "").replace(TRAILING_SLASH_REGEX, "");
const bin = (() => {
if (nodePackage === void 0) return;
const binField = nodePackage.bin;
if (binField === void 0) return;
if (typeof binField === "string") return [nodePackage.name];
const names = Object.keys(binField);
return names.length > 0 ? names : void 0;
})();
const engines = (() => {
const raw = nodePackage?.engines;
if (raw === void 0) return;
const entries = Object.entries(raw).filter((entry) => entry[1] !== void 0);
return entries.length > 0 ? Object.fromEntries(entries) : void 0;
})();
const peerDependencies = (() => {
if (nodePackage === void 0) return;
const peers = nodePackage.peerDependencies;
if (peers === void 0) return;
const entries = Object.entries(peers).filter((entry) => entry[1] !== void 0);
if (entries.length === 0) return;
const meta = nodePackage.peerDependenciesMeta;
return entries.map(([name, version]) => ({
name,
optional: meta?.[name]?.optional === true,
version
}));
})();
const firstAuthor = helpers.firstOf(helpers.ensureArray(codemeta.author));
return {
author: helpers.firstOf(helpers.mixedStringsToArray(helpers.toBasicNames(codemeta.author))),
authorUrl: firstAuthor?.url,
bin,
ciActionFileName: ciActionFilePath === void 0 ? void 0 : path.basename(ciActionFilePath),
description: codemeta.description,
engines,
isPublicNpmPackage: nodePackage?.private !== true && (nodePackage?.name.startsWith("@") && nodePackage.publishConfig?.access === "public" || true),
issuesUrl: codemeta.issueTracker,
license: helpers.toBasicLicense(helpers.firstOf(helpers.ensureArray(codemeta.license))),
licenseFilePath: licenseFileData?.source,
licenseUrl: licenseFileData?.data.match?.spdxUrl,
name: codemeta.name,
operatingSystem: codemeta.operatingSystem,
peerDependencies,
projectDirectory: metascope?.data.options.path === void 0 ? void 0 : `file://${metascope.data.options.path}`,
repositoryUrl: repoUrl,
runtimePlatform: codemeta.runtimePlatform,
usesPnpm: helpers.usesPnpm(nodePackageJson)
};
});
let readmeMetadata;
/**
* Nice data for readme rules
*
* @public
*/
async function getReadmeMetadata() {
if (readmeMetadata !== void 0) return readmeMetadata;
const contextMetadata = await getContextMetadata();
readmeMetadata = readmeMetadataTemplate(contextMetadata, {});
return readmeMetadata;
}
//#endregion
//#region src/lib/readme/rules/badges.ts
var badges_default = { badges: { async content(options) {
const validOptions = z.object({
custom: z.record(z.string(), z.object({
image: z.string(),
link: z.string()
})).optional(),
npm: z.array(z.string()).optional()
}).optional().parse(options);
const metadata = await getReadmeMetadata();
const { ciActionFileName, license, licenseUrl, name, repositoryUrl } = metadata;
const badges = [];
if (validOptions?.npm === void 0) {
if (metadata.isPublicNpmPackage) badges.push(`[](https://www.npmjs.com/package/${name})`);
} else for (const packageName of validOptions.npm) badges.push(`[](https://www.npmjs.com/package/${packageName})`);
if (license !== void 0 && licenseUrl !== void 0) badges.push(`[![License: ${license}](https://img.shields.io/badge/License-${license.replaceAll("-", "--")}-yellow.svg)](${licenseUrl})`);
if (ciActionFileName !== void 0 && repositoryUrl !== void 0) badges.push(`[](${repositoryUrl}/actions/workflows/${ciActionFileName})`);
if (validOptions?.custom !== void 0) for (const [badgeName, { image, link }] of Object.entries(validOptions.custom)) badges.push(`[](${link})`);
return badges.join("\n");
} } };
//#endregion
//#region src/lib/readme/rules/banner.ts
var banner_default = { banner: { async content(options) {
const validOptions = z.object({
alt: z.string().optional(),
src: z.string().optional()
}).optional().parse(options);
const src = validOptions?.src ?? await getBannerSrc();
if (src === void 0) throw new Error("Banner image not found at any typical location, consider adding something at ./assets/banner.webp");
if (!isUrl(src) && !await isFile(src)) throw new Error(`Banner image not found at "${src}"`);
let alt = validOptions?.alt;
if (alt === void 0) {
const { name: packageName } = await getReadmeMetadata();
if (packageName === void 0) throw new Error("Banner image alt text not available");
alt = `${packageName} banner`;
}
return ``;
} } };
async function getBannerSrc() {
const { projectDirectory } = await getReadmeMetadata();
if (projectDirectory === void 0) throw new Error("No project directory found");
const [firstPath] = await globby([
".",
"assets",
"media",
"readme-assets",
"readme-media",
"readme",
"images",
".github/assets"
].map((location) => path.join(projectDirectory, location)), {
deep: 1,
expandDirectories: {
extensions: [
"png",
"gif",
"jpg",
"jpeg",
"svg",
"webp"
],
files: [
"banner",
"cover",
"demo",
"header",
"hero",
"image",
"logo",
"overview",
"readme",
"screenshot",
"screenshots",
"splash"
]
}
});
return firstPath === void 0 ? void 0 : path.relative(process.cwd(), firstPath);
}
function isUrl(text, lenient = true) {
if (typeof text !== "string") throw new TypeError("Expected a string");
text = text.trim();
if (text.includes(" ")) return false;
if (URL.canParse(text)) return true;
return lenient && URL.canParse(`https://${text}`);
}
//#endregion
//#region src/lib/readme/rules/code.ts
const LEADING_DOT_REGEX = /^\./v;
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(LEADING_DOT_REGEX, "");
const exampleCode = await fs.readFile(path.join(process.cwd(), validOptions.file), "utf8");
return `\`\`\`${lang}\n${validOptions.trim ? exampleCode.trim() : exampleCode}\n\`\`\``;
} } };
//#endregion
//#region src/lib/readme/rules/contributing.ts
var contributing_default = { contributing: { async content() {
const { issuesUrl } = await getReadmeMetadata();
if (issuesUrl === void 0) throw new Error("Could not find \"bugs.url\" entry in package.json");
return [
"## Contributing",
"",
`[Issues](${issuesUrl}) are welcome and appreciated.`,
"",
"Please open an issue to discuss changes before submitting a pull request. Unsolicited PRs (especially AI-generated ones) are unlikely to be merged.",
"",
"This repository uses [@kitschpatrol/shared-config](https://github.com/kitschpatrol/shared-config) (via its `ksc` CLI) for linting and formatting, plus [MDAT](https://github.com/kitschpatrol/mdat) for readme placeholder expansion."
].join("\n");
} } };
//#endregion
//#region src/lib/readme/rules/dependencies.ts
const PLATFORM_INFO = {
bun: {
display: "Bun",
url: "https://bun.sh/"
},
deno: {
display: "Deno",
url: "https://deno.land/"
},
go: {
display: "Go",
url: "https://go.dev/"
},
java: {
display: "Java",
url: "https://www.java.com/"
},
node: {
display: "Node.js",
url: "https://nodejs.org/"
},
python: {
display: "Python",
url: "https://www.python.org/"
},
ruby: {
display: "Ruby",
url: "https://www.ruby-lang.org/"
},
rust: {
display: "Rust",
url: "https://www.rust-lang.org/"
}
};
var dependencies_default = { dependencies: { async content() {
const { engines, operatingSystem, peerDependencies, runtimePlatform } = await getReadmeMetadata();
const platformItems = [];
if (engines !== void 0) for (const [name, version] of Object.entries(engines)) {
const info = PLATFORM_INFO[name.toLowerCase()];
const display = info ? `[${info.display}](${info.url})` : name;
platformItems.push(`- ${display} ${version}`);
}
if (runtimePlatform !== void 0) for (const entry of runtimePlatform) {
const spaceIndex = entry.indexOf(" ");
const platformKey = spaceIndex > 0 ? entry.slice(0, spaceIndex) : entry;
const version = spaceIndex > 0 ? entry.slice(spaceIndex + 1) : void 0;
if (engines?.[platformKey] !== void 0) continue;
const info = PLATFORM_INFO[platformKey.toLowerCase()];
const display = info ? `[${info.display}](${info.url})` : platformKey;
platformItems.push(version === void 0 || version === "" ? `- ${display}` : `- ${display} ${version}`);
}
if (operatingSystem !== void 0 && operatingSystem.length > 0) platformItems.push(`- Supported platforms: ${operatingSystem.join(", ")}`);
const peerItems = [];
if (peerDependencies !== void 0) for (const { name, optional, version } of peerDependencies) {
const npmUrl = `https://www.npmjs.com/package/${name}`;
const optionalSuffix = optional ? " _(optional)_" : "";
peerItems.push(`- [${name}](${npmUrl}) ${version}${optionalSuffix}`);
}
const hasPlatform = platformItems.length > 0;
const hasPeers = peerItems.length > 0;
if (!hasPlatform && !hasPeers) return "";
const sections = ["## Dependencies"];
if (hasPlatform && hasPeers) sections.push("", "### Platform", "", ...platformItems, "", "### Peer Dependencies", "", ...peerItems);
else if (hasPlatform) sections.push("", ...platformItems);
else sections.push("", ...peerItems);
return sections.join("\n");
} } };
//#endregion
//#region src/lib/readme/rules/description.ts
/**
* Simple alias for short-description
*/
var description_default = { description: { async content() {
const { description } = await getReadmeMetadata();
if (description === void 0) throw new Error("Could not find \"description\" entry in package.json");
return `**${description}**`;
} } };
//#endregion
//#region src/lib/readme/rules/license.ts
var license_default = { license: { async content() {
const { author, authorUrl, license, licenseFilePath } = await getReadmeMetadata();
if (author === void 0) throw new Error("Could not find author name in project");
if (license === void 0 || licenseFilePath === void 0) throw new Error("Could not find license for project");
return `## License\n[${license}](${licenseFilePath}) © ${authorUrl === void 0 ? author : `[${author}](${authorUrl})`}`;
} } };
//#endregion
//#region src/lib/readme/rules/footer.ts
var footer_default = { footer: { content: [getSoleRule(contributing_default), getSoleRule(license_default)] } };
//#endregion
//#region src/lib/readme/rules/short-description.ts
/**
* Simple alias for `description` rule, to match nomenclature in
* [standard-readme](https://github.com/RichardLitt/standard-readme/blob/main/spec.md#short-description)
* spec.
*/
var short_description_default = { "short-description": getSoleRule(description_default) };
//#endregion
//#region src/lib/readme/rules/title.ts
var title_default = { title: {
async content(options) {
const { postfix, prefix, titleCase } = z.object({
postfix: z.string().optional().default(""),
prefix: z.string().optional().default(""),
titleCase: z.boolean().optional().default(false)
}).parse(options ?? {});
const { name: packageName } = await getReadmeMetadata();
if (packageName === void 0) throw new Error("Could not find project name");
return `# ${prefix}${titleCase ? makeTitleCase(packageName) : packageName}${postfix}`;
},
order: 2
} };
const SPLIT_FOR_TITLE_CASE_REGEX = /[ _\-]+/v;
function makeTitleCase(text) {
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
var header_default = { header: {
content: [
getSoleRule(title_default),
getSoleRule(banner_default),
getSoleRule(badges_default),
getSoleRule(short_description_default)
],
order: 2
} };
//#endregion
//#region src/lib/readme/rules/install.ts
var install_default = { install: { async content() {
const { bin, engines, isPublicNpmPackage, name, runtimePlatform, usesPnpm } = await getReadmeMetadata();
if (name === void 0) throw new Error("Could not find project name");
const lines = ["## Install"];
if (isPublicNpmPackage || engines?.node !== void 0 || runtimePlatform?.includes("node")) {
const pmAdd = usesPnpm ? "pnpm add" : "npm install";
const pmx = usesPnpm ? "pnpx" : "npx";
lines.push("", "```sh", `${pmAdd} ${name}`, "```");
if (bin !== void 0 && bin.length > 0) lines.push("", "Or run it directly:", "", "```sh", `${pmx} ${name}`, "```");
} else if (runtimePlatform?.some((p) => p.startsWith("python"))) lines.push("", "```sh", `pip install ${name}`, "```");
else if (runtimePlatform?.some((p) => p.startsWith("rust"))) lines.push("", "```sh", `cargo install ${name}`, "```");
else if (runtimePlatform?.some((p) => p.startsWith("go"))) lines.push("", "```sh", `go install ${name}@latest`, "```");
else if (runtimePlatform?.some((p) => p.startsWith("ruby"))) lines.push("", "```sh", `gem install ${name}`, "```");
else throw new Error("Could not determine project ecosystem for install instructions");
return lines.join("\n");
} } };
//#endregion
//#region src/lib/readme/rules/utilities/size/size-report.ts
const brotliCompressAsync = promisify(brotliCompress);
const gzipCompressAsync = promisify(gzip);
/**
* Creates a SizeInfo object with formatted values
*
* @param bytes - Size in bytes
* @param originalSize - Original file size for percentage calculation
*/
function createSizeInfo(bytes, originalSize) {
const percent = originalSize === 0 ? 0 : (originalSize - bytes) / originalSize * 100;
return {
bytes,
bytesPretty: prettyBytes(bytes, { maximumFractionDigits: 1 }),
percent,
percentPretty: `${Math.round(percent)}%`
};
}
/**
* Analyzes a file's size and its compressed sizes using Brotli and Gzip
*
* @param filePath - Path to the file to analyze
*
* @returns Promise containing detailed size report
* @throws {Error} If file cannot be read or compressed
*/
async function createSizeReport(filePath) {
try {
const fileContent = await fs.readFile(filePath);
const originalSize = fileContent.length;
const [brotliCompressed, gzipCompressed] = await Promise.all([brotliCompressAsync(fileContent), gzipCompressAsync(fileContent)]);
return {
brotli: createSizeInfo(brotliCompressed.length, originalSize),
gzip: createSizeInfo(gzipCompressed.length, originalSize),
original: createSizeInfo(originalSize, originalSize)
};
} catch (error) {
throw new Error(`Failed to analyze file: ${error instanceof Error ? error.message : "Unknown error"}`, { cause: error });
}
}
//#endregion
//#region src/lib/readme/rules/size.ts
const optionsSchema$1 = z.object({
compression: z.enum([
"none",
"brotli",
"gzip"
]).optional().default("none"),
file: z.string()
});
function getSizeForCompression(report, compression) {
switch (compression) {
case "brotli": return report.brotli.bytesPretty;
case "gzip": return report.gzip.bytesPretty;
case "none": return report.original.bytesPretty;
}
}
var size_default = { size: { async content(options) {
const validOptions = optionsSchema$1.parse(options);
return getSizeForCompression(await createSizeReport(path.join(process.cwd(), validOptions.file)), validOptions.compression);
} } };
//#endregion
//#region src/lib/readme/rules/size-table.ts
const fileSchema = z.union([z.string(), z.array(z.string())]).transform((files) => Array.isArray(files) ? files : [files]);
const optionsSchema = z.union([z.object({
brotli: z.boolean().optional().default(true),
file: fileSchema,
gzip: z.boolean().optional().default(true),
original: z.boolean().optional().default(true),
showPercentage: z.boolean().optional().default(false)
}), z.object({
brotli: z.boolean().optional().default(true),
files: fileSchema,
gzip: z.boolean().optional().default(true),
original: z.boolean().optional().default(true),
showPercentage: z.boolean().optional().default(false)
})]).transform((options) => {
if ("file" in options) {
const { file, ...rest } = options;
return {
files: file,
...rest
};
}
return options;
});
function formatMarkdownTable(reports, options) {
const headers = ["File"];
if (options.original) headers.push("Original");
if (options.gzip) headers.push("Gzip");
if (options.brotli) headers.push("Brotli");
const separators = headers.map(() => "---");
const rows = reports.map(([file, report]) => {
const row = [path.basename(file)];
if (options.original) row.push(report.original.bytesPretty);
if (options.gzip) row.push(options.showPercentage ? `${report.gzip.bytesPretty} (${report.gzip.percentPretty})` : report.gzip.bytesPretty);
if (options.brotli) row.push(options.showPercentage ? `${report.brotli.bytesPretty} (${report.brotli.percentPretty})` : report.brotli.bytesPretty);
return row;
});
return [
`| ${headers.join(" | ")} |`,
`| ${separators.join(" | ")} |`,
...rows.map((row) => `| ${row.join(" | ")} |`)
].join("\n");
}
var size_table_default = { "size-table": { async content(options) {
const validOptions = optionsSchema.parse(options);
return formatMarkdownTable(await Promise.all(validOptions.files.map(async (file) => {
return [file, await createSizeReport(path.join(process.cwd(), file))];
})), {
brotli: validOptions.brotli,
gzip: validOptions.gzip,
original: validOptions.original,
showPercentage: validOptions.showPercentage
});
} } };
//#endregion
//#region src/lib/readme/rules/table-of-contents.ts
var table_of_contents_default = { "table-of-contents": {
async content(options, { tree }) {
const result = toc(tree, {
heading: null,
maxDepth: z.object({ depth: z.union([
z.literal(1),
z.literal(2),
z.literal(3),
z.literal(4),
z.literal(5),
z.literal(6)
]).optional() }).optional().parse(options)?.depth ?? 3,
tight: true
});
if (result.map === void 0) throw new Error("Could not generate table of contents");
const heading = `## Table of contents`;
const rootWrapper = {
children: result.map.children,
type: "root"
};
return [heading, remark().use(remarkGfm).stringify(rootWrapper).replaceAll("\n\n", "\n")].join("\n");
},
order: 1
} };
//#endregion
//#region src/lib/readme/rules/toc.ts
/**
* Simple alias for table-of-contents
*/
var toc_default = { toc: getSoleRule(table_of_contents_default) };
//#endregion
//#region src/lib/readme/rules/index.ts
var rules_default = {
...badges_default,
...banner_default,
...code_default,
...contributing_default,
...dependencies_default,
...description_default,
...footer_default,
...header_default,
...install_default,
...license_default,
...short_description_default,
...size_default,
...size_table_default,
...table_of_contents_default,
...title_default,
...toc_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. Merge precedence: Base Defaults < Defaults < Searched Config <
* Additional Config
*/
async function loadConfig(options) {
const { additionalConfig, defaults = rules_default, searchFrom } = options ?? {};
let finalConfig = { mdat: `Powered by the Markdown Autophagic Template system: [mdat](https://github.com/kitschpatrol/mdat).` };
finalConfig = deepMergeDefined(finalConfig, defaults);
const results = await getConfigExplorer().search(searchFrom);
if (results) {
const { config, filepath } = results;
let possibleRules = config;
log.debug(`Using config from "${filepath}"`);
if (typeof config === "string" && filepath.endsWith("package.json")) {
log.debug(`Detected shared config string: "${config}"`);
const { default: sharedConfig } = await import(config);
possibleRules = sharedConfig;
}
const validated = validateConfig(possibleRules);
if (validated) finalConfig = deepMergeDefined(finalConfig, validated);
}
if (additionalConfig !== void 0) {
const additionalConfigArray = Array.isArray(additionalConfig) ? additionalConfig : [additionalConfig];
for (const configOrPath of additionalConfigArray) {
let loaded;
if (typeof configOrPath === "string") {
let loadResults;
if (path.basename(configOrPath).endsWith("package.json")) loadResults = {
config: mdatJsonLoader(configOrPath, await fs.readFile(configOrPath, "utf8")),
filepath: configOrPath
};
else loadResults = await getAdditionalConfigExplorer().load(configOrPath);
if (loadResults === null || loadResults === void 0) continue;
const { config: loadedConfig, filepath } = loadResults;
log.debug(`Loaded additional config from "${filepath}"`);
loaded = loadedConfig;
} else loaded = configOrPath;
if (loaded === void 0) continue;
log.debug("Merging config");
const validated = validateConfig(loaded);
if (validated) finalConfig = deepMergeDefined(finalConfig, validated);
}
}
const prettyRules = Object.keys(finalConfig).toSorted().map((rule) => `"${picocolors.green(picocolors.bold(rule))}"`);
log.debug(`Loaded ${picocolors.bold(prettyRules.length)} mdat comment expansion ${plur("rule", prettyRules.length)}:`);
for (const rule of prettyRules) log.debug(`\t${rule}`);
return finalConfig;
}
function validateConfig(value) {
if (rulesSchema.safeParse(value).success) return value;
log.warn(`Config has the wrong shape. Ignoring and using default configuration:\n${JSON.stringify(value, void 0, 2)}`);
}
//#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) {
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 configKey = filePath === void 0 || filePath === "" ? process.cwd() : path.dirname(filePath);
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(`Resolved Prettier config for "${configKey}"`);
}
return cachedPrettier.format(content, {
...config,
filepath: filePath,
parser: "markdown"
});
}
//#endregion
//#region src/lib/utilities.ts
function zeroPad(n, nMax) {
const places = nMax === 0 ? 1 : Math.floor(Math.log10(Math.abs(nMax)) + 1);
return n.toString().padStart(places, "0");
}
async function getInputOutputPaths(inputs, output, name, extension) {
const paths = [];
for (const [index, file] of inputs.entries()) {
const inputOutputPath = await getInputOutputPath(file, output, name, extension, name !== void 0 && name !== "" && inputs.length > 1 ? `-${zeroPad(index + 1, inputs.length)}` : "");
paths.push(inputOutputPath);
}
return paths;
}
async function getInputOutputPath(input, output, name, extension, nameSuffix = "") {
const resolvedInput = expandPath(input);
if (!isFileSync(resolvedInput)) throw new Error(`Input file not found: "${resolvedInput}"`);
const resolvedOutput = output === void 0 || output === "" ? void 0 : expandPath(output);
if (resolvedOutput !== void 0) {
if (isFileSync(resolvedOutput)) throw new Error(`Output path must be a directory, received a file path: "${resolvedOutput}"`);
await fs.mkdir(resolvedOutput, { recursive: true });
}
return {
input: resolvedInput,
name: `${name === void 0 || name === "" ? path.basename(resolvedInput, path.extname(resolvedInput)) : path.basename(name, path.extname(name))}${nameSuffix}${extension === void 0 ? name !== void 0 && path.extname(name) !== "" ? path.extname(name) : path.extname(input) : `.${extension}`}`,
output: resolvedOutput ?? path.dirname(resolvedInput)
};
}
function expandPath(file) {
return untildify(file);
}
function ensureArray(value) {
if (value === void 0 || value === null) return [];
return Array.isArray(value) ? value : [value];
}
const README_SEARCH_REGEX = /^readme(?:\.\w+)?$/iv;
/**
* 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_SEARCH_REGEX.test(entry));
if (readme !== void 0) {
const absolutePath = path.resolve(readme);
log.debug(`Found readme at "${absolutePath}"`);
return absolutePath;
}
}
/**
* Searches up for a readme.md file.
*
* @throws {Error} If no readme is found
*/
async function findReadmeThrows() {
const readme = await findReadme();
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,
packageField: "remarkConfig",
rcName: ".remarkrc"
});
const configResult = await new Promise((resolve) => {
ambientConfig.load("", (error, result) => {
if (error) {
log.error(String(error));
resolve(void 0);
return;
}
resolve(result);
});
});
if (configResult) {
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}"`);
cachedAmbientRemarkConfig = stripLintPlugins(configResult);
return cachedAmbientRemarkConfig;
}
log.debug("No ambient Remark configuration found");
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, localRemarkConfig] = await Promise.all([loader({ additionalConfig: config }), loadAmbientRemarkConfig()]);
const inputOutputPaths = await getInputOutputPaths(ensureArray(files), output, name, "md");
const resolvedProcessor = processorGetter(resolvedConfig, localRemarkConfig);
return await Promise.all(inputOutputPaths.map(async ({ input, name: outputName, output: outputDirectory }) => {
const inputFile = await read(input);
const result = await resolvedProcessor.process(inputFile);
result.dirname = outputDirectory;
result.basename = outputName;
return result;
}));
}
function getExpandProcessor(config, ambientRemarkConfig) {
return remark().use({ settings: {
bullet: "-",
emphasis: "_"
} }).use(remarkGfm).use(ambientRemarkConfig).use(() => async function(tree, file) {
mdatSplit(tree, file);
mdatCollapse(tree, file);
await mdatExpand(tree, file, config);
});
}
function getCollapseProcessor(_config, ambientRemarkConfig) {
return remark().use({ settings: {
bullet: "-",
emphasis: "_"
} }).use(remarkGfm).use(ambientRemarkConfig).use(() => function(tree, file) {
mdatSplit(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
//#region src/lib/readme/templates/mdat-readme-compound.md?raw
var mdat_readme_compound_default = "<!-- header -->\n\n<!-- table-of-contents -->\n\n## Overview\n\n## Getting started\n\n### Dependencies\n\n### Installation\n\n## Usage\n\n### Library\n\n#### API\n\n#### Examples\n\n### CLI\n\n#### Commands\n\n#### Examples\n\n## Background\n\n### Motivation\n\n### Implementation notes\n\n### Similar projects\n\n## The future\n\n## Maintainers\n\n_List maintainer(s) for a repository, along with one way of contacting them (e.g. GitHub link or email)._\n\n## Acknowledgments\n\n_State anyone or anything that significantly helped with the development of your project. State public contact hyper-links if applicable._\n\n<!-- footer -->\n";
//#endregion
//#region src/lib/readme/templates/mdat-readme.md?raw
var mdat_readme_default = "<!-- title -->\n\n<!-- banner -->\n\n<!-- badges -->\n\n<!-- short-description -->\n\n<!-- table-of-contents -->\n\n## Overview\n\n## Getting started\n\n### Dependencies\n\n### Installation\n\n## Usage\n\n### Library\n\n#### API\n\n#### Examples\n\n### CLI\n\n#### Commands\n\n#### Examples\n\n## Background\n\n### Motivation\n\n### Implementation notes\n\n### Similar projects\n\n## The future\n\n## Maintainers\n\n_List maintainer(s) for a repository, along with one way of contacting them (e.g. GitHub link or email)._\n\n## Acknowledgments\n\n_State anyone or anything that significantly helped with the development of your project. State public contact hyper-links if applicable._\n\n<!-- contributing -->\n\n<!-- license -->\n";
//#endregion
//#region src/lib/readme/templates/standard-readme-basic-compound.md?raw
var standard_readme_basic_compound_default = "<!-- header -->\n\n## Install\n\n```sh\n# Code block illustrating how to install.\n```\n\n## Usage\n\n```ts\n// Code block illustrating common usage.\n// Consider using the <!-- code({ src: \"path/to/example.ts\" }) --> comment as well.\n```\n\n<!-- footer -->\n";
//#endregion
//#region src/lib/readme/templates/standard-readme-basic.md?raw
var standard_readme_basic_default = "<!-- title -->\n\n<!-- short-description -->\n\n<!-- table-of-contents -->\n\n## Install\n\n```sh\n# Code block illustrating how to install.\n```\n\n## Usage\n\n```ts\n// Code block illustrating common usage.\n// Consider using the <!-- code({ src: \"path/to/example.ts\" })--> comment as well.\n```\n\n<!-- contributing -->\n\n<!-- license -->\n";
//#endregion
//#region src/lib/readme/templates/standard-readme-full-compound.md?raw
var standard_readme_full_compound_default = "<!-- header -->\n\n_Long description goes here._\n\n_No heading. Cover the main reasons for building the repository. This should describe your module in broad terms, generally in just a few paragraphs; more detail of the module's routines or methods, lengthy code examples, or other in-depth material should be given in subsequent sections._\n\n<!-- table-of-contents -->\n\n## Background\n\n_Cover motivation. Cover abstract dependencies. Cover intellectual provenance: A See Also section is also fitting._\n\n### See also\n\n## Install\n\n```sh\n# Code block illustrating how to install.\n```\n\n### Dependencies\n\n_Required if there are unusual dependencies or dependencies that must be manually installed._\n\n## Usage\n\n```ts\n// Code block illustrating common usage.\n// Consider using the <!-- code({ src: \"path/to/example.ts\" })--> comment as well.\n```\n\n```ts\n// If importable, code block indicating both import functionality and usage.\n```\n\n### CLI\n\n```ts\n// If CLI compatible, code block indicating common usage.\n```\n\n## _Extra Sections (Rename)_\n\n## Security\n\n## API\n\n_Describe exported functions and objects._\n\n- _Describe signatures, return types, callbacks, and events._\n- _Cover types covered where not obvious._\n- _Describe caveats._\n- _If using an external API generator (like go-doc, js-doc, or so on), point to an external API.md file. This can be the only item in the section, if present._\n\n## Maintainers\n\n_List maintainer(s) for a repository, along with one way of contacting them (e.g. GitHub link or email)._\n\n## Thanks\n\n_State anyone or anything that significantly helped with the development of your project. State public contact hyper-links if applicable._\n\n<!-- footer -->\n";
//#endregion
//#region src/lib/readme/templates/standard-readme-full.md?raw
var standard_readme_full_default = "<!-- title -->\n\n<!-- banner -->\n\n<!-- badges -->\n\n<!-- short-description -->\n\n_Long description goes here._\n\n_No heading. Cover the main reasons for building the repository. This should describe your module in broad terms, generally in just a few paragraphs; more detail of the module's routines or methods, lengthy code examples, or other in-depth material should be given in subsequent sections._\n\n<!-- table-of-contents -->\n\n## Background\n\n_Cover motivation. Cover abstract dependencies. Cover intellectual provenance: A See Also section is also fitting._\n\n### See also\n\n## Install\n\n```sh\n# Code block illustrating how to install.\n```\n\n### Dependencies\n\n_Required if there are unusual dependencies or dependencies that must be manually installed._\n\n## Usage\n\n```ts\n// Code block illustrating common usage.\n// Consider using the <!-- code({ src: \"path/to/example.ts\" })--> comment as well.\n```\n\n```ts\n// If importable, code block indicating both import functionality and usage.\n```\n\n### CLI\n\n```ts\n// If CLI compatible, code block indicating common usage.\n```\n\n## _Extra Sections (Rename)_\n\n## Security\n\n## API\n\n_Describe exported functions and objects._\n\n- _Describe signatures, return types, callbacks, and events._\n- _Cover types covered where not obvious._\n- _Describe caveats._\n- _If using an external API generator (like go-doc, js-doc, or so on), point to an external API.md file. This can be the only item in the section, if present._\n\n## Maintainers\n\n_List maintainer(s) for a repository, along with one way of contacting them (e.g. GitHub link or email)._\n\n## Thanks\n\n_State anyone or anything that significantly helped with the development of your project. State public contact hyper-links if applicable._\n\n<!-- contributing -->\n\n<!-- license -->\n";
//#endregion
//#region src/lib/readme/templates/index.ts
var templates_default = {
"MDAT Readme": {
content: {
compound: mdat_readme_compound_default,
explicit: mdat_readme_default
},
description: "The house style. An expansive starting point. Prune to your context and taste.",
exampleLink: "https://github.com/kitschpatrol/mdat/blob/main/readme.md"
},
"Standard Readme Basic": {
content: {
compound: standard_readme_basic_compound_default,
explicit: standard_readme_basic_default
},
description: "Includes only the \"required\" sections from the Standard Readme specification.",
exampleLink: "https://github.com/RichardLitt/standard-readme/blob/main/example-readmes/minimal-readme.md"
},
"Standard Readme Full": {
content: {
compound: standard_readme_full_compound_default,
explicit: standard_readme_full_default
},
description: "Includes all sections from the Standard Readme specification.",
exampleLink: "https://github.com/RichardLitt/standard-readme/blob/main/example-readmes/maximal-readme.md"
}
};
//#endregion
//#region src/lib/readme/create.ts
/**
* Creates a new readme file interactively.
*
* @returns Path to the created readme file.
*/
async function createReadmeInteractive() {
const readmePath = await findReadme();
intro(`Running ${picocolors.bold("mdat create")} interactively`);
const newReadmePath = await createReadme(await group({
async overwrite() {
if (readmePath === void 0) return true;
if (await confirm({
message: `Found an existing readme at "${picocolors.blue(readmePath)}". Do you want to overwrite it?`,
active: "Overwrite",
inactive: "Exit"
}) === false) throw new Error("`mdat create` was cancelled to avoid an overwrite - no changes were made");
return true;
},
template: async () => select({
message: "Which template would you like to use?",
options: getTemplateOptions()
}),
compound: async () => select({
message: "Do you want to use \"compound comments\" where possible, which combine several expansions into a single comment block?",
options: [{
label: `Yes: Combine things like ${picocolors.green("<!-- title -->")} and ${picocolors.green("<!-- badges -->")} in a single ${picocolors.green("<!-- header -->")} comment.`,
value: true
}, {
label: "No: Use individual MDAT expansion comments for each section.",
value: false
}]
}),
expand: async () => confirm({
initialValue: true,
message: "Do you want to run `mdat expand` now to expand the template with content from your project metadata?"
})
}, { onCancel() {
throw new Error("`mdat create` was cancelled - no changes were made");
} }));
note(`Readme created: "${picocolors.blue(picocolors.bold(newReadmePath))}"`);
outro("Done!");
return newReadmePath;
}
/**
* Creates a new readme file with the given options.
*
* @returns Path to the created readme file.
*/
async function createReadme(options) {
const resolvedOptions = deepMergeDefined({
compound: true,
output: process.cwd(),
overwrite: true,
expand: true,
template: Object.keys(templates_default)[0]
}, options ?? {});
const templateString = getTemplateForConfig(resolvedOptions.template, resolvedOptions.compound);
const readmePath = path.join(resolvedOptions.output, "readme.md");
if (!resolvedOptions.overwrite) {
let exists = true;
try {
await fs.access(readmePath);
} catch {
exists = false;
}
if (exists) throw new Error(`Readme already exists at "${readmePath}". Use the overwrite option to replace it.`);
}
await fs.writeFile(readmePath, templateString, "utf8");
if (resolvedOptions.expand) {
const [result] = await expand(readmePath);
if (result === void 0) throw new Error(`Failed to expand readme at "${readmePath}"`);
await write(result);
}
return readmePath;
}
function getTemplateForConfig(templateKey, compound) {
if (!Object.hasOwn(templates_default, templateKey)) 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]) => ({
label: key,
hint: value.description,
value: key
}));
}
//#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
*/
async function expand(files, name, output, config, options) {
files ??= await findReadmeThrows();
const results = await processFiles(files, loadConfig, getExpandProcessor, name, output, config);
if (options?.format) await formatResults(results);
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
*/
async function collapse(files, name, output, config, options) {
files ??= await findReadmeThrows();
const results = await processFiles(files, loadConfig, getCollapseProcessor, name, output, config);
if (options?.format) await formatResults(results);
return results;
}
/**
* 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();
const { read } = await import("to-vfile");
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) => {
const original = originals[i];
if (original === void 0) throw new Error(`Missing original file for comparison at index ${i}`);
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 : file.path);
}
//#endregion
//#region src/bin/options.ts
const nameOption = { name: {
alias: "n",
defaultDescription: "Same name as input file. Overwrites the input file.",
description: "Output file name.",
type: "string"
} };
const outputOption = { output: {
alias: "o",
defaultDescription: "Same directory as input file.",
description: "Output file directory.",
type: "string"
} };
const printOption = { print: {
description: "Print the expanded Markdown to stdout instead of saving to a file. Ignores `--output` and `--name` options.",
type: "boolean"
} };
const configOption = { config: {
alias: "c",
description: "Path(s) to additional mdat configuration files.",
string: true,
type: "array"
} };
const formatOption = { format: {
alias: "f",
description: "Format the output with Prettier. Discovers Prettier config from the file path. Requires `prettier` as a peer dependency.",
type: "boolean"
} };
const verboseOption = { verbose: {
describe: "Enable verbose logging. All verbose logs are prefixed with their log level and are printed to stderr for ease of redirection.",
type: "boolean"
} };
const filesPositional = ["files", {
array: true,
demandOption: false,
describe: "Markdown file(s) with MDAT placeholder comments. If not provided, the closest readme.md file is used.",
type: "string"
}];
const interactiveOption = { interactive: {
alias: "i",
default: true,
description: "Run the guided interactive `create` process. Set explicitly to `false` to use default values and skip the prompt.",
type: "boolean"
} };
const overwriteOption = { overwrite: {
default: false,
defaultDescription: "`false`, if an existing readme is found, don't touch it.",
description: "Replace an existing readme file if one is found.",
type: "boolean"
} };
const expandOption = { expand: {
alias: "e",
default: true,
description: "Automatically run `mdat` immediately after creating the readme template.",
type: "boolean"
} };
const templateOption = { template: {
alias: "t",
choices: Object.keys(templates_default),
default: Object.keys(templates_default)[0],
description: "Specify a template to use for the new readme.",
type: "string"
} };
const compoundOption = { compound: {
default: true,
description: "Use compound comment version of the template to replace several individual comment placeholders where possible. This combines things like `<!-- title -->`, `<!-- badges -->`, etc. in a single `<!-- header -->` comment. It's less clutter when you're editing, but it's also less explicit. The final read