mdat 3.6.2 → 3.6.3

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-BEUFGevf.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-CX9VHWwF.js";
 import { createLogger } from "lognow";
 import picocolors from "picocolors";
 import prettyMilliseconds from "pretty-ms";

package/dist/lib/index.d.ts

@@ -146,8 +146,6 @@ export declare function checkString(markdown: string, config?: ConfigToLoad, opt
 /**
  * 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
  */
 export declare function getContextMetadata(): Promise<MetadataContext>;
 declare const readmeMetadataTemplate: import("metascope").Template<{
@@ -191,6 +189,7 @@ declare const readmeMetadataTemplate: import("metascope").Template<{
   repositoryUrl: string | undefined;
   runtimePlatform: string[] | undefined;
   usesGitLfs: boolean;
+  usesSharedConfig: boolean;
   vscodeExtensionId: string | undefined;
 }>;
 type ReadmeMetadata = ReturnType<typeof readmeMetadataTemplate>;
@@ -240,6 +239,7 @@ export declare function getReadmeMetadata(): Promise<{
   repositoryUrl: string | undefined;
   runtimePlatform: string[] | undefined;
   usesGitLfs: boolean;
+  usesSharedConfig: boolean;
   vscodeExtensionId: string | undefined;
 }>;
 /**

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-BEUFGevf.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-CX9VHWwF.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-BEUFGevf.js → lib-CX9VHWwF.js}

@@ -26,7 +26,7 @@ import { confirm, group, intro, note, outro, select } from "@clack/prompts";
 
 //#region package.json
 var name = "mdat";
-var version = "3.6.2";
+var version = "3.6.3";
 
 //#endregion
 //#region src/lib/deep-merge-defined.ts
@@ -94,8 +94,6 @@ 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;
@@ -143,6 +141,13 @@ 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;
+const SHARED_CONFIG_PACKAGE = "@kitschpatrol/shared-config";
+/**
+* Normalize repository URLs for README links and badges.
+*/
+function normalizeRepositoryUrl(url) {
+	return url?.replace(GIT_PREFIX_REGEX, "").replace(GIT_SUFFIX_REGEX, "").replace(TRAILING_SLASH_REGEX, "");
+}
 /**
 * True if the package.json `exports` field declares a `types` condition
 * anywhere in its (possibly nested) structure.
@@ -215,6 +220,13 @@ function getRepositoryDirectory(nodePackage) {
 	return typeof nodePackage?.repository === "object" ? nodePackage.repository.directory : void 0;
 }
 /**
+* True if package.json lists `@kitschpatrol/shared-config` as a dependency or
+* dev dependency, meaning the repository is linted and formatted with `ksc`.
+*/
+function dependsOnSharedConfig(nodePackage) {
+	return nodePackage?.dependencies?.[SHARED_CONFIG_PACKAGE] !== void 0 || nodePackage?.devDependencies?.[SHARED_CONFIG_PACKAGE] !== void 0;
+}
+/**
 * Reset cached context metadata. Call between tests or when the underlying
 * project files may have changed on disk.
 *
@@ -229,7 +241,7 @@ const readmeMetadataTemplate = defineTemplate((context) => {
 	const nodePackage = helpers.firstOf(nodePackageJson)?.data;
 	const licenseFileData = helpers.firstOf(licenseFile);
 	const ciActionFilePath = helpers.ensureArray(githubActions).find((entry) => entry.data.name.toLowerCase() === "ci")?.source;
-	const repositoryUrl = codemeta.codeRepository?.replace(GIT_PREFIX_REGEX, "").replace(GIT_SUFFIX_REGEX, "").replace(TRAILING_SLASH_REGEX, "");
+	const repositoryUrl = normalizeRepositoryUrl(codemeta.codeRepository);
 	const bin = (() => {
 		if (nodePackage === void 0) return;
 		const binField = nodePackage.bin;
@@ -309,6 +321,7 @@ const readmeMetadataTemplate = defineTemplate((context) => {
 		repositoryUrl,
 		runtimePlatform: codemeta.runtimePlatform,
 		usesGitLfs: helpers.firstOf(gitStats)?.data.hasLfs === true,
+		usesSharedConfig: dependsOnSharedConfig(nodePackage),
 		vscodeExtensionId
 	};
 });
@@ -413,7 +426,7 @@ const badgeDefinitions = [
 	},
 	{
 		key: "license",
-		render: ({ license, licenseUrl }) => license === void 0 || licenseUrl === void 0 ? { unavailable: "no license file matching a known SPDX license was found" } : [`[![License: ${license}](https://img.shields.io/badge/License-${license.replaceAll("-", "--")}-yellow.svg)](${licenseUrl})`]
+		render: ({ license, licenseUrl }) => license === void 0 || licenseUrl === void 0 ? { unavailable: "no license file matching a known SPDX license was found" } : [`[![License: ${license}](https://img.shields.io/badge/License-${escapeStaticBadgeText(license)}-yellow.svg)](${licenseUrl})`]
 	},
 	{
 		key: "ci",
@@ -622,15 +635,16 @@ var contributing_default = { contributing: { async content(options) {
 		heading: headingSchema,
 		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");
+	const { issuesUrl, usesSharedConfig } = await getReadmeMetadata();
+	if (issuesUrl === void 0) throw new Error("Could not find an issue tracker URL in the project metadata. Add \"bugs.url\" to package.json, \"issueTracker\" to codemeta.json, or a GitHub repository URL.");
+	const toolingLine = usesSharedConfig ? "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." : "This repository uses [MDAT](https://github.com/kitschpatrol/mdat) for readme placeholder expansion.";
 	return [
 		...getHeadingLines(validOptions?.heading, validOptions?.headingLevel ?? 2, "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."
+		toolingLine
 	].join("\n");
 } } };
 
@@ -749,7 +763,7 @@ var dependencies_default = { dependencies: { async content(options) {
 */
 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");
+	if (description === void 0) throw new Error("Could not find project description");
 	return `**${description}**`;
 } } };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdat",
-  "version": "3.6.2",
+  "version": "3.6.3",
   "description": "CLI tool and TypeScript library to turn comments into content in Markdown files. MDAT makes it easy to generate and update dynamic boilerplate in project readmes.",
   "keywords": [
     "mdat",
@@ -11,7 +11,8 @@
     "docs-generator",
     "docs",
     "cli",
-    "npm-package"
+    "npm-package",
+    "homebrew-formula"
   ],
   "homepage": "https://github.com/kitschpatrol/mdat",
   "bugs": "https://github.com/kitschpatrol/mdat/issues",
@@ -52,7 +53,7 @@
     "gray-matter-es": "^0.2.1",
     "lognow": "^0.8.5",
     "mdast-util-toc": "^7.1.0",
-    "metascope": "^0.12.2",
+    "metascope": "^0.13.2",
     "path-type": "^6.0.0",
     "picocolors": "^1.1.1",
     "plur": "^6.0.0",
@@ -67,31 +68,31 @@
     "untildify": "^6.0.0",
     "vfile": "^6.0.3",
     "yargs": "^18.2.0",
-    "zod": "^4.6.5"
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@arethetypeswrong/core": "^0.18.5",
-    "@kitschpatrol/shared-config": "^8.12.1",
+    "@kitschpatrol/shared-config": "^8.13.1",
     "@types/mdast": "^4.0.4",
     "@types/node": "~24.13.6",
     "@types/unist": "^3.0.3",
     "@types/yargs": "^17.0.35",
-    "@vitest/coverage-v8": "^5.0.3",
+    "@vitest/coverage-v8": "^5.0.4",
     "brewpub": "^0.5.0",
     "bumpp": "^12.3.0",
