remark-mdat 0.7.4 → 1.0.0

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,63 +1,67 @@
 {
   "name": "remark-mdat",
-  "version": "0.7.4",
-  "type": "module",
+  "version": "1.0.0",
   "description": "A remark plugin implementing the Markdown Autophagic Template (MDAT) system.",
-  "repository": "github:kitschpatrol/remark-mdat",
+  "keywords": [
+    "mdat",
+    "markdown",
+    "template",
+    "comments",
+    "unist",
+    "mdast",
+    "mdast-util",
+    "syntax-tree",
+    "remark",
+    "remark-plugin"
+  ],
   "homepage": "https://github.com/kitschpatrol/remark-mdat",
   "bugs": "https://github.com/kitschpatrol/remark-mdat/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/github:kitschpatrol/remark-mdat"
+  },
+  "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"
-  },
+  "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
     "dist/*"
   ],
-  "keywords": [
-    "mdat",
-    "markdown",
-    "template",
-    "comments",
-    "unist",
-    "mdast",
-    "mdast-util",
-    "syntax-tree",
-    "remark",
-    "remark-plugin"
-  ],
   "dependencies": {
     "@types/mdast": "^4.0.4",
     "@types/node": "18.19.0",
-    "@types/unist": "^3.0.3"
+    "@types/unist": "^3.0.3",
+    "type-fest": "^4.36.0",
+    "unified": "^11.0.5",
+    "vfile": "^6.0.3",
+    "zod": "^3.24.2"
   },
   "devDependencies": {
-    "@kitschpatrol/shared-config": "^4.7.11",
-    "bumpp": "^9.8.1",
-    "chalk": "^5.3.0",
+    "@kitschpatrol/shared-config": "^5.0.6",
+    "@microsoft/api-extractor": "^7.51.1",
+    "bumpp": "^10.0.3",
+    "chalk": "^5.4.1",
     "cli-table3": "^0.6.5",
-    "deepmerge-ts": "^7.1.3",
+    "deepmerge-ts": "^7.1.5",
     "hast-util-from-html": "^2.0.3",
     "json5": "^2.2.3",
     "remark": "^15.0.1",
-    "remark-gfm": "^4.0.0",
-    "tsup": "^8.3.5",
-    "type-fest": "^4.26.1",
-    "typescript": "^5.6.3",
-    "unified": "^11.0.5",
+    "remark-gfm": "^4.0.1",
+    "tsup": "^8.4.0",
+    "typescript": "~5.7.3",
     "unist-util-visit": "^5.0.0",
-    "vfile": "^6.0.3",
     "vfile-message": "^4.0.2",
-    "vitest": "^2.1.4",
-    "zod": "^3.23.8"
+    "vitest": "^3.0.7"
+  },
+  "engines": {
+    "node": "^18.19.0 || >=20.5.0",
+    "pnpm": ">=10.0.0"
   },
   "publishConfig": {
     "access": "public"
@@ -66,8 +70,8 @@
     "build": "tsup && tsc -p tsconfig.build.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"
   }

package/readme.md

@@ -19,7 +19,8 @@
 
 <!-- /description -->
 
-> \[!NOTE]\
+> [!NOTE]
+>
 > **Please see The [`mdat` package](https://github.com/kitschpatrol/mdat) for a higher-level CLI tool and library with a collection of built-in expansion rules.**
 
 <!-- table-of-contents -->
@@ -100,11 +101,11 @@ The plugin accepts an optional options object which exposes some configuration o
 
 ```ts
 export type Options = {
-  addMetaComment?: boolean // default: false
-  closingPrefix?: string // default: '/',
-  keywordPrefix?: string // default: '',
-  metaCommentIdentifier?: string // default: '+',
-  rules?: Rules // default: a single test rule for the 'mdat' keyword
+  addMetaComment?: boolean // Default: false
+  closingPrefix?: string // Default: '/',
+  keywordPrefix?: string // Default: '',
+  metaCommentIdentifier?: string // Default: '+',
+  rules?: Rules // Default: a single test rule for the 'mdat' keyword
 }
 ```
 
@@ -137,7 +138,7 @@ If you wanted to replace `<!-- time -->` comments in your Markdown file with the
 
 ```ts
 import { remark } from 'remark'
-import { type Rules, default as remarkMdat } from 'remark-mdat'
+import remarkMdat, { type Rules } from 'remark-mdat'
 
 // Create the rule
 const rules: Rules = {

package/dist/index.d.ts

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

@@ -1,16 +0,0 @@
-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

@@ -1,13 +0,0 @@
-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

@@ -1,11 +0,0 @@
-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

@@ -1,9 +0,0 @@
-import type { Root } from 'mdast';
-import { type Html, type 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

@@ -1,11 +0,0 @@
-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

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

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

@@ -1,12 +0,0 @@
-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

@@ -1,20 +0,0 @@
-import type { Node } from 'unist';
-import { type VFile } from 'vfile';
-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

@@ -1,62 +0,0 @@
-import type { JsonValue } from 'type-fest';
-import { type Html, type Parent } from 'mdast';
-import { type Simplify } from 'type-fest';
-/**
- * Structured data about a parsed comment.
- * Note that this is a discriminated union based on the `type` field.
- */
-export 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<{
-    /** Original Mdast HTML Node where the comment was found. */
-    node: Html;
-    /** Parent of original Mdast HTML Node where the comment was found. */
-    parent: Parent;
-} & CommentMarker>;
-export 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;

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

@@ -1,117 +0,0 @@
-import type { Merge, MergeDeep, SetOptional, Simplify } from 'type-fest';
-import { type Root } from 'mdast';
-import { type JsonValue } from 'type-fest';
-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>>;
-export declare const normalizedRulesSchema: z.ZodRecord<z.ZodString, z.ZodType<any, z.ZodTypeDef, any>>;
-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

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