remark-mdat 1.2.2 → 1.2.3

package/dist/index.d.ts

@@ -1,10 +1,248 @@
-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 { Root } from "mdast";
+import { VFile } from "vfile";
+import { JsonValue, MergeDeep, Simplify } from "type-fest";
+import { Plugin } from "unified";
+
+//#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.
+ */
+| string
+/**
+ * Rule object with optional validation metadata.
+ */
+| {
+  /**
+   * The order in which the rule should be applied during processing.
+   * Defaults to 0.
+   */
+  applicationOrder?: number;
+  /**
+   * 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;
+  /**
+   * The expected order of the keyword in the document relative to other expander comments.
+   * Defaults to undefined, which means order is not enforced.
+   */
+  order?: number | undefined;
+  /**
+   * Whether the presence of the keyword comment in the document is required.
+   * Defaults to false.
+   */
+  required?: boolean;
+};
+/**
+ * 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 MdatOptions = {
+  addMetaComment: boolean | string;
+  closingPrefix: string;
+  keywordPrefix: string;
+  metaCommentIdentifier: string;
+  rules: Rules;
+};
+declare function mdat(tree: Root, file: VFile, options: MdatOptions): Promise<void>;
+//#endregion
+//#region src/lib/mdast-utils/mdast-util-mdat-check.d.ts
+type MdatCheckOptions = {
+  addMetaComment: boolean | string;
+  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: MdatCheckOptions): Promise<void>;
+//#endregion
+//#region src/lib/mdast-utils/mdast-util-mdat-clean.d.ts
+type MdatCleanOptions = {
+  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: MdatCleanOptions): void;
+//#endregion
+//#region src/lib/mdast-utils/mdast-util-mdat-expand.d.ts
+type MdatExpandOptions = {
+  addMetaComment: boolean | string;
+  closingPrefix: string;
+  keywordPrefix: string;
+  metaCommentIdentifier: string;
+  rules: Rules;
+};
+declare function mdatExpand(tree: Root, file: VFile, options: MdatExpandOptions): 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 = Partial<MdatOptions>;
+declare const optionsSchema: z.ZodObject<{
+  addMetaComment: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodString]>>;
+  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, {
+  closingPrefix?: string | undefined;
+  keywordPrefix?: string | undefined;
+  addMetaComment?: string | boolean | undefined;
+  metaCommentIdentifier?: string | undefined;
+  rules?: Record<string, any> | undefined;
+}, {
+  closingPrefix?: string | undefined;
+  keywordPrefix?: string | undefined;
+  addMetaComment?: string | boolean | undefined;
+  metaCommentIdentifier?: string | undefined;
+  rules?: Record<string, any> | undefined;
+}>;
+/**
+ * A remark plugin that expands HTML comments in Markdown files.
+ */
+declare const remarkMdat: Plugin<[Options], Root>;
+//#endregion
+export { type MdatCheckOptions, type MdatCleanOptions, type MdatExpandOptions, type MdatFileReport, type MdatMessage, type MdatOptions, type NormalizedRule, type NormalizedRules, type Options, type Rule, type Rules, type SimplifyDeep, deepMergeDefined, remarkMdat as default, getMdatReports, getSoleRule, getSoleRuleKey, log, mdat, mdatCheck, mdatClean, mdatExpand, mdatSplit, optionsSchema, reporterMdat, rulesSchema };