mdat 3.2.2 → 3.4.0

package/dist/bin/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { S as version, a as expand, b as setLogger$1, d as templates_default, f as ensureArray, l as createReadme, r as collapse, s as strip, t as check, u as createReadmeInteractive, x as name, y as log } from "../lib-BEZJR3k_.js";
+import { S as version, a as expand, b as setLogger$1, d as templates_default, f as ensureArray, l as createReadme, r as collapse, s as strip, t as check, u as createReadmeInteractive, x as name, y as log } from "../lib-D8QaJZ-l.js";
 import { createLogger } from "lognow";
 import picocolors from "picocolors";
 import prettyMilliseconds from "pretty-ms";

package/dist/lib/index.d.ts

@@ -169,6 +169,10 @@ declare const readmeMetadataTemplate: import("metascope").Template<{
   engines: {
     [k: string]: string;
   } | undefined;
+  hasTypes: boolean;
+  homebrewFormula: string | undefined;
+  isLibrary: boolean;
+  isNodePackage: boolean;
   isPublicNpmPackage: boolean;
   issuesUrl: string | undefined;
   license: string | undefined;
@@ -185,7 +189,6 @@ declare const readmeMetadataTemplate: import("metascope").Template<{
   repositoryUrl: string | undefined;
   runtimePlatform: string[] | undefined;
   usesGitLfs: boolean;
-  usesPnpm: boolean;
 }>;
 type ReadmeMetadata = ReturnType<typeof readmeMetadataTemplate>;
 /**
@@ -212,6 +215,10 @@ export declare function getReadmeMetadata(): Promise<{
   engines: {
     [k: string]: string;
   } | undefined;
+  hasTypes: boolean;
+  homebrewFormula: string | undefined;
+  isLibrary: boolean;
+  isNodePackage: boolean;
   isPublicNpmPackage: boolean;
   issuesUrl: string | undefined;
   license: string | undefined;
@@ -228,7 +235,6 @@ export declare function getReadmeMetadata(): Promise<{
   repositoryUrl: string | undefined;
   runtimePlatform: string[] | undefined;
   usesGitLfs: boolean;
-  usesPnpm: boolean;
 }>;
 /**
  * Reset all cached metadata. Call between tests or when the underlying project

package/dist/lib/index.js

@@ -1,3 +1,3 @@
-import { _ as getReadmeMetadata, a as expand, b as setLogger, c as stripString, g as getContextMetadata, h as mergeConfig, i as collapseString, l as createReadme, m as loadConfig, n as checkString, o as expandString, p as defineConfig, r as collapse, s as strip, t as check, u as createReadmeInteractive, v as resetMetadataCaches } from "../lib-BEZJR3k_.js";
+import { _ as getReadmeMetadata, a as expand, b as setLogger, c as stripString, g as getContextMetadata, h as mergeConfig, i as collapseString, l as createReadme, m as loadConfig, n as checkString, o as expandString, p as defineConfig, r as collapse, s as strip, t as check, u as createReadmeInteractive, v as resetMetadataCaches } from "../lib-D8QaJZ-l.js";
 
 export { check, checkString, collapse, collapseString, createReadme as create, createReadmeInteractive as createInteractive, defineConfig, expand, expandString, getContextMetadata, getReadmeMetadata, loadConfig, mergeConfig, resetMetadataCaches, setLogger, strip, stripString };

package/dist/{lib-BEZJR3k_.js → lib-D8QaJZ-l.js}

@@ -9,7 +9,7 @@ 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 { deepmergeCustom } from "deepmerge-ts";
 import { defineTemplate, getMetadata, helpers, setLogger as setLogger$1, templates } from "metascope";
 import { z } from "zod";
 import { globby } from "globby";
@@ -25,10 +25,11 @@ import { confirm, group, intro, note, outro, select } from "@clack/prompts";
 
 //#region package.json
 var name = "mdat";
-var version = "3.2.2";
+var version = "3.4.0";
 
 //#endregion
 //#region src/lib/deep-merge-defined.ts
+const deepmerge = deepmergeCustom({ mergeArrays: false });
 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 : {
@@ -139,6 +140,57 @@ const GIT_PREFIX_REGEX = /^git\+/v;
 const GIT_SUFFIX_REGEX = /\.git$/v;
 const TRAILING_SLASH_REGEX = /\/$/v;
 const PACKAGE_MANAGER_REGEX = /^(?<name>[^@]+)@(?<version>[^+]+)/v;
+const BREWPUB_TAP_REGEX = /\bbrewpub\b[^&;]*?--tap[ =](?<tap>[\w.\-\/]+)/v;
+const BREWPUB_NAME_REGEX = /\bbrewpub\b[^&;]*?--name[ =](?<name>[\w.\-\/@+]+)/v;
+const HOMEBREW_TAP_PREFIX_REGEX = /^homebrew-/v;
+/**
+* True if the package.json `exports` field declares a `types` condition
+* anywhere in its (possibly nested) structure.
+*/
+function containsTypesKey(exports) {
+	return typeof exports === "object" && exports !== null && Object.entries(exports).some(([key, value]) => key === "types" || containsTypesKey(value));
+}
+/**
+* True if the package is importable as a library, as opposed to a CLI-only
+* package that only exposes a `bin`.
+*/
+function isLibraryPackage(nodePackage) {
+	return nodePackage !== void 0 && [
+		nodePackage.exports,
+		nodePackage.main,
+		nodePackage.module,
+		nodePackage.types
+	].some((entry) => entry !== void 0);
+}
+/**
+* Supported operating systems from the package.json `os` field, which codemeta
+* doesn't carry. Exclusions like `!win32` are ignored since they don't name a
+* supported platform.
+*/
+function getSupportedOperatingSystems(os) {
+	const supported = helpers.ensureArray(os).filter((entry) => !entry.startsWith("!"));
+	return supported.length > 0 ? supported : void 0;
+}
+/**
+* Derive the `brew install` path for a package published to a Homebrew tap with
+* [brewpub](https://github.com/kitschpatrol/brewpub), by finding the `brewpub
+* --tap <owner>/<tap>` invocation in the package.json scripts. Mirrors
+* brewpub's formula naming: the `--name` option if passed, otherwise the
+* package name without its scope.
+*
+* @returns E.g. `kitschpatrol/tap/mdat`, or undefined if brewpub isn't used
+*/
+function getHomebrewFormula(packageName, scripts) {
+	if (packageName === void 0 || scripts === void 0) return;
+	for (const script of Object.values(scripts)) {
+		const tap = BREWPUB_TAP_REGEX.exec(script ?? "")?.groups?.tap;
+		if (tap === void 0) continue;
+		const [owner, tapName] = tap.split("/", 2);
+		if (owner === void 0 || tapName === void 0) continue;
+		const formula = BREWPUB_NAME_REGEX.exec(script ?? "")?.groups?.name ?? packageName.slice(packageName.indexOf("/") + 1).toLowerCase();
+		return `${owner}/${tapName.replace(HOMEBREW_TAP_PREFIX_REGEX, "")}/${formula}`;
+	}
+}
 /**
 * Reset cached context metadata. Call between tests or when the underlying
 * project files may have changed on disk.
@@ -203,6 +255,7 @@ const readmeMetadataTemplate = defineTemplate((context) => {
 			runtimes: runtimes.length > 0 ? runtimes : void 0
 		};
 	})();
+	const homebrewFormula = getHomebrewFormula(nodePackage?.name, nodePackage?.scripts);
 	const firstAuthor = helpers.firstOf(helpers.ensureArray(codemeta.author));
 	return {
 		author: helpers.firstOf(helpers.mixedStringsToArray(helpers.toBasicNames(codemeta.author))),
@@ -212,19 +265,22 @@ const readmeMetadataTemplate = defineTemplate((context) => {
 		description: codemeta.description,
 		developmentDependencies,
 		engines,
-		isPublicNpmPackage: nodePackage?.private !== true && (nodePackage?.name.startsWith("@") && nodePackage.publishConfig?.access === "public" || true),
+		hasTypes: nodePackage?.types !== void 0 || containsTypesKey(nodePackage?.exports),
+		homebrewFormula,
+		isLibrary: isLibraryPackage(nodePackage),
+		isNodePackage: nodePackage !== void 0,
+		isPublicNpmPackage: nodePackage !== void 0 && nodePackage.private !== 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,
+		operatingSystem: codemeta.operatingSystem ?? getSupportedOperatingSystems(nodePackage?.os),
 		peerDependencies,
 		projectDirectory: metascope?.data.options.path === void 0 ? void 0 : `file://${metascope.data.options.path}`,
 		repositoryUrl: repoUrl,
 		runtimePlatform: codemeta.runtimePlatform,
-		usesGitLfs: helpers.firstOf(gitStats)?.data.hasLfs === true,
-		usesPnpm: helpers.usesPnpm(nodePackageJson)
+		usesGitLfs: helpers.firstOf(gitStats)?.data.hasLfs === true
 	};
 });
 let readmeMetadata;
@@ -359,13 +415,30 @@ var code_default = { code: { async content(options) {
 	return `\`\`\`${lang}\n${validOptions.trim ? exampleCode.trim() : exampleCode}\n\`\`\``;
 } } };
 
+//#endregion
+//#region src/lib/readme/rules/utilities/heading.ts
+/**
+* Option schema for the Markdown heading level (1-6) at which a rule emits its
+* section heading. Sub-headings, if any, are nested one level deeper. Rules
+* default to level 3, matching their placement under a level 2 section like
+* "Getting started" in the house readme template.
+*/
+const headingLevelSchema = z.number().int().min(1).max(6).optional();
+/**
+* The `#` prefix for a Markdown heading, clamped to the maximum level of 6.
+*/
+function getHeadingPrefix(level) {
+	return "#".repeat(Math.min(level, 6));
+}
+
 //#endregion
 //#region src/lib/readme/rules/contributing.ts
-var contributing_default = { contributing: { async content() {
+var contributing_default = { contributing: { async content(options) {
+	const validOptions = z.object({ headingLevel: headingLevelSchema }).optional().parse(options);
 	const { issuesUrl } = await getReadmeMetadata();
 	if (issuesUrl === void 0) throw new Error("Could not find \"bugs.url\" entry in package.json");
 	return [
-		"## Contributing",
+		`${getHeadingPrefix(validOptions?.headingLevel ?? 2)} Contributing`,
 		"",
 		`[Issues](${issuesUrl}) are welcome and appreciated.`,
 		"",
@@ -375,6 +448,37 @@ var contributing_default = { contributing: { async content() {
 	].join("\n");
 } } };
 
+//#endregion
+//#region src/lib/readme/rules/utilities/version-range.ts
+const BARE_VERSION_REGEX = /^v?\d+(?:\.\d+){0,2}$/v;
+const MINIMUM_ONLY_REGEX = /^>=\s*v?(?<version>\d+(?:\.\d+){0,2})$/v;
+const LOWER_BOUND_REGEX = /(?:^|[\s\|\(^~]|>=)\s*v?(?<version>\d+(?:\.\d+){0,2})/gv;
+function compareVersions(a, b) {
+	const partsA = a.split(".").map(Number);
+	const partsB = b.split(".").map(Number);
+	for (let index = 0; index < Math.max(partsA.length, partsB.length); index++) {
+		const difference = (partsA[index] ?? 0) - (partsB[index] ?? 0);
+		if (difference !== 0) return difference;
+	}
+	return 0;
+}
+/**
+* Describe a semver range in plain language for readme prose.
+*
+* @example
+* 	`>=24.16.0` → `24.16.0 or newer`
+* 	`^24.16.0 || >=26.3.0` → `24.16.0 or newer (specifically \`^24.16.0 || >=26.3.0\`)`
+* 	`3.13` → `3.13`
+*/
+function describeVersionRange(range) {
+	const trimmed = range.trim();
+	if (BARE_VERSION_REGEX.test(trimmed)) return trimmed;
+	const minimumOnly = MINIMUM_ONLY_REGEX.exec(trimmed)?.groups?.version;
+	if (minimumOnly !== void 0) return `${minimumOnly} or newer`;
+	const floor = trimmed.matchAll(LOWER_BOUND_REGEX).map((match) => match.groups?.version).filter((version) => version !== void 0).toArray().toSorted(compareVersions)[0];
+	return floor === void 0 ? `\`${trimmed}\`` : `${floor} or newer (specifically \`${trimmed}\`)`;
+}
+
 //#endregion
 //#region src/lib/readme/rules/dependencies.ts
 const PLATFORM_INFO = {
@@ -396,7 +500,7 @@ const PLATFORM_INFO = {
 	},
 	node: {
 		display: "Node.js",
-		url: "https://nodejs.org/en"
+		url: "https://nodejs.org/"
 	},
 	python: {
 		display: "Python",
@@ -411,38 +515,46 @@ const PLATFORM_INFO = {
 		url: "https://www.rust-lang.org/"
 	}
 };
-var dependencies_default = { dependencies: { async content() {
+const OPERATING_SYSTEM_NAMES = {
+	darwin: "macOS",
+	linux: "Linux",
+	win32: "Windows"
+};
+function getPlatformDisplay(key) {
+	const info = PLATFORM_INFO[key.toLowerCase()];
+	return info ? `[${info.display}](${info.url})` : key;
+}
+function getPlatformItem(key, version) {
+	const display = getPlatformDisplay(key);
+	return version === void 0 || version.trim() === "" ? `- ${display}` : `- ${display} ${describeVersionRange(version)}`;
+}
+var dependencies_default = { dependencies: { async content(options) {
+	const validOptions = z.object({ headingLevel: headingLevelSchema }).optional().parse(options);
 	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;
+	const items = [];
+	const engineEntries = Object.entries(engines ?? {});
+	const runtimePlatformEntries = runtimePlatform ?? [];
+	const peerDependencyEntries = (peerDependencies ?? []).filter(({ optional }) => !optional);
+	for (const [name, version] of engineEntries) items.push(getPlatformItem(name, version));
+	for (const entry of runtimePlatformEntries) {
+		const [platformKey = entry, ...versionParts] = entry.split(" ");
 		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}`);
+		items.push(getPlatformItem(platformKey, versionParts.join(" ")));
 	}
-	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) {
+	if (operatingSystem !== void 0 && operatingSystem.length > 0) {
+		const names = operatingSystem.map((os) => OPERATING_SYSTEM_NAMES[os] ?? os);
+		items.push(`- Supported operating systems: ${names.join(", ")}`);
+	}
+	for (const { name, version } of peerDependencyEntries) {
 		const npmUrl = `https://www.npmjs.com/package/${name}`;
-		const optionalSuffix = optional ? " _(optional)_" : "";
-		peerItems.push(`- [${name}](${npmUrl}) ${version}${optionalSuffix}`);
+		items.push(`- [${name}](${npmUrl}) \`${version}\` _(peer dependency)_`);
 	}
-	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");
+	if (items.length === 0) return "";
+	return [
+		`${getHeadingPrefix(validOptions?.headingLevel ?? 3)} Dependencies`,
+		"",
+		...items
+	].join("\n");
 } } };
 
 //#endregion
@@ -469,7 +581,7 @@ const TOOL_INFO = {
 	},
 	node: {
 		display: "Node.js",
-		url: "https://nodejs.org/en"
+		url: "https://nodejs.org/"
 	},
 	npm: {
 		display: "npm",
@@ -484,7 +596,8 @@ const TOOL_INFO = {
 		url: "https://yarnpkg.com/"
 	}
 };
-var development_dependencies_default = { "development-dependencies": { async content() {
+var development_dependencies_default = { "development-dependencies": { async content(options) {
+	const validOptions = z.object({ headingLevel: headingLevelSchema }).optional().parse(options);
 	const { developmentDependencies } = await getReadmeMetadata();
 	if (developmentDependencies === void 0) return "";
 	const { packageManagers, runtimes } = developmentDependencies;
@@ -495,7 +608,7 @@ var development_dependencies_default = { "development-dependencies": { async con
 		items.push(version === void 0 || version === "" ? `- ${display}` : `- ${display} ${version}`);
 	}
 	return [
-		"## Development Dependencies",
+		`${getHeadingPrefix(validOptions?.headingLevel ?? 3)} Development dependencies`,
 		"",
 		...items
 	].join("\n");
@@ -510,11 +623,13 @@ var dev_dependencies_default = { "dev-dependencies": getSoleRule(development_dep
 
 //#endregion
 //#region src/lib/readme/rules/license.ts
-var license_default = { license: { async content() {
+var license_default = { license: { async content(options) {
+	const validOptions = z.object({ headingLevel: headingLevelSchema }).optional().parse(options);
 	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})`}`;
+	const authorDisplay = authorUrl === void 0 ? author : `[${author}](${authorUrl})`;
+	return `${`${getHeadingPrefix(validOptions?.headingLevel ?? 2)} License`}\n[${license}](${licenseFilePath}) © ${authorDisplay}`;
 } } };
 
 //#endregion
@@ -564,21 +679,99 @@ var header_default = { header: {
 
 //#endregion
 //#region src/lib/readme/rules/install.ts
-var install_default = { install: { async content() {
-	const { bin, engines, isPublicNpmPackage, name, runtimePlatform, usesPnpm } = await getReadmeMetadata();
+const listFormatter = new Intl.ListFormat("en", {
+	style: "long",
+	type: "conjunction"
+});
+function codeBlock(command) {
+	return [
+		"```sh",
+		command,
+		"```"
+	];
+}
+/**
+* Install instructions for command-line use: run once with `npx`, or install
+* globally with Homebrew (if published to a tap) or npm.
+*/
+function getCliLines(name, homebrewFormula) {
+	return [
+		"Run it once without installing:",
+		"",
+		...codeBlock(`npx ${name}`),
+		...homebrewFormula === void 0 ? [] : [
+			"",
+			"Or install it globally with Homebrew:",
+			"",
+			...codeBlock(`brew install ${homebrewFormula}`)
+		],
+		"",
+		"Or install it globally with npm:",
+		"",
+		...codeBlock(`npm install --global ${name}`)
+	];
+}
+/**
+* Install instructions for use as a project dependency.
+*/
+function getLibraryLines(name, bin, hasTypes, dev) {
+	const lead = dev ? "Add it to your project as a development dependency" : "Add it to your project";
+	const command = `npm install ${dev ? "--save-dev " : ""}${name}`;
+	if (bin === void 0 || bin.length === 0) return [
+		`${lead}:`,
+		"",
+		...codeBlock(command)
+	];
+	return [
+		`${lead} to import the ${hasTypes ? "TypeScript API" : "API"}. This also puts the ${listFormatter.format(bin.map((binName) => `\`${binName}\``))} ${bin.length === 1 ? "CLI" : "CLIs"} on your project's path:`,
+		"",
+		...codeBlock(command)
+	];
+}
+var install_default = { install: { async content(options) {
+	const validOptions = z.object({
+		dev: z.boolean().optional(),
+		headingLevel: headingLevelSchema,
+		homebrew: z.union([z.string(), z.literal(false)]).optional()
+	}).optional().parse(options);
+	const { bin, hasTypes, homebrewFormula, isLibrary, isNodePackage, isPublicNpmPackage, name, runtimePlatform } = 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");
+	const headingLevel = validOptions?.headingLevel ?? 3;
+	const heading = `${getHeadingPrefix(headingLevel)} Installation`;
+	const subheading = getHeadingPrefix(headingLevel + 1);
+	if (isNodePackage) {
+		if (!isPublicNpmPackage) throw new Error("Install instructions require a publishable package, but package.json sets \"private\": true");
+		const homebrew = validOptions?.homebrew === void 0 ? homebrewFormula : validOptions.homebrew === false ? void 0 : validOptions.homebrew;
+		const hasCli = bin !== void 0 && bin.length > 0;
+		const cliLines = getCliLines(name, homebrew);
+		const libraryLines = getLibraryLines(name, bin, hasTypes, validOptions?.dev ?? false);
+		if (hasCli && isLibrary) return [
+			heading,
+			"",
+			"Pick the option that matches how you plan to use it.",
+			"",
+			`${subheading} CLI`,
+			"",
+			...cliLines,
+			"",
+			`${subheading} Library`,
+			"",
+			...libraryLines
+		].join("\n");
+		return [
+			heading,
+			"",
+			...hasCli ? cliLines : libraryLines
+		].join("\n");
+	}
+	const platform = (prefix) => runtimePlatform?.some((p) => p.startsWith(prefix));
+	const command = platform("python") ? `pip install ${name}` : platform("rust") ? `cargo install ${name}` : platform("go") ? `go install ${name}@latest` : platform("ruby") ? `gem install ${name}` : void 0;
+	if (command === void 0) throw new Error("Could not determine project ecosystem for install instructions");
+	return [
+		heading,
+		"",
+		...codeBlock(command)
+	].join("\n");
 } } };
 
 //#endregion
@@ -710,21 +903,24 @@ var size_table_default = { "size-table": { async content(options) {
 //#region src/lib/readme/rules/table-of-contents.ts
 var table_of_contents_default = { "table-of-contents": {
 	async content(options, { tree }) {
-		const validOptions = 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);
+		const validOptions = z.object({
+			depth: z.union([
+				z.literal(1),
+				z.literal(2),
+				z.literal(3),
+				z.literal(4),
+				z.literal(5),
+				z.literal(6)
+			]).optional(),
+			headingLevel: headingLevelSchema
+		}).optional().parse(options);
 		const result = toc(tree, {
 			heading: null,
 			maxDepth: validOptions?.depth ?? 3,
 			tight: true
 		});
 		if (result.map === void 0) throw new Error("Could not generate table of contents");
-		const heading = `## Table of contents`;
+		const heading = `${getHeadingPrefix(validOptions?.headingLevel ?? 2)} Table of contents`;
 		const rootWrapper = {
 			children: result.map.children,
 			type: "root"
@@ -1034,11 +1230,11 @@ function getStripProcessor(_config, ambientRemarkConfig) {
 
 //#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";
+var mdat_readme_compound_default = "<!-- header -->\n\n<!-- table-of-contents -->\n\n## Overview\n\n## Getting started\n\n<!-- dependencies -->\n\n<!-- install -->\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";
+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<!-- install -->\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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdat",
-  "version": "3.2.2",
+  "version": "3.4.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.1",
     "remark": "^15.0.1",
     "remark-gfm": "^4.0.1",
-    "remark-mdat": "^3.0.2",
+    "remark-mdat": "^3.1.0",
     "to-vfile": "^8.0.0",
     "type-fest": "^5.10.0",
     "unified-engine": "^11.2.2",
@@ -71,7 +71,7 @@
     "@arethetypeswrong/core": "^0.18.5",
     "@kitschpatrol/shared-config": "^8.10.0",
     "@types/mdast": "^4.0.4",
-    "@types/node": "~24.13.4",
+    "@types/node": "~24.13.6",
     "@types/unist": "^3.0.3",
     "@types/yargs": "^17.0.35",
     "@vitest/coverage-v8": "^5.0.1",
@@ -99,7 +99,7 @@
     }
   },
   "engines": {
-    "node": ">=24.16.0"
+    "node": "^24.16.0 || >=26.3.0"
   },
   "scripts": {
     "bench": "vitest bench --run --reporter=default",

package/readme.md

@@ -6,9 +6,10 @@
 
 <!-- badges({
   custom: {
-    "Bundle Size": {
-      image: "https://img.shields.io/bundlephobia/minzip/mdat?label=Size",
-      link: "https://bundlephobia.com/package/mdat",
+    "Homebrew": {
+      image:
+        "https://img.shields.io/badge/Homebrew-kitschpatrol%2Ftap%2Fmdat-FBB040?logo=homebrew&logoColor=white",
+      link: "https://github.com/kitschpatrol/homebrew-tap/blob/main/Formula/mdat.rb",
     },
   }
 }) -->
@@ -16,7 +17,7 @@
 [![NPM Package mdat](https://img.shields.io/npm/v/mdat.svg)](https://www.npmjs.com/package/mdat)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/license/mit)
 [![CI](https://github.com/kitschpatrol/mdat/actions/workflows/ci.yml/badge.svg)](https://github.com/kitschpatrol/mdat/actions/workflows/ci.yml)
-[![Bundle Size](https://img.shields.io/bundlephobia/minzip/mdat?label=Size)](https://bundlephobia.com/package/mdat)
+[![Homebrew](https://img.shields.io/badge/Homebrew-kitschpatrol%2Ftap%2Fmdat-FBB040?logo=homebrew&logoColor=white)](https://github.com/kitschpatrol/homebrew-tap/blob/main/Formula/mdat.rb)
 
 <!-- /badges -->
 
@@ -36,8 +37,8 @@
   - [Installation](#installation)
 - [Features](#features)
 - [Usage](#usage)
-  - [CLI](#cli)
-  - [API](#api)
+  - [CLI](#cli-1)
+  - [Library](#library-1)
   - [Configuration](#configuration)
   - [Creating custom rules](#creating-custom-rules)
   - [Bundled rules](#bundled-rules)
@@ -109,30 +110,52 @@ The `<!-- title -->` comment was expanded with content derived from your project
 
 ## Getting started
 
+<!-- dependencies -->
+
 ### Dependencies
 
-Node 24+ (specifically `>=24.16.0`). Written in TypeScript with bundled type definitions.
+- [Node.js](https://nodejs.org/) 24.16.0 or newer (specifically `^24.16.0 || >=26.3.0`)
+
+<!-- /dependencies -->
+
+Written in TypeScript with bundled type definitions.
+
+<!-- install -->
 
 ### Installation
 
-Install locally to access the CLI and API in a single project:
+Pick the option that matches how you plan to use it.
+
+#### CLI
+
+Run it once without installing:
 
 ```sh
-pnpm install mdat
+npx mdat
 ```
 
-Or install globally:
+Or install it globally with Homebrew:
 
 ```sh
-pnpm install --global mdat
+brew install kitschpatrol/tap/mdat
 ```
 
-The CLI tool is also available on Homebrew:
+Or install it globally with npm:
 
 ```sh
-brew install kitschpatrol/tap/mdat
+npm install --global mdat
+```
+
+#### Library
+
+Add it to your project to import the TypeScript API. This also puts the `mdat` CLI on your project's path:
+
+```sh
+npm install mdat
 ```
 
+<!-- /install -->
+
 ## Features
 
 1. **Minimalist syntax**
@@ -423,7 +446,7 @@ mdat --format
 mdat create
 ```
 
-### API
+### Library
 
 `mdat` exports functions for expanding, collapsing, checking, and creating Markdown files programmatically.
 
@@ -566,6 +589,8 @@ See the [Examples section](https://github.com/kitschpatrol/remark-mdat#examples)
 
 ### Bundled rules
 
+Every rule that emits a section heading accepts a `headingLevel` option (`1`-`6`) to control the heading's Markdown level, with any sub-headings nested one level deeper. The defaults match each rule's placement in the bundled MDAT Readme template: `2` for top-level sections (`table-of-contents`, `contributing`, and `license`), and `3` for the rules that sit under "Getting started" (`dependencies`, `install`, and `development-dependencies`).
+
 #### Stand-alone
 
 - ##### `<!-- title -->`
@@ -586,19 +611,23 @@ See the [Examples section](https://github.com/kitschpatrol/remark-mdat#examples)
 
 - ##### `<!-- install -->`
 
-  Ecosystem-aware install instructions derived from project metadata. Emits `pnpm add` / `npm install` for Node packages (plus a `pnpx` / `npx` hint when the project exposes a binary), and falls back to `pip`, `cargo`, `gem`, or `go install` for Python, Rust, Ruby, and Go projects.
+  Install instructions derived from `package.json`, written for people consuming the package rather than developing it, so they always use `npm`. Packages with a `bin` get CLI instructions (`npx`, Homebrew, and `npm install --global`), packages with an entry point (`exports`, `main`, `module`, or `types`) get library instructions (`npm install`), and packages with both get a section for each. The Homebrew option appears automatically when a `brewpub --tap` invocation is found in the package scripts, and can be set explicitly with `homebrew: "owner/tap/formula"` or suppressed with `homebrew: false`. Pass `dev: true` to recommend `npm install --save-dev` for tooling packages. Private packages are rejected. Falls back to `pip`, `cargo`, `gem`, or `go install` for Python, Rust, Ruby, and Go projects. The optional `headingLevel` sets the Markdown heading level and defaults to `3`, matching the template's placement under a "Getting started" section:
+
+  ```md
+  <!-- install({ headingLevel: 2, dev: true, homebrew: false }) -->
+  ```
 
 - ##### `<!-- dependencies -->`
 
-  Documents platform requirements and peer dependencies. Lists runtime platforms (Node, Python, Rust, Go, Ruby, etc.) with version constraints from `engines` or equivalent metadata, supported operating systems, and peer dependencies with links to npm.
+  Documents platform requirements and peer dependencies. Lists runtime platforms (Node, Python, Rust, Go, Ruby, etc.) with version constraints from `engines` or equivalent metadata, supported operating systems, and required peer dependencies with links to npm. Optional peer dependencies are left out. Version ranges are described in plain language (`>=24.16.0` becomes "24.16.0 or newer"), with the exact range included when it can't be summarized that simply. The optional `headingLevel` sets the Markdown heading level and defaults to `3`.
 
 - ##### `<!-- development-dependencies -->`
 
-  Documents the tools needed to work on the project itself, derived from the `devEngines` and `packageManager` fields in `package.json`. Lists required runtimes and package managers with links and version constraints. Also aliased as `<!-- dev-dependencies -->`.
+  Documents the tools needed to work on the project itself, derived from the `devEngines` and `packageManager` fields in `package.json`. Lists required runtimes and package managers with links and version constraints. The optional `headingLevel` sets the Markdown heading level and defaults to `3`. Also aliased as `<!-- dev-dependencies -->`.
 
 - ##### `<!-- table-of-contents -->`
 
-  Auto-generated via [mdast-util-toc](https://github.com/syntax-tree/mdast-util-toc). Also aliased as `<!-- toc -->`.
+  Auto-generated via [mdast-util-toc](https://github.com/syntax-tree/mdast-util-toc). The optional `depth` limits how deeply nested headings are listed and defaults to `3`. Also aliased as `<!-- toc -->`.
 
 - ##### `<!-- contributing -->`
 
@@ -631,7 +660,7 @@ See the [Examples section](https://github.com/kitschpatrol/remark-mdat#examples)
 
 #### Compound
 
-Compound rules combine several stand-alone rules under a single keyword.
+Compound rules combine several stand-alone rules under a single keyword. Options are passed as an array with one entry per stand-alone rule, in order, e.g. `<!-- footer([{ headingLevel: 3 }, { headingLevel: 3 }]) -->`.
 
 - ##### `<!-- header -->`
 
@@ -668,7 +697,7 @@ Rule plugins are packages for sharing mdat expansion rules across projects.
 ### Installing a rule plugin
 
 ```sh
-pnpm install mdat-plugin-example
+npm install mdat-plugin-example
 ```
 
 Spread the plugin into your configuration: