mdat 0.6.12 → 0.6.14

package/dist/src/cli/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli/options.d.ts

@@ -0,0 +1,63 @@
+export declare const configOption: {
+    readonly config: {
+        readonly defaultDescription: "Configuration is loaded if found from the usual places, or defaults are used.";
+        readonly description: "Path(s) to files containing MDAT configuration.";
+        readonly string: true;
+        readonly type: "array";
+    };
+};
+export declare const metaOption: {
+    readonly meta: {
+        readonly alias: "m";
+        readonly description: "Embed an extra comment at the top of the generated Markdown warning editors that certain sections of the document have been generated dynamically.";
+        readonly type: "boolean";
+    };
+};
+export declare const nameOption: {
+    readonly name: {
+        readonly alias: "n";
+        readonly defaultDescription: "Same name as input file. Overwrites the input file.";
+        readonly description: "Output file name.";
+        readonly type: "string";
+    };
+};
+export declare const outputOption: {
+    readonly output: {
+        readonly alias: "o";
+        readonly defaultDescription: "Same directory as input file.";
+        readonly description: "Output file directory.";
+        readonly type: "string";
+    };
+};
+export declare const prefixOption: {
+    readonly prefix: {
+        readonly description: "Require a string prefix before all comments to be considered for expansion. Useful if you have a bunch of non-MDAT comments in your Markdown file, or if you're willing to trade some verbosity for safety.";
+        readonly type: "string";
+    };
+};
+export declare const printOption: {
+    readonly print: {
+        readonly description: "Print the expanded Markdown to stdout instead of saving to a file. Ignores `--output` and `--name` options.";
+        readonly type: "boolean";
+    };
+};
+export declare const rulesOption: {
+    readonly rules: {
+        readonly alias: "r";
+        readonly description: "Path(s) to files containing MDAT comment expansion rules.";
+        readonly string: true;
+        readonly type: "array";
+    };
+};
+export declare const verboseOption: {
+    readonly verbose: {
+        readonly describe: "Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection.";
+        readonly type: "boolean";
+    };
+};
+export declare const filesPositional: ["files", {
+    readonly array: true;
+    readonly demandOption: true;
+    readonly describe: "Markdown file(s) with MDAT placeholder comments.";
+    readonly type: "string";
+}];

package/dist/src/cli/readme-options.d.ts

@@ -0,0 +1,61 @@
+export declare const packageOption: {
+    readonly package: {
+        readonly defaultDescription: "The closest package.json file is used by default.";
+        readonly description: "Path to the package.json file to use to populate the readme.";
+        readonly string: true;
+    };
+};
+export declare const assetsOption: {
+    readonly assets: {
+        readonly defaultDescription: "./assets";
+        readonly description: "Path to find and save readme-related assets.";
+        readonly string: true;
+    };
+};
+export declare const interactiveOption: {
+    readonly interactive: {
+        readonly alias: "i";
+        readonly default: true;
+        readonly description: "Run the guided interactive `init` process. Set explicitly to `false` to use default values and skip the prompt.";
+        readonly type: "boolean";
+    };
+};
+export declare const overwriteOption: {
+    readonly overwrite: {
+        readonly default: false;
+        readonly defaultDescription: "`false`, if an existing readme is found, don't touch it.";
+        readonly description: "Replace an existing readme file if one is found.";
+        readonly type: "boolean";
+    };
+};
+export declare const expandOption: {
+    readonly expand: {
+        readonly alias: "e";
+        readonly default: true;
+        readonly description: "Automatically run `mdat readme` immediately after creating the readme template.";
+        readonly type: "boolean";
+    };
+};
+export declare const templateOption: {
+    readonly template: {
+        readonly alias: "t";
+        readonly choices: string[];
+        readonly default: string;
+        readonly description: "Specify a template to use for the new readme.";
+        readonly type: "string";
+    };
+};
+export declare const compoundOption: {
+    readonly compound: {
+        readonly alias: "c";
+        readonly default: true;
+        readonly 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 readme.md output is identical.";
+        readonly type: "boolean";
+    };
+};
+export declare const filesPositionalOptional: ["files", {
+    readonly array: true;
+    readonly demandOption: false;
+    readonly describe: "Readme file(s) with MDAT placeholder comments. If not provided, the closest readme.md file is used.";
+    readonly type: "string";
+}];

package/dist/src/lib/readme/init.d.ts

@@ -0,0 +1,16 @@
+export type Symbolize<T extends Record<string, unknown>> = {
+    [x in keyof T]: T[x] | symbol;
+};
+type MdatReadmeInitOptions = {
+    compound: boolean;
+    expand: boolean;
+    output: string;
+    overwrite: boolean;
+    template: string;
+};
+export declare function initReadmeInteractive(): Promise<string>;
+/**
+ * @return Path to the created readme file.
+ */
+export declare function initReadme(options?: Partial<MdatReadmeInitOptions>): Promise<string>;
+export {};

package/dist/{readme → src/lib/readme}/rules/cli-help/utilities/get-help-markdown.d.ts

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

package/dist/src/lib/readme/rules/cli.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Simple alias for cli-help
+ */
+declare const _default: {
+    cli: {
+        content(options?: import("type-fest").JsonValue | undefined): Promise<string>;
+    };
+};
+export default _default;

package/dist/{readme → src/lib/readme}/rules/index.d.ts

@@ -1,9 +1,4 @@
 declare const _default: {
-    title: {
-        applicationOrder: number;
-        content(options?: import("type-fest").JsonValue | undefined): Promise<string>;
-        order: number;
-    };
     toc: {
         applicationOrder: number;
         content(options: import("type-fest").JsonValue, tree: import("mdast").Root): Promise<string>;
@@ -12,6 +7,11 @@ declare const _default: {
     tldraw: {
         content(options?: import("type-fest").JsonValue | undefined): Promise<string>;
     };
+    title: {
+        applicationOrder: number;
+        content(options?: import("type-fest").JsonValue | undefined): Promise<string>;
+        order: number;
+    };
     'table-of-contents': {
         applicationOrder: number;
         content(options: import("type-fest").JsonValue, tree: import("mdast").Root): Promise<string>;
@@ -54,6 +54,9 @@ declare const _default: {
     'cli-help': {
         content(options?: import("type-fest").JsonValue | undefined): Promise<string>;
     };
+    cli: {
+        content(options?: import("type-fest").JsonValue | undefined): Promise<string>;
+    };
     banner: {
         content(options?: import("type-fest").JsonValue | undefined): Promise<string>;
         order: number;

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

@@ -0,0 +1,36 @@
+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: {
+            compound: string;
+            explicit: string;
+        };
+        description: string;
+        exampleLink: "https://github.com/kitschpatrol/mdat/blob/main/readme.md";
+    };
+    'Standard Readme Basic': {
+        content: {
+            compound: string;
+            explicit: string;
+        };
+        description: string;
+        exampleLink: "https://github.com/RichardLitt/standard-readme/blob/main/example-readmes/minimal-readme.md";
+    };
+    'Standard Readme Full': {
+        content: {
+            compound: string;
+            explicit: string;
+        };
+        description: string;
+        exampleLink: "https://github.com/RichardLitt/standard-readme/blob/main/example-readmes/maximal-readme.md";
+    };
+};
+export default _default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdat",
-  "version": "0.6.12",
+  "version": "0.6.14",
   "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": {
@@ -43,43 +43,43 @@
   ],
   "dependencies": {
     "@clack/prompts": "^0.7.0",
-    "@kitschpatrol/tldraw-cli": "^4.5.3",
+    "@kitschpatrol/tldraw-cli": "^4.5.4",
     "@types/mdast": "^4.0.4",
+    "@types/node": "^20.14.1",
     "@types/unist": "^3.0.2",
-    "chalk": "^5.3.0",
-    "chevrotain": "^11.0.3",
+    "@types/which": "^3.0.4",
+    "@types/yargs": "^17.0.32",
     "cosmiconfig": "^9.0.0",
     "cosmiconfig-typescript-loader": "^5.0.0",
     "execa": "^9.1.0",
-    "find-up": "^7.0.0",
     "globby": "^14.0.1",
+    "read-pkg": "^9.0.1",
+    "which": "^4.0.0"
+  },
+  "devDependencies": {
+    "chalk": "^5.3.0",
+    "chevrotain": "^11.0.3",
+    "find-up": "^7.0.0",
     "is-executable": "^2.0.1",
-    "mdast-util-toc": "^7.0.1",
+    "mdast-util-toc": "^7.1.0",
     "nanoid": "^5.0.7",
     "package-up": "^5.0.0",
     "path-type": "^5.0.0",
     "pkg-dir": "^8.0.0",
     "plur": "^5.1.0",
     "pretty-ms": "^9.0.0",
-    "read-pkg": "^9.0.1",
     "remark": "^15.0.1",
     "remark-gfm": "^4.0.0",
     "to-vfile": "^8.0.0",
-    "type-fest": "^4.18.2",
+    "tsup": "^8.1.0",
+    "type-fest": "^4.19.0",
+    "typescript": "^5.4.5",
     "untildify": "^5.0.0",
     "vfile": "^6.0.1",
-    "which": "^4.0.0",
+    "vitest": "^1.6.0",
     "yargs": "^17.7.2",
     "zod": "^3.23.8",
-    "remark-mdat": "0.6.12"
-  },
-  "devDependencies": {
-    "@types/node": "^20.12.12",
-    "@types/which": "^3.0.3",
-    "@types/yargs": "^17.0.32",
-    "tsup": "^8.0.2",
-    "typescript": "^5.4.5",
-    "vitest": "^1.6.0"
+    "remark-mdat": "0.6.14"
   },
   "publishConfig": {
     "access": "public"

package/readme.md

@@ -701,6 +701,8 @@ See the [Examples section](../remark-mdat/readme.md#examples) of the `remark-mda
 
   ([Parsing help output](https://github.com/kitschpatrol/mdat/tree/main/packages/mdat/src/lib/readme/rules/cli-help/utilities/parsers) is a bit tricky. The [jc](https://github.com/kellyjonbrazil/jc) project is a heroic collection of output parsers, but does not currently implement help output parsing. It might be interesting to try to contribute mdat's help parsing implementations to jc.)
 
+  This rule is also aliased under the `<!-- cli -->` keyword.
+
 - ###### `<!-- tldraw -->`
 
   Allows embedding [tldraw](https://www.tldraw.com) files in your readme. Accepts either a path to a local `.tldr` file, or remote tldraw URLs.