mdat 0.9.0 → 1.0.0

package/dist/mdat-json-loader.d.ts

@@ -1,2 +1,7 @@
 import { type LoaderResult } from 'cosmiconfig';
+/**
+ * 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
+ */
 export declare function mdatJsonLoader(filePath: string, content: string): LoaderResult;

package/dist/processors.d.ts

@@ -1,11 +1,12 @@
 import { type Root } from 'mdast';
 import { VFile } from 'vfile';
 import { type ConfigLoaded, type ConfigToLoad, type loadConfig, type RulesToLoad } from './config';
+import { type AmbientRemarkConfig } from './utilities';
 type Loader = typeof loadConfig;
 type ProcessorGetter = typeof getCleanProcessor | typeof getExpandProcessor;
 export declare function processFiles(files: string | string[], loader: Loader, processorGetter: ProcessorGetter, name?: string, output?: string, config?: ConfigToLoad, rules?: RulesToLoad): Promise<VFile[]>;
 export declare function processString(markdown: string, loader: Loader, processorGetter: ProcessorGetter, config?: ConfigToLoad, rules?: RulesToLoad): Promise<VFile>;
-export declare function getExpandProcessor(options: ConfigLoaded): import("unified").Processor<Root, undefined, undefined, Root, string>;
-export declare function getCleanProcessor(options: ConfigLoaded): import("unified").Processor<Root, undefined, undefined, Root, string>;
-export declare function getCheckProcessor(options: ConfigLoaded): import("unified").Processor<Root, undefined, undefined, Root, string>;
+export declare function getExpandProcessor(options: ConfigLoaded, ambientRemarkConfig: AmbientRemarkConfig): import("unified").Processor<Root, undefined, undefined, Root, string>;
+export declare function getCleanProcessor(options: ConfigLoaded, ambientRemarkConfig: AmbientRemarkConfig): import("unified").Processor<Root, undefined, undefined, Root, string>;
+export declare function getCheckProcessor(options: ConfigLoaded, ambientRemarkConfig: AmbientRemarkConfig): import("unified").Processor<Root, undefined, undefined, Root, string>;
 export {};

package/dist/readme/api.d.ts

@@ -1,10 +1,46 @@
 import { type VFile } from 'vfile';
 import { type ConfigToLoad, type RulesToLoad } from '../config';
+/**
+ * Expands MDAT readme comments in the closest readme.md file
+ * Basically an alias to `expandReadmeFiles()` with certain arguments elided.
+ * @see `findReadme()` for more details on the search process.
+ */
 export declare function expandReadme(config?: ConfigToLoad, rules?: RulesToLoad): Promise<VFile[]>;
+/**
+ * Expands MDAT readme comments in one or more Markdown files
+ * Searches up for a readme.md file if none is provided.
+ * @see `findReadme()` for more details on the search process.
+ */
 export declare function expandReadmeFiles(files?: string | string[], name?: string, output?: string, config?: ConfigToLoad, rules?: RulesToLoad): Promise<VFile[]>;
+/**
+ * Expands MDAT readme comments in a Markdown string
+ */
 export declare function expandReadmeString(markdown: string, config?: ConfigToLoad, rules?: RulesToLoad): Promise<VFile>;
+/**
+ * Checks and validates MDAT readme comments in the closest readme.md file
+ * Basically an alias to `checkReadmeFiles()` with certain arguments elided.
+ * @see `findReadme()` for more details on the search process.
+ */
 export declare function checkReadme(config?: ConfigToLoad, rules?: RulesToLoad): Promise<VFile[]>;
+/**
+ * Checks and validates MDAT readme comments in one or more Markdown files
+ * Searches up for a readme.md file if none is provided.
+ * @see `findReadme()` for more details on the search process.
+ */
 export declare function checkReadmeFiles(files?: string | string[], name?: string, output?: string, config?: ConfigToLoad, rules?: RulesToLoad): Promise<VFile[]>;
+/**
+ * Checks and validates MDAT readme comments in a Markdown string
+ */
 export declare function checkReadmeString(markdown: string, config?: ConfigToLoad, rules?: RulesToLoad): Promise<VFile>;
+/**
+ * Collapses MDAT readme comments in the closest readme.md file
+ * Basically an alias to `collapseReadmeFiles()` with certain arguments elided.
+ * @see `findReadme()` for more details on the search process.
+ */
 export declare function collapseReadme(config?: ConfigToLoad, rules?: RulesToLoad): Promise<VFile[]>;
+/**
+ * Collapses MDAT readme comments in one or more Markdown files
+ * Searches up for a readme.md file if none is provided.
+ * @see `findReadme()` for more details on the search process.
+ */
 export declare function collapseReadmeFiles(files?: string | string[], name?: string, output?: string, config?: ConfigToLoad, rules?: RulesToLoad): Promise<VFile[]>;

package/dist/readme/config.d.ts

@@ -1,8 +1,11 @@
 import { type Simplify } from 'type-fest';
 import { type ConfigLoaded, loadConfig } from '../config';
-type ReadmeConfigLoaded = Simplify<{
+type ReadmeConfigLoaded = Simplify<ConfigLoaded & {
     packageFile: string;
-} & ConfigLoaded>;
+}>;
 type LoadConfigOptions = Parameters<typeof loadConfig>[0];
+/**
+ * Convenience loader to always include the default readme config
+ */
 export declare function loadConfigReadme(options?: LoadConfigOptions): Promise<ReadmeConfigLoaded>;
 export {};

package/dist/readme/init.d.ts

@@ -1,6 +1,3 @@
-export type Symbolize<T extends Record<string, unknown>> = {
-    [x in keyof T]: symbol | T[x];
-};
 type MdatReadmeInitOptions = {
     compound: boolean;
     expand: boolean;
@@ -8,9 +5,14 @@ type MdatReadmeInitOptions = {
     overwrite: boolean;
     template: string;
 };
+/**
+ * Initializes a new readme file interactively.
+ * @returns Path to the created readme file.
+ */
 export declare function initReadmeInteractive(): Promise<string>;
 /**
- * @return Path to the created readme file.
+ * Creates a new readme file with the given options.
+ * @returns Path to the created readme file.
  */
 export declare function initReadme(options?: Partial<MdatReadmeInitOptions>): Promise<string>;
 export {};

package/dist/readme/rules/utilities/cli-help/get-help-markdown.d.ts

@@ -2,4 +2,7 @@
  * Get help output from a CLI command and return it as markdown
  */
 export declare function getHelpMarkdown(cliCommand: string, helpFlag?: string, depth?: number): Promise<string>;
+/**
+ * Exported for testing
+ */
 export declare function renderHelpMarkdownBasic(rawHelpString: string): string;

package/dist/readme/rules/utilities/cli-help/help-object-to-markdown.d.ts

@@ -1,2 +1,6 @@
 import { type ProgramInfo } from './parsers/index';
+/**
+ * Converts a ProgramInfo object extracted by one of the help parsers into a big
+ * beautiful Markdown table.
+ */
 export declare function helpObjectToMarkdown(programInfo: ProgramInfo, depthRemaining?: number): string;

package/dist/readme/rules/utilities/cli-help/help-string-to-object.d.ts

@@ -1,2 +1,10 @@
 import { type ProgramInfo } from './parsers/index';
+/**
+ * Tries to parse a help string into an object through a process of trial and
+ * error with the available parsers.
+ *
+ * Generally, there's no way to know which framework was used to generate a
+ * particular CLI tool without inspecting the output for particular formatting
+ * patterns.
+ */
 export declare function helpStringToObject(helpString: string): ProgramInfo | undefined;

package/dist/readme/rules/utilities/cli-help/parsers/index.d.ts

@@ -37,6 +37,9 @@ declare const _default: {
     meow: typeof helpStringToObjectMeow;
 };
 export default _default;
+/**
+ * Get the command and subcommand from a command string.
+ */
 export declare function getCommandParts(wholeCommand: string | undefined): {
     command: string;
     subcommand: string | undefined;

package/dist/readme/rules/utilities/cli-help/parsers/meow.d.ts

@@ -1,2 +1,7 @@
 import { type ProgramInfo } from './index';
+/**
+ * Converts am unstructured help string emitted from a CLI tool built with the
+ * `meow` CLI library and turn it into a structured POJO describing the
+ * command.
+ */
 export declare function helpStringToObject(helpString: string): ProgramInfo;

package/dist/readme/rules/utilities/cli-help/parsers/yargs.d.ts

@@ -1,2 +1,7 @@
 import { type ProgramInfo } from './index';
+/**
+ * Converts am unstructured help string emitted from a CLI tool built with the
+ * `Yargs` CLI library and turn it into a structured POJO describing the
+ * command.
+ */
 export declare function helpStringToObject(helpString: string): ProgramInfo;

package/dist/readme/templates/index.d.ts

@@ -1,12 +1,3 @@
-export type Template = {
-    content: {
-        compound: string;
-        explicit: string;
-    };
-    description: string;
-    exampleLink: `https://${string}.md`;
-};
-export type Templates = Record<string, Template>;
 declare const _default: {
     'MDAT Readme': {
         content: {

package/dist/readme/utilities.d.ts

@@ -3,8 +3,13 @@
  * 1. Searches the current working directly for readme.md
  * 2. If there's no readme.md in the current directory, search up to the closest package directory
  * 3. Give up and return undefined if no readme is found
- *
  * @returns The path to the readme file or undefined if not found
  */
 export declare function findReadme(): Promise<string | undefined>;
+/**
+ * Searches up for a readme.md file
+ * @see `findReadme()` for more details on the search process.
+ * @returns The path to the readme file
+ * @throws if no readme is found
+ */
 export declare function findReadmeThrows(): Promise<string>;

package/dist/utilities.d.ts

@@ -1,13 +1,10 @@
+import { type ConfigResult as AmbientRemarkConfig } from 'unified-engine';
+export { type ConfigResult as AmbientRemarkConfig } from 'unified-engine';
 export declare function getInputOutputPaths(inputs: string[], output: string | undefined, name: string | undefined, extension: string | undefined): Array<{
     input: string;
     name: string;
     output: string;
 }>;
-export declare function getInputOutputPath(input: string, output: string | undefined, name: string | undefined, extension: string | undefined, nameSuffix?: string): {
-    input: string;
-    name: string;
-    output: string;
-};
-export declare function expandPath(file: string): string;
 export declare function findPackage(): Promise<string | undefined>;
 export declare function ensureArray<T>(value: T | T[] | undefined): T[];
+export declare function loadAmbientRemarkConfig(): Promise<AmbientRemarkConfig>;

package/license.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Eric Mika
+Copyright (c) 2024-2025 Eric Mika
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/package.json

@@ -1,69 +1,69 @@
 {
   "name": "mdat",
-  "version": "0.9.0",
-  "type": "module",
+  "version": "1.0.0",
   "description": "CLI tool and 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.",
-  "repository": "github:kitschpatrol/mdat",
+  "keywords": [
+    "mdat",
+    "markdown",
+    "template",
+    "readme",
+    "comments",
+    "docs-generator",
+    "docs",
+    "cli",
+    "npm-package"
+  ],
   "homepage": "https://github.com/kitschpatrol/mdat",
   "bugs": "https://github.com/kitschpatrol/mdat/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kitschpatrol/mdat"
+  },
+  "license": "MIT",
   "author": {
     "name": "Eric Mika",
     "email": "eric@ericmika.com",
     "url": "https://ericmika.com"
   },
-  "license": "MIT",
-  "engines": {
-    "node": "^18.19.0 || >=20.5.0",
-    "pnpm": ">=9.0.0"
-  },
-  "bin": {
-    "mdat": "bin/cli.js"
-  },
+  "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "mdat": "bin/cli.js"
+  },
   "files": [
     "bin/*",
     "dist/*"
   ],
-  "keywords": [
-    "mdat",
-    "markdown",
-    "template",
-    "readme",
-    "comments",
-    "docs-generator",
-    "docs",
-    "cli",
-    "npm-package"
-  ],
   "dependencies": {
-    "@clack/prompts": "^0.7.0",
-    "@kitschpatrol/tldraw-cli": "^4.6.28",
+    "@clack/prompts": "^0.10.0",
+    "@kitschpatrol/tldraw-cli": "^4.6.30",
     "@types/mdast": "^4.0.4",
     "@types/node": "18.19.0",
     "@types/unist": "^3.0.3",
+    "@types/which": "^3.0.4",
     "@types/yargs": "^17.0.33",
     "cosmiconfig": "^9.0.0",
     "cosmiconfig-typescript-loader": "^6.1.0",
     "execa": "^9.5.2",
-    "globby": "^14.0.2",
+    "globby": "^14.1.0",
     "read-pkg": "^9.0.1",
-    "remark-mdat": "^0.7.5",
-    "type-fest": "^4.33.0",
+    "remark-mdat": "^1.0.1",
+    "type-fest": "^4.36.0",
+    "unified-engine": "^11.2.2",
     "vfile": "^6.0.3",
     "which": "^5.0.0"
   },
   "devDependencies": {
-    "@kitschpatrol/shared-config": "^4.7.12",
-    "@types/which": "^3.0.4",
-    "bumpp": "^9.10.1",
+    "@kitschpatrol/shared-config": "^5.0.6",
+    "bumpp": "^10.0.3",
     "chalk": "^5.4.1",
     "chevrotain": "^11.0.3",
     "find-up": "^7.0.0",
     "is-executable": "^2.0.1",
     "mdast-util-toc": "^7.1.0",
-    "nanoid": "^5.0.9",
+    "nanoid": "^5.1.2",
     "package-up": "^5.0.0",
     "path-type": "^6.0.0",
     "pkg-dir": "^8.0.0",
@@ -71,14 +71,18 @@
     "pretty-bytes": "^6.1.1",
     "pretty-ms": "^9.2.0",
     "remark": "^15.0.1",
-    "remark-gfm": "^4.0.0",
+    "remark-gfm": "^4.0.1",
     "to-vfile": "^8.0.0",
-    "tsup": "^8.3.5",
-    "typescript": "^5.7.3",
+    "tsup": "^8.4.0",
+    "typescript": "~5.7.3",
     "untildify": "^5.0.0",
-    "vitest": "^2.1.8",
+    "vitest": "^3.0.7",
     "yargs": "^17.7.2",
-    "zod": "^3.24.1"
+    "zod": "^3.24.2"
+  },
+  "engines": {
+    "node": "^18.19.0 || >=20.11.0",
+    "pnpm": ">=10.0.0"
   },
   "publishConfig": {
     "access": "public"
@@ -87,8 +91,8 @@
     "build": "tsup && tsc -p tsconfig.build.lib.json",
     "clean": "git rm -f pnpm-lock.yaml ; git clean -fdX",
     "dev": "pnpm run test",
-    "fix": "shared-config --fix",
-    "lint": "shared-config --lint",
+    "fix": "kpi fix",
+    "lint": "kpi lint",
     "release": "bumpp --commit 'Release: %s' && pnpm run build && pnpm publish --otp $(op read 'op://Personal/Npmjs/one-time password?attribute=otp')",
     "test": "vitest --no-file-parallelism"
   }

package/readme.md

@@ -153,7 +153,7 @@ As [noted below](#similar-projects), there are several similar projects out ther
    An expansion rule can be as minimal as a file exporting a record:
 
    ```ts
-   { keyword: "content"}`
+   export default { keyword: 'content' }
    ```
 
    Which will turn:
@@ -175,13 +175,13 @@ As [noted below](#similar-projects), there are several similar projects out ther
    Or, make things a bit more dynamic by returning a function instead of a string. Async functions are welcome.
 
    ```ts
-   { date: () => `${new Date().toISOString()}` } }"
+   export default { date: () => `${new Date().toISOString()}` }
    ```
 
    Or enforce validation by adding some metadata:
 
    ```ts
-   {
+   export default {
      date: {
        content: () => `${new Date().toISOString()}`,
        order: 1,
@@ -216,7 +216,8 @@ As [noted below](#similar-projects), there are several similar projects out ther
 
 ## Usage
 
-> \[!WARNING]\
+> [!WARNING]
+>
 > **The MDAT CLI tool directly manipulates the contents of readme files, in close (and perhaps dangerous) proximity to your painstakingly crafted words.**
 >
 > Please make sure any text you care about is committed before running `mdat`, and never directly modify content inside of the comment expansion blocks.
@@ -556,10 +557,10 @@ Similar to `expandString()`, but takes a file path and handles setting an option
 It's up to the caller to actually save the returned VFile object. The [to-vfile](https://www.npmjs.com/package/to-vfile) library can make this particularly painless:
 
 ```ts
-import { expandFile } from 'mdat'
+import { expandFiles } from 'mdat'
 import { write } from 'to-vfile'
 
-const file = await expandFiles(...)
+const [file] = await expandFiles('some-file.md')
 await write(file)
 ```
 
@@ -581,10 +582,10 @@ Like `expandFile()`, but accepts an array of inputs. If an output name is specif
 
 ```ts
 function loadConfig(options?: {
-  additionalConfig?: ConfigToLoad // file paths or config objects
-  additionalRules?: RulesToLoad // file paths or rule objects
+  additionalConfig?: ConfigToLoad // File paths or config objects
+  additionalRules?: RulesToLoad // File paths or rule objects
   searchFrom?: string
-}): Promise<ConfigLoaded> // returns a single merged config object
+}): Promise<ConfigLoaded> // Returns a single merged config object
 ```
 
 This is provided for more advanced use cases. It assists in discovering and loading ambient configuration in your project (e.g. fields in your package.json, or dedicated `mdat` config files). It also dynamically loads, validates, and merges additional `mdat` configuration and rule files into a final `ConfigLoaded` object ready to be passed into the [`remark-mdat`](https://github.com/kitschpatrol/remark-mdat) plugin or one of the API functions like `expandFile()`.
@@ -633,12 +634,12 @@ The `mdat` configuration file is a record object allowing you to customize aspec
 
 ```ts
 type Config = {
-  assetsPath?: string // where asset-generating rules should store their output, defaults to './assets'
-  packageFile?: string // used by readme rules, found dynamically if undefined
-  addMetaComment?: boolean // defaults to true
-  closingPrefix?: string // defaults to '/'
-  keywordPrefix?: string // defaults to ''
-  metaCommentIdentifier?: string // defaults to '+'
+  addMetaComment?: boolean // Defaults to true
+  assetsPath?: string // Where asset-generating rules should store their output, defaults to './assets'
+  closingPrefix?: string // Defaults to '/'
+  keywordPrefix?: string // Defaults to ''
+  metaCommentIdentifier?: string // Defaults to '+'
+  packageFile?: string // Used by readme rules, found dynamically if undefined
   rules?: Rules
 }
 ```
@@ -647,6 +648,10 @@ A valid configuration file default-exports an object conforming to the above typ
 
 The configuration file may be located in any location supported by [cosmicconfig](https://github.com/cosmiconfig/cosmiconfig?tab=readme-ov-file#searchplaces). I use an `mdat.config.ts` file in the root of my projects.
 
+> [!NOTE]
+>
+> The `mdat` commands _also_ search for and merge any ambient Remark `.remarkrc` configuration files you might have in your project. This is unrelated to the `mdat` rule configuration files, but it _can_ have an affect how Markdown is validated and rendered by `mdat`.
+
 #### Rule file format
 
 Rules may also be defined in separate files that default-export a record of rules. The record keys become the keywords used to reference a rule from your comments in Markdown.
@@ -655,12 +660,12 @@ Rules may also be defined in separate files that default-export a record of rule
 type Rules = Record<string, Rule>
 
 type Rule =
-  | string
   | ((options: JsonValue, tree: Root) => Promise<string> | string)
   | Rule[]
+  | string
   | {
-      content: string | Rule[] | ((options: JsonValue, tree: Root) => Promise<string> | string)
       applicationOrder?: number | undefined
+      content: ((options: JsonValue, tree: Root) => Promise<string> | string) | Rule[] | string
       order?: number | undefined
       required?: boolean | undefined
     }
@@ -738,10 +743,10 @@ See the [Examples section](https://github.com/kitschpatrol/remark-mdat#examples)
 
   <!-- size-table { files: ["package.json", "readme.md"] } -->
 
-  | File         | Original | Gzip   | Brotli |
-  | ------------ | -------- | ------ | ------ |
-  | package.json | 2.5 kB   | 1.1 kB | 996 B  |
-  | readme.md    | 22.8 kB  | 8.2 kB | 6.8 kB |
+  | File         | Original | Gzip    | Brotli |
+  | ------------ | -------- | ------- | ------ |
+  | package.json | 2.6 kB   | 1.2 kB  | 1 kB   |
+  | readme.md    | 57.4 kB  | 11.4 kB | 9.1 kB |
 
   <!-- /size-table -->
 
@@ -856,6 +861,10 @@ Recommended workflow integration approach:
 
 - Invoke via hooks / GitHub actions?
 
+Architectural improvements:
+
+- Use [unified-engine](https://github.com/unifiedjs/unified-engine) to handle file loading and transformation.
+
 ## Maintainers
 
 [@kitschpatrol](https://github.com/kitschpatrol)