-    "execa": "^10.0.1",
-    "mdat-plugin-cli-help": "^3.4.0",
-    "mdat-plugin-example": "^3.0.0",
-    "mdat-plugin-tldraw": "^3.0.0",
+    "execa": "^10.1.0",
+    "mdat-plugin-cli-help": "^3.4.1",
+    "mdat-plugin-example": "^3.0.1",
+    "mdat-plugin-tldraw": "^3.0.1",
     "nanoid": "^6.0.2",
-    "prettier": "^3.9.9",
+    "prettier": "^3.9.10",
     "publint": "^0.3.25",
     "shx": "^0.4.0",
-    "skills": "^1.7.0",
-    "tsdown": "^0.23.0",
+    "skills": "1.7.1",
+    "tsdown": "^0.23.1",
     "typescript": "~6.0.3",
     "unplugin-raw": "^0.8.0",
-    "vitest": "^5.0.3"
+    "vitest": "^5.0.4"
   },
   "peerDependencies": {
     "prettier": "^3.0.0"

package/readme.md

@@ -42,7 +42,7 @@
 - [Agent skills](#agent-skills)
   - [Skill: `mdat`](#skill-mdat)
   - [Skill: `mdat-plugin-authoring`](#skill-mdat-plugin-authoring)
-- [Migrating from 1.x to 2.x](#migrating-from-1x-to-2x)
+- [Migrating from 1.x to 2.x or 3.x](#migrating-from-1x-to-2x-or-3x)
   - [Flat CLI commands](#flat-cli-commands)
   - [Polyglot metadata](#polyglot-metadata)
   - [Simplified configuration](#simplified-configuration)
@@ -231,6 +231,18 @@ npm install mdat
 
    Bundled rules pull normalized metadata from almost any project type via [metascope](https://github.com/kitschpatrol/metascope), not just `package.json`.
 
+   Projects without a package manifest can provide a `metadata.json` file (`metadata.yaml` and `metadata.yml` also work):
+
+   ```json
+   {
+     "description": "A light sculpture for Disorient.",
+     "keywords": ["installation", "led"],
+     "repository": "https://github.com/kitschpatrol/asterism"
+   }
+   ```
+
+   This is a small format for GitHub descriptions, homepages, and topics. Metascope's shared CodeMeta templates also aggregate these fields, and MDAT consumes their normalized result. Project names and richer metadata come from package manifests, `codemeta.json`, or other supported sources; an existing README heading remains a title fallback.
+
 ## Usage
 
 > [!WARNING]
@@ -662,7 +674,7 @@ Rules that generate inline content, like `badges`, `code`, and `size`, have no h
 
 - ##### `<!-- contributing -->`
 
-  Invites issues and pull requests with links derived from project metadata.
+  Invites issues and pull requests with links derived from project metadata. Mentions [@kitschpatrol/shared-config](https://github.com/kitschpatrol/shared-config) only when `package.json` lists it as a dependency.
 
 - ##### `<!-- license -->`
 
@@ -829,9 +841,11 @@ Write custom mdat expansion rules and publishable mdat rule plugins (mdat-plugin
 
 <!-- /skills -->
 
-## Migrating from 1.x to 2.x
+## Migrating from 1.x to 2.x or 3.x
+
+The 2.0 version introduces significant breaking changes in the interest of simplicity and a somewhat narrowed scope of concerns. 3.0 was a mostly non-breaking, only dropping support for Node 22.
 
-The 2.0 version introduces significant breaking changes in the interest of simplicity and a somewhat narrowed scope of concerns.
+Plugin compatibility was broken from 1.x to 2.x, but maintained in 3.x.
 
 Details of the changes and migration strategies are enumerated below.
 
@@ -846,6 +860,7 @@ The `mdat readme` subcommand is gone. All commands are now top-level:
 | `mdat readme check` | `mdat check`    |
 | `mdat expand`       | `mdat expand`   |
 | `mdat collapse`     | `mdat collapse` |
+| _no equivalent_     | `mdat strip`    |
 
 Running `mdat` with no arguments expands the closest readme, matching the behavior of the 1.x `mdat readme` command.