npm - remark-mdat - Versions diffs - 1.0.0 → 1.0.1 - Mend

remark-mdat 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/dist/index.d.ts +10 -0
package/dist/lib/mdast-utils/mdast-util-mdat-check.d.ts +16 -0
package/dist/lib/mdast-utils/mdast-util-mdat-clean.d.ts +13 -0
package/dist/lib/mdast-utils/mdast-util-mdat-expand.d.ts +11 -0
package/dist/lib/mdast-utils/mdast-util-mdat-split.d.ts +8 -0
package/dist/lib/mdast-utils/mdast-util-mdat.d.ts +11 -0
package/dist/lib/mdat/deep-merge-defined.d.ts +1 -0
package/dist/lib/mdat/log.d.ts +12 -0
package/dist/lib/mdat/mdat-log.d.ts +23 -0
package/dist/lib/mdat/parse.d.ts +62 -0
package/dist/lib/mdat/rules.d.ts +112 -0
package/dist/lib/remark-mdat.d.ts +29 -0
package/package.json +1 -1

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,10 @@
+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';

package/dist/lib/mdast-utils/mdast-util-mdat-check.d.ts ADDED Viewed

@@ -0,0 +1,16 @@
+import type { Root } from 'mdast';
+import type { VFile } from 'vfile';
+import { type Rules } from '../mdat/rules';
+export 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.
+ */
+export declare function mdatCheck(tree: Root, file: VFile, options: Options): Promise<void>;

package/dist/lib/mdast-utils/mdast-util-mdat-clean.d.ts ADDED Viewed

@@ -0,0 +1,13 @@
+import type { Root } from 'mdast';
+import { type VFile } from 'vfile';
+export type Options = {
+    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.
+ */
+export declare function mdatClean(tree: Root, file: VFile, options: Options): void;

package/dist/lib/mdast-utils/mdast-util-mdat-expand.d.ts ADDED Viewed

@@ -0,0 +1,11 @@
+import type { Root } from 'mdast';
+import type { VFile } from 'vfile';
+import { type Rules } from '../mdat/rules';
+export type Options = {
+    addMetaComment: boolean;
+    closingPrefix: string;
+    keywordPrefix: string;
+    metaCommentIdentifier: string;
+    rules: Rules;
+};
+export declare function mdatExpand(tree: Root, file: VFile, options: Options): Promise<void>;

package/dist/lib/mdast-utils/mdast-util-mdat-split.d.ts ADDED Viewed

@@ -0,0 +1,8 @@
+import type { Html, Root, Text } from 'mdast';
+import type { VFile } from 'vfile';
+/**
+ * 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.
+ */
+export declare function mdatSplit(tree: Root, file: VFile): void;
+export declare function splitHtmlIntoMdastNodes(mdastNode: Html): Array<Html | Text>;

package/dist/lib/mdast-utils/mdast-util-mdat.d.ts ADDED Viewed

@@ -0,0 +1,11 @@
+import type { Root } from 'mdast';
+import { type VFile } from 'vfile';
+import { type Rules } from '../mdat/rules';
+export type Options = {
+    addMetaComment: boolean;
+    closingPrefix: string;
+    keywordPrefix: string;
+    metaCommentIdentifier: string;
+    rules: Rules;
+};
+export declare function mdat(tree: Root, file: VFile, options: Options): Promise<void>;

package/dist/lib/mdat/deep-merge-defined.d.ts ADDED Viewed

	@@ -0,0 +1 @@
1	+ export declare function deepMergeDefined<T extends Record<string, unknown>>(...objects: T[]): T;

package/dist/lib/mdat/log.d.ts ADDED Viewed

@@ -0,0 +1,12 @@
+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;
+};
+export default log;

package/dist/lib/mdat/mdat-log.d.ts ADDED Viewed

@@ -0,0 +1,23 @@
+import type { Node } from 'unist';
+import { type VFile } from 'vfile';
+/**
+ * Tries to provide a simpler wrapper to vfile.message
+ */
+export type MdatMessage = {
+    column?: number;
+    level: 'error' | 'info' | 'warn';
+    line?: number;
+    message: string;
+    source?: string;
+};
+export type MdatFileReport = {
+    destinationPath?: string;
+    errors: MdatMessage[];
+    infos: MdatMessage[];
+    sourcePath: string;
+    warnings: MdatMessage[];
+};
+export declare function saveLog(file: VFile, level: 'error' | 'info' | 'warn', source: string, message: string, line?: number, column?: number): void;
+export declare function saveLog(file: VFile, level: 'error' | 'info' | 'warn', source: string, message: string, node?: Node): void;
+export declare function getMdatReports(files: VFile[]): MdatFileReport[];
+export declare function reporterMdat(files: VFile[]): void;

