remark-mdat 1.0.5 → 1.1.0

package/dist/index.d.ts

@@ -1,10 +1,228 @@
-export { mdat, type Options as MdatOptions } from './lib/mdast-utils/mdast-util-mdat';
-export { mdatCheck, type Options as MdatCheckOptions, } from './lib/mdast-utils/mdast-util-mdat-check';
-export { mdatClean, type Options as MdatCleanOptions, } from './lib/mdast-utils/mdast-util-mdat-clean';
-export { mdatExpand, type Options as MdatExpandOptions, } from './lib/mdast-utils/mdast-util-mdat-expand';
-export { mdatSplit } from './lib/mdast-utils/mdast-util-mdat-split';
-export { deepMergeDefined } from './lib/mdat/deep-merge-defined';
-export { default as log } from './lib/mdat/log';
-export { getMdatReports, type MdatFileReport, type MdatMessage, reporterMdat, } from './lib/mdat/mdat-log';
-export { getSoleRule, getSoleRuleKey, type NormalizedRule, type NormalizedRules, type Rule, type Rules, rulesSchema, type SimplifyDeep, } from './lib/mdat/rules';
-export { default, type Options, optionsSchema } from './lib/remark-mdat';
+import { z } from "zod";
+import { Plugin } from "unified";
+import { VFile } from "vfile";
+import { Root } from "mdast";
+import { JsonValue, Merge, MergeDeep, SetOptional, Simplify } from "type-fest";
+
+//#region src/lib/mdat/rules.d.ts
+type SimplifyDeep<T> = Simplify<MergeDeep<T, T>>;
+/**
+ * Strict normalized rules used internally.
+ * Rules normalized to a form with async content functions and other default metadata
+ * Simplifies processing elsewhere, while retaining flexibility for rule authors
+ */
+type NormalizedRule = {
+  /**
+   * The order in which the rule should be applied during processing
+   * Helpful if a rule depends on the presence of content generated by another rule
+   * Defaults to 0.
+   */
+  applicationOrder: number;
+  /**
+   * The function that generates the expanded Markdown string.
+   * For 'compound' rules, this can be an array of rules (without keywords).
+   */
+  content: ((options: JsonValue, tree: Root) => Promise<string>) | NormalizedRule[];
+  /**
+   * The expected order of the keyword in the document relative to other expander comments.
+   * Used for validation purposes.
+   * Leave undefined to order skip validation.
+   * Defaults to undefined, which means order is not enforced.
+   */
+  order: number | undefined;
+  /**
+   * Whether the presence of the keyword comment in the document is required.
+   * Used for validation purposes.
+   * Defaults to false.
+   */
+  required: boolean;
+};
+type Rule =
+/**
+ * Function that returns the Markdown string to expand at the comment site.
+ */
+((options: JsonValue, tree: Root) => Promise<string> | string)
+/**
+ * Compound rules may be defined an array of rules, without keywords.
+ * Can be defined at the top level, if no validation metadata is required, or as the 'content' value
+ * of a rule object with validation metadata.
+ */ | Rule[]
+/**
+ * The Markdown string to expand at the comment site.
+ */ | SetOptional<Merge<NormalizedRule, {
+  /**
+   * Gets content to expand into the comment.
+   * Can be a simple string for direct replacement, a function that returns a string, or an async function that returns a string.
+   *
+   * If a function is provided, it will be passed the following arguments:
+   * @param options
+   * JSON value of options parsed immediately after the comment keyword in the comment, e.g.:
+   * `<!-- keyword({something: true}) -->` or
+   * `<!-- keyword {something: true}-->`
+   * Sets options to {something: true}
+   * @param tree
+   * Markdown (mdast) abstract syntax tree containing the entire parsed document. Useful for expanders that need the entire document context, such as when generating a table of contents. Do not mutate the AST, instead return a new string.
+   * @returns A string with the generated content. The string will be parsed as Markdown and inserted into the document at the comment's location.
+   */
+  content: ((options: JsonValue, tree: Root) => Promise<string> | string) | Rule[] | string;
+}>, 'applicationOrder' | 'order' | 'required'> | string;
+/**
+ * Rules are record objects whose keys match strings inside a Markdown comment, and values explain what should be expanded at the comment site.
+ *
+ * The record value may be a string, or an object containing additional metadata, possibly with a function to invoke to generate content.
+ * @example
+ * Most basic rule:
+ * ```ts
+ * { basic: 'content' }
+ * ```
+ *
+ * Rule with dynamic content:
+ * ```ts
+ * { basic: () => `${new Date().toISOString()}` }
+ * ```
+ *
+ * Rule with metadata:
+ * ```ts
+ * { basic-meta: { required: true, content: 'content'} }
+ * ```
+ *
+ * Rule with dynamic content and metadata:
+ * { basic-date: { required: true, content: () => `${new Date().toISOString()}` } }
+ */
+type Rules = SimplifyDeep<Record<string, Rule>>;
+type NormalizedRules = SimplifyDeep<Record<string, NormalizedRule>>;
+declare const rulesSchema: z.ZodRecord<z.ZodString, z.ZodType<any, z.ZodTypeDef, any>>;
+/**
+ * Returns the rule value from a single-rule record.
+ * Useful when aliasing rules or invoking them programmatically.
+ *
+ * Throws if there are no entries or more than one entry.
+ */
+declare function getSoleRule<T extends NormalizedRules | Rules>(rules: T): T[keyof T];
+/**
+ * Returns the rule key from a single-rule record.
+ * Useful for comment placeholder validation.
+ *
+ * Throws if there are no entries or more than one entry.
+ */
+declare function getSoleRuleKey<T extends NormalizedRules | Rules>(rules: T): keyof T;
+//#endregion
+//#region src/lib/mdast-utils/mdast-util-mdat.d.ts
+type Options$3 = {
+  addMetaComment: boolean;
+  closingPrefix: string;
+  keywordPrefix: string;
+  metaCommentIdentifier: string;
+  rules: Rules;
+};
+declare function mdat(tree: Root, file: VFile, options: Options$3): Promise<void>;
+//#endregion
+//#region src/lib/mdast-utils/mdast-util-mdat-check.d.ts
+type Options = {
+  addMetaComment: boolean;
+  closingPrefix: string;
+  keywordPrefix: string;
+  metaCommentIdentifier: string;
+  /** Enable extra checks, too noisy for real life. */
+  paranoid: boolean;
+  rules: Rules;
+};
+/**
+ * Mdast utility function to check mdat source document, and output.
+ */
+declare function mdatCheck(tree: Root, file: VFile, options: Options): Promise<void>;
+//#endregion
+//#region src/lib/mdast-utils/mdast-util-mdat-clean.d.ts
+type Options$1 = {
+  closingPrefix: string;
+  keywordPrefix: string;
+  metaCommentIdentifier: string;
+};
+/**
+ * Collapses any expanded mdat comments and removes meta comments,
+ * effectively resetting the document to its pre-expansion state. No-op if no
+ * mdat comments are found.
+ */
+declare function mdatClean(tree: Root, file: VFile, options: Options$1): void;
+//#endregion
+//#region src/lib/mdast-utils/mdast-util-mdat-expand.d.ts
+type Options$2 = {
+  addMetaComment: boolean;
+  closingPrefix: string;
+  keywordPrefix: string;
+  metaCommentIdentifier: string;
+  rules: Rules;
+};
+declare function mdatExpand(tree: Root, file: VFile, options: Options$2): Promise<void>;
+//#endregion
+//#region src/lib/mdast-utils/mdast-util-mdat-split.d.ts
+/**
+ * Mdast utility plugin to split any multi-comment nodes and their content into individual MDAST HTML
+ * nodes. They're wrapped in a paragraph so as not to introduce new breaks.
+ */
+declare function mdatSplit(tree: Root, file: VFile): void;
+//#endregion
+//#region src/lib/mdat/deep-merge-defined.d.ts
+declare function deepMergeDefined<T extends Record<string, unknown>>(...objects: T[]): T;
+//#endregion
+//#region src/lib/mdat/log.d.ts
+declare const log: {
+  verbose: boolean;
+  log(...data: unknown[]): void;
+  logPrefixed(prefix: string, ...data: unknown[]): void;
+  info(...data: unknown[]): void;
+  infoPrefixed(prefix: string, ...data: unknown[]): void;
+  warn(...data: unknown[]): void;
+  warnPrefixed(prefix: string, ...data: unknown[]): void;
+  error(...data: unknown[]): void;
+  errorPrefixed(prefix: string, ...data: unknown[]): void;
+};
+//#endregion
+//#region src/lib/mdat/mdat-log.d.ts
+/**
+ * Tries to provide a simpler wrapper to vfile.message
+ */
+type MdatMessage = {
+  column?: number;
+  level: 'error' | 'info' | 'warn';
+  line?: number;
+  message: string;
+  source?: string;
+};
+type MdatFileReport = {
+  destinationPath?: string;
+  errors: MdatMessage[];
+  infos: MdatMessage[];
+  sourcePath: string;
+  warnings: MdatMessage[];
+};
+declare function getMdatReports(files: VFile[]): MdatFileReport[];
+declare function reporterMdat(files: VFile[]): void;
+//#endregion
+//#region src/lib/remark-mdat.d.ts
+type Options$4 = Partial<Options$3>;
+declare const optionsSchema: z.ZodObject<{
+  addMetaComment: z.ZodOptional<z.ZodBoolean>;
+  closingPrefix: z.ZodOptional<z.ZodString>;
+  keywordPrefix: z.ZodOptional<z.ZodString>;
+  metaCommentIdentifier: z.ZodOptional<z.ZodString>;
+  rules: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<any, z.ZodTypeDef, any>>>;
+}, "strip", z.ZodTypeAny, {
+  addMetaComment?: boolean | undefined;
+  closingPrefix?: string | undefined;
+  keywordPrefix?: string | undefined;
+  metaCommentIdentifier?: string | undefined;
+  rules?: Record<string, any> | undefined;
+}, {
+  addMetaComment?: boolean | undefined;
+  closingPrefix?: string | undefined;
+  keywordPrefix?: string | undefined;
+  metaCommentIdentifier?: string | undefined;
+  rules?: Record<string, any> | undefined;
+}>;
+/**
+ * A remark plugin that expands HTML comments in Markdown files.
+ */
+declare const remarkMdat: Plugin<[Options$4], Root>;
+//#endregion
+export { type Options as MdatCheckOptions, type Options$1 as MdatCleanOptions, type Options$2 as MdatExpandOptions, type MdatFileReport, type MdatMessage, type Options$3 as MdatOptions, type NormalizedRule, type NormalizedRules, type Options$4 as Options, type Rule, type Rules, type SimplifyDeep, deepMergeDefined, remarkMdat as default, getMdatReports, getSoleRule, getSoleRuleKey, log, mdat, mdatCheck, mdatClean, mdatExpand, mdatSplit, optionsSchema, reporterMdat, rulesSchema };