mdat 0.10.0 → 1.0.1

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/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

@@ -5,12 +5,6 @@ export declare function getInputOutputPaths(inputs: string[], output: string | u
     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,71 +1,69 @@
 {
   "name": "mdat",
-  "version": "0.10.0",
-  "type": "module",
-  "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",
+  "version": "1.0.1",
+  "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",
+    "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": "git+https://github.com/kitschpatrol/mdat.git"
+  },
+  "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.31",
     "@types/mdast": "^4.0.4",
-    "@types/node": "18.19.0",
+    "@types/node": "^18.19.79",
     "@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.2",
+    "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": "^10.0.1",
+    "@kitschpatrol/shared-config": "^5.2.0",
+    "bumpp": "^10.0.3",
     "chalk": "^5.4.1",
     "chevrotain": "^11.0.3",
     "find-up": "^7.0.0",
     "is-executable": "^2.0.1",
-    "mdast-util-to-markdown": "^2.1.2",
     "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",
@@ -73,14 +71,17 @@
     "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.6",
-    "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"
   },
   "publishConfig": {
     "access": "public"
@@ -89,8 +90,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

@@ -15,7 +15,7 @@
 
 <!-- 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.**
+**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.**
 
 <!-- /description -->
 
@@ -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,
@@ -557,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)
 ```
 
@@ -582,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()`.
@@ -634,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
 }
 ```
@@ -660,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
     }
@@ -745,8 +745,8 @@ See the [Examples section](https://github.com/kitschpatrol/remark-mdat#examples)
 
   | 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 |
+  | package.json | 2.7 kB   | 1.2 kB  | 1.1 kB |
+  | readme.md    | 57.5 kB  | 11.4 kB | 9.1 kB |
 
   <!-- /size-table -->