package/dist/lib/mdat/parse.d.ts ADDED Viewed

@@ -0,0 +1,62 @@
+import type { Html, Parent } from 'mdast';
+import type { JsonValue, Simplify } from 'type-fest';
+/**
+ * Structured data about a parsed comment.
+ * Note that this is a discriminated union based on the `type` field.
+ */
+type CommentMarker = Simplify<{
+    /** The complete original comment, e.g. `<!-- keyword -->`  */
+    html: string;
+} & ({
+    /** Character used to delimit closing tags, e.g. the `/` in `<!-- /keyword -->`  */
+    closingPrefix: string;
+    /** The first complete word in the comment  */
+    keyword: string;
+    /** The unique keyword prefix  */
+    keywordPrefix: string;
+    /** Parsed JSON object of argument string that followed the keyword, empty object if nothing passed  */
+    options: JsonValue;
+    /**
+     * `open`: A mdat-style opening comment tag, e.g. `<!-- keyword -->`  \
+     * `close`: A mdat-style closing comment tag, e.g. `<!-- /keyword -->`
+     */
+    type: 'close' | 'open';
+} | {
+    /** The original text inside the comment, e.g. `<!-- content -->`  */
+    content: string;
+    /**
+     * `meta`: A mdat-style generated meta comment tag  \
+     * `native`: A normal comment that does not match the the `keywordPrefix` (if specified)
+     */
+    type: 'meta' | 'native';
+})>;
+/**
+ * Parsed comment with additional information about the Mdast Node and its Parent.
+ */
+export type CommentMarkerNode = Simplify<CommentMarker & {
+    /** Original Mdast HTML Node where the comment was found. */
+    node: Html;
+    /** Parent of original Mdast HTML Node where the comment was found. */
+    parent: Parent;
+}>;
+type CommentMarkerParseOptions = {
+    /** Character to identify closing tags, e.g. the `/` in `<!-- /keyword -->`  */
+    closingPrefix: string;
+    /** Prefix to require on all mdat comments, e.g. `mm-`  */
+    keywordPrefix: string;
+    /** Means of identifying mdat generated meta comments, e.g. `+`  */
+    metaCommentIdentifier: string;
+};
+/**
+ * Parse an Mdast HTML comment node into structured data.
+ * @returns A discriminated union of CommentMarkerNode based on comment type, or
+ * undefined if the node is not a comment.
+ */
+export declare function parseCommentNode(node: Html, parent: Parent, options: CommentMarkerParseOptions): CommentMarkerNode | undefined;
+/**
+ * Parse any comment string into structured data.
+ * @returns A discriminated union of CommentMarker based on comment type, or
+ * undefined if the node is not a comment.
+ */
+export declare function parseComment(text: string, options: CommentMarkerParseOptions): CommentMarker | undefined;
+export {};

package/dist/lib/mdat/rules.d.ts ADDED Viewed

@@ -0,0 +1,112 @@
+import type { JsonValue, Merge, MergeDeep, SetOptional, Simplify } from 'type-fest';
+import { type Root } from 'mdast';
+import { z } from 'zod';
+export 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
+ */
+export 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;
+};
+export 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()}` } }
+ */
+export type Rules = SimplifyDeep<Record<string, Rule>>;
+export type NormalizedRules = SimplifyDeep<Record<string, NormalizedRule>>;
+export declare function normalizeRules(rules: Rules): NormalizedRules;
+export declare function validateRules(rules: Rules): void;
+export declare const rulesSchema: z.ZodRecord<z.ZodString, z.ZodType<any, z.ZodTypeDef, any>>;
+/**
+ * Compound rule helpers, used in both "expand" and "check" utilities
+ */
+export declare function getRuleContent(rule: NormalizedRule, options: JsonValue, tree: Root, check?: boolean): Promise<string>;
+/**
+ * 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.
+ */
+export 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.
+ */
+export declare function getSoleRuleKey<T extends NormalizedRules | Rules>(rules: T): keyof T;

package/dist/lib/remark-mdat.d.ts ADDED Viewed

@@ -0,0 +1,29 @@
+import type { Root } from 'mdast';
+import type { Plugin } from 'unified';
+import { z } from 'zod';
+import { type Options as MdatOptions } from './mdast-utils/mdast-util-mdat';
+export type Options = Partial<MdatOptions>;
+export 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, {
+    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;
+    addMetaComment?: boolean | undefined;
+}>;
+/**
+ * A remark plugin that expands HTML comments in Markdown files.
+ */
+declare const remarkMdat: Plugin<[Options], Root>;
+export default remarkMdat;

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "remark-mdat",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "A remark plugin implementing the Markdown Autophagic Template (MDAT) system.",
   "keywords": [
     "mdat",