@markupme/core 0.0.0-stage → 0.1.1

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,37 @@
+# Third-party notices
+
+`@markupme/core` contains code ported to TypeScript from these MIT-licensed projects:
+
+| File | Ported from | Copyright |
+| ---- | ----------- | --------- |
+| `src/render/katex.ts` | [rehype-katex](https://github.com/remarkjs/remark-math/tree/main/packages/rehype-katex) 7.0.1 | Copyright (c) Junyoung Choi <fluke8259@gmail.com> |
+| `src/plugins/math.ts` | [remark-math](https://github.com/remarkjs/remark-math/tree/main/packages/remark-math) 6.0.0 | Copyright (c) Junyoung Choi <fluke8259@gmail.com> |
+| `src/plugins/math-syntax.ts` | [micromark-extension-math](https://github.com/micromark/micromark-extension-math) 3.1.0 | Copyright (c) 2020 Titus Wormer <tituswormer@gmail.com> |
+
+All three are distributed under the MIT License:
+
+```text
+(The MIT License)
+
+Copyright (c) Junyoung Choi <fluke8259@gmail.com>
+Copyright (c) 2020 Titus Wormer <tituswormer@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+```

package/dist/format.d.ts

@@ -0,0 +1,3 @@
+import type { Diagnostic } from './types.js';
+/** `file:line:col severity code message (rule)`: the format editors and CI annotate from. */
+export declare function formatDiagnostic(d: Diagnostic): string;

package/dist/format.js

@@ -0,0 +1,5 @@
+/** `file:line:col severity code message (rule)`: the format editors and CI annotate from. */
+export function formatDiagnostic(d) {
+    const where = [d.file ?? '<input>', d.line, d.column].filter((x) => x !== undefined).join(':');
+    return `${where} ${d.severity} ${d.code} ${d.message} (${d.rule})`;
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { formatDiagnostic } from './format.js';
+export { ALERT_TITLES, ALERT_TYPES, type AlertType } from './plugins/alerts.js';
+export { CALLOUTS, CONTAINERS, LEAF_DIRECTIVES, TEXT_DIRECTIVES } from './plugins/directives.js';
+export { headingId, type OutlineItem, outline } from './plugins/headings.js';
+export { buildToc, insertToc, type TocNode } from './plugins/toc.js';
+export { type BuiltinTransform, createProcessor, MarkupMeError, type Processor, parse, render, serialize, type TransformOptions, type TransformResult, transform, validate, } from './processor.js';
+export { markupmeSchema } from './render/schema.js';
+export type { SerializeFormat, SerializeOptions } from './serialize.js';
+export * from './types.js';
+export { type BlockChange, type DocumentStats, diff, escapeHtml, query, stats, stripPositions, visit, } from './util.js';
+export { RULES } from './validate.js';
+export { VERSION } from './version.js';

package/dist/index.js

@@ -0,0 +1,11 @@
+export { formatDiagnostic } from './format.js';
+export { ALERT_TITLES, ALERT_TYPES } from './plugins/alerts.js';
+export { CALLOUTS, CONTAINERS, LEAF_DIRECTIVES, TEXT_DIRECTIVES } from './plugins/directives.js';
+export { headingId, outline } from './plugins/headings.js';
+export { buildToc, insertToc } from './plugins/toc.js';
+export { createProcessor, MarkupMeError, parse, render, serialize, transform, validate, } from './processor.js';
+export { markupmeSchema } from './render/schema.js';
+export * from './types.js';
+export { diff, escapeHtml, query, stats, stripPositions, visit, } from './util.js';
+export { RULES } from './validate.js';
+export { VERSION } from './version.js';

package/dist/parse.d.ts

@@ -0,0 +1,6 @@
+import { type PluggableList } from 'unified';
+import { type MarkupMeDocument, type ParseOptions, type ProcessorOptions, type TocOptions } from './types.js';
+/** Syntax extensions shared by the parser and the serializer, so round trips keep every construct. */
+export declare function syntaxPlugins(opts: ProcessorOptions): PluggableList;
+export declare function tocOptions(opts: ProcessorOptions): TocOptions | undefined;
+export declare function parseDocument(source: string, opts: ProcessorOptions, parseOpts?: ParseOptions): MarkupMeDocument;

package/dist/parse.js

@@ -0,0 +1,66 @@
+import remarkDirective from 'remark-directive';
+import remarkFrontmatter from 'remark-frontmatter';
+import remarkGfm from 'remark-gfm';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+import { annotateAlerts } from './plugins/alerts.js';
+import { normalizeDirectives } from './plugins/directives.js';
+import { readFrontmatter } from './plugins/frontmatter.js';
+import { addHeadingIds } from './plugins/headings.js';
+import { remarkMath } from './plugins/math.js';
+import { insertToc } from './plugins/toc.js';
+import { SCHEMA_VERSION, } from './types.js';
+/** Syntax extensions shared by the parser and the serializer, so round trips keep every construct. */
+export function syntaxPlugins(opts) {
+    const list = [];
+    if (opts.gfm !== false)
+        list.push(remarkGfm);
+    if (opts.frontmatter !== false)
+        list.push([remarkFrontmatter, ['yaml', 'toml']]);
+    if (opts.directives !== false)
+        list.push(remarkDirective);
+    if (opts.math === true)
+        list.push(remarkMath);
+    for (const p of opts.plugins ?? [])
+        if (p.remarkPlugins)
+            list.push(...p.remarkPlugins);
+    return list;
+}
+export function tocOptions(opts) {
+    if (opts.toc === false)
+        return undefined;
+    return opts.toc === true || opts.toc === undefined ? {} : opts.toc;
+}
+export function parseDocument(source, opts, parseOpts = {}) {
+    const processor = unified().use(remarkParse).use(syntaxPlugins(opts));
+    const tree = processor.runSync(processor.parse(source));
+    const diagnostics = [];
+    const file = parseOpts.file;
+    const report = (d) => diagnostics.push(file ? { ...d, file } : d);
+    const doc = {
+        type: 'markupme-document',
+        schemaVersion: SCHEMA_VERSION,
+        source,
+        tree,
+        diagnostics,
+        ...(file ? { file } : {}),
+    };
+    if (opts.frontmatter !== false) {
+        const fm = readFrontmatter(tree, report);
+        if (fm)
+            doc.frontmatter = fm;
+    }
+    if (opts.directives !== false)
+        normalizeDirectives(tree, report);
+    if (opts.alerts !== false)
+        annotateAlerts(tree);
+    if (opts.headingIds !== false)
+        addHeadingIds(tree, report);
+    const toc = tocOptions(opts);
+    if (toc)
+        insertToc(tree, toc);
+    const ctx = { doc, options: opts, report };
+    for (const p of opts.plugins ?? [])
+        p.parse?.(tree, ctx);
+    return doc;
+}

package/dist/plugins/alerts.d.ts

@@ -0,0 +1,8 @@
+import type { Root } from 'mdast';
+export declare const ALERT_TYPES: readonly ['note', 'tip', 'important', 'warning', 'caution'];
+export type AlertType = (typeof ALERT_TYPES)[number];
+export declare const ALERT_TITLES: Record<AlertType, string>;
+/** Parse time: records `data.alert` on `> [!NOTE]` blockquotes. The tree text is untouched. */
+export declare function annotateAlerts(tree: Root): void;
+/** Render time (on a copy): turns annotated blockquotes into GitHub-style alert boxes. */
+export declare function presentAlerts(tree: Root): void;

package/dist/plugins/alerts.js

@@ -0,0 +1,50 @@
+import { visit } from 'unist-util-visit';
+export const ALERT_TYPES = ['note', 'tip', 'important', 'warning', 'caution'];
+const MARKER = /^\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\][ \t]*(?:\r?\n|$)/i;
+export const ALERT_TITLES = {
+    note: 'Note',
+    tip: 'Tip',
+    important: 'Important',
+    warning: 'Warning',
+    caution: 'Caution',
+};
+/** Parse time: records `data.alert` on `> [!NOTE]` blockquotes. The tree text is untouched. */
+export function annotateAlerts(tree) {
+    visit(tree, 'blockquote', (node) => {
+        const first = node.children[0];
+        if (first?.type !== 'paragraph')
+            return;
+        const text = first.children[0];
+        if (text?.type !== 'text')
+            return;
+        const m = MARKER.exec(text.value);
+        if (!m?.[1])
+            return;
+        node.data = { ...node.data, alert: m[1].toLowerCase() };
+    });
+}
+/** Render time (on a copy): turns annotated blockquotes into GitHub-style alert boxes. */
+export function presentAlerts(tree) {
+    visit(tree, 'blockquote', (node) => {
+        const type = node.data?.alert;
+        if (!type)
+            return;
+        const first = node.children[0];
+        const text = first.children[0];
+        if (text?.type === 'text')
+            text.value = text.value.replace(MARKER, '');
+        if (first.children.length === 1 && text?.type === 'text' && text.value === '')
+            node.children.shift();
+        const title = {
+            type: 'paragraph',
+            children: [{ type: 'text', value: ALERT_TITLES[type] }],
+            data: { hProperties: { className: ['markdown-alert-title'] } },
+        };
+        node.children.unshift(title);
+        node.data = {
+            ...node.data,
+            hName: 'div',
+            hProperties: { className: ['markdown-alert', `markdown-alert-${type}`], role: 'note' },
+        };
+    });
+}

package/dist/plugins/directives.d.ts

@@ -0,0 +1,16 @@
+import type { Root } from 'mdast';
+import type { Diagnostic } from '../types.js';
+/** `:::name` containers rendered as callout boxes. */
+export declare const CALLOUTS: string[];
+export declare const CONTAINERS: string[];
+/** `:name[label]` inline directives. */
+export declare const TEXT_DIRECTIVES: string[];
+/** `::name` leaf directives. `toc` is handled by the TOC plugin. */
+export declare const LEAF_DIRECTIVES: string[];
+/**
+ * Parse time: a text directive with no label and no attributes (`10:30`, `note:this`) is almost
+ * always prose, so it goes back to plain text. Unknown directives are reported, never dropped.
+ */
+export declare function normalizeDirectives(tree: Root, report: (d: Diagnostic) => void): void;
+/** Render time (on a copy): maps directives to HTML elements. */
+export declare function presentDirectives(tree: Root): void;

package/dist/plugins/directives.js

@@ -0,0 +1,126 @@
+import { toString as mdToString } from 'mdast-util-to-string';
+import { SKIP, visit } from 'unist-util-visit';
+/** `:::name` containers rendered as callout boxes. */
+export const CALLOUTS = [
+    'note',
+    'tip',
+    'info',
+    'important',
+    'warning',
+    'caution',
+    'danger',
+    'success',
+];
+export const CONTAINERS = [...CALLOUTS, 'details', 'figure', 'columns', 'column'];
+/** `:name[label]` inline directives. */
+export const TEXT_DIRECTIVES = ['kbd', 'abbr', 'mark', 'sub', 'sup', 'badge'];
+/** `::name` leaf directives. `toc` is handled by the TOC plugin. */
+export const LEAF_DIRECTIVES = ['toc', 'br'];
+function isLabel(node) {
+    return (node?.type === 'paragraph' &&
+        node.data?.directiveLabel === true);
+}
+/**
+ * Parse time: a text directive with no label and no attributes (`10:30`, `note:this`) is almost
+ * always prose, so it goes back to plain text. Unknown directives are reported, never dropped.
+ */
+export function normalizeDirectives(tree, report) {
+    visit(tree, (node, index, parent) => {
+        if (node.type !== 'textDirective' &&
+            node.type !== 'leafDirective' &&
+            node.type !== 'containerDirective')
+            return;
+        const d = node;
+        const hasAttrs = d.attributes && Object.keys(d.attributes).length > 0;
+        if (d.type === 'textDirective' &&
+            d.children.length === 0 &&
+            !hasAttrs &&
+            parent &&
+            index !== undefined) {
+            parent.children.splice(index, 1, { type: 'text', value: `:${d.name}` });
+            return [SKIP, index];
+        }
+        const known = d.type === 'textDirective'
+            ? TEXT_DIRECTIVES
+            : d.type === 'leafDirective'
+                ? LEAF_DIRECTIVES
+                : CONTAINERS;
+        if (!known.includes(d.name)) {
+            report({
+                code: 'MM009',
+                rule: 'unknown-directive',
+                severity: 'warning',
+                message: `Unknown directive "${d.name}" (${d.type.replace('Directive', '')}); its content is rendered as-is`,
+                line: d.position?.start.line,
+                column: d.position?.start.column,
+            });
+        }
+        return undefined;
+    });
+}
+function setH(node, hName, hProperties = {}) {
+    node.data = { ...node.data, hName, hProperties: { ...hProperties } };
+}
+/** Render time (on a copy): maps directives to HTML elements. */
+export function presentDirectives(tree) {
+    visit(tree, (node) => {
+        if (node.type !== 'textDirective' &&
+            node.type !== 'leafDirective' &&
+            node.type !== 'containerDirective')
+            return;
+        const d = node;
+        const attrs = d.attributes ?? {};
+        if (d.type === 'containerDirective') {
+            const label = isLabel(d.children[0]) ? d.children.shift() : undefined;
+            const title = attrs.title ?? (label ? mdToString(label) : undefined);
+            if (CALLOUTS.includes(d.name)) {
+                setH(d, 'div', { className: ['mm-callout', `mm-callout-${d.name}`], role: 'note' });
+                const heading = title ?? d.name.charAt(0).toUpperCase() + d.name.slice(1);
+                d.children.unshift({
+                    type: 'paragraph',
+                    children: label && !attrs.title ? label.children : [{ type: 'text', value: heading }],
+                    data: { hProperties: { className: ['mm-callout-title'] } },
+                });
+            }
+            else if (d.name === 'details') {
+                setH(d, 'details', attrs.open !== undefined ? { open: true } : {});
+                d.children.unshift({
+                    type: 'paragraph',
+                    children: label ? label.children : [{ type: 'text', value: title ?? 'Details' }],
+                    data: { hName: 'summary' },
+                });
+            }
+            else if (d.name === 'figure') {
+                setH(d, 'figure', { className: ['mm-figure'] });
+                if (label)
+                    d.children.push({
+                        type: 'paragraph',
+                        children: label.children,
+                        data: { hName: 'figcaption' },
+                    });
+            }
+            else if (d.name === 'columns')
+                setH(d, 'div', { className: ['mm-columns'] });
+            else if (d.name === 'column')
+                setH(d, 'div', { className: ['mm-column'] });
+            else
+                setH(d, 'div', { className: ['mm-directive', `mm-directive-${d.name}`] });
+        }
+        else if (d.type === 'textDirective') {
+            if (d.name === 'kbd' || d.name === 'mark' || d.name === 'sub' || d.name === 'sup')
+                setH(d, d.name);
+            else if (d.name === 'abbr')
+                setH(d, 'abbr', attrs.title ? { title: attrs.title } : {});
+            else if (d.name === 'badge')
+                setH(d, 'span', { className: ['mm-badge', `mm-badge-${attrs.type ?? 'default'}`] });
+            else
+                setH(d, 'span', { className: ['mm-directive', `mm-directive-${d.name}`] });
+        }
+        else {
+            if (d.name === 'br')
+                setH(d, 'br');
+            else
+                setH(d, 'div', { className: ['mm-directive', `mm-directive-${d.name}`] });
+        }
+    });
+}

package/dist/plugins/emoji.d.ts

@@ -0,0 +1,3 @@
+import type { Root } from 'mdast';
+/** Render time: replaces GitHub `:shortcode:` names with emoji. Unknown names stay as written. */
+export declare function presentEmoji(tree: Root): void;

package/dist/plugins/emoji.js

@@ -0,0 +1,22 @@
+import { gemoji } from 'gemoji';
+import { visit } from 'unist-util-visit';
+let names;
+function lookup() {
+    if (!names) {
+        names = new Map();
+        for (const entry of gemoji)
+            for (const name of entry.names)
+                names.set(name, entry.emoji);
+    }
+    return names;
+}
+const SHORTCODE = /:([a-z0-9_+-]+):/g;
+/** Render time: replaces GitHub `:shortcode:` names with emoji. Unknown names stay as written. */
+export function presentEmoji(tree) {
+    const map = lookup();
+    visit(tree, 'text', (node) => {
+        if (!node.value.includes(':'))
+            return;
+        node.value = node.value.replace(SHORTCODE, (whole, name) => map.get(name) ?? whole);
+    });
+}

package/dist/plugins/frontmatter.d.ts

@@ -0,0 +1,4 @@
+import type { Root } from 'mdast';
+import type { Diagnostic } from '../types.js';
+/** Reads the first YAML or TOML frontmatter block. Invalid data is reported, never thrown. */
+export declare function readFrontmatter(tree: Root, report: (d: Diagnostic) => void): Record<string, unknown> | undefined;

package/dist/plugins/frontmatter.js

@@ -0,0 +1,37 @@
+import { parse as parseToml } from 'smol-toml';
+import { parse as parseYaml } from 'yaml';
+/** Reads the first YAML or TOML frontmatter block. Invalid data is reported, never thrown. */
+export function readFrontmatter(tree, report) {
+    const node = tree.children[0];
+    if (!node || (node.type !== 'yaml' && node.type !== 'toml'))
+        return undefined;
+    const value = node.value;
+    try {
+        const data = node.type === 'yaml' ? parseYaml(value) : parseToml(value);
+        if (data === null || data === undefined)
+            return {};
+        if (typeof data !== 'object' || Array.isArray(data)) {
+            report({
+                code: 'MM010',
+                rule: 'invalid-frontmatter',
+                severity: 'error',
+                message: 'Frontmatter must be a mapping of keys to values',
+                line: node.position?.start.line,
+                column: 1,
+            });
+            return undefined;
+        }
+        return data;
+    }
+    catch (error) {
+        report({
+            code: 'MM010',
+            rule: 'invalid-frontmatter',
+            severity: 'error',
+            message: `Invalid ${node.type.toUpperCase()} frontmatter: ${error.message.split('\n')[0]}`,
+            line: node.position?.start.line,
+            column: 1,
+        });
+        return undefined;
+    }
+}

package/dist/plugins/headings.d.ts

@@ -0,0 +1,18 @@
+import type { Heading, Root } from 'mdast';
+import type { Diagnostic } from '../types.js';
+export declare function headingId(node: Heading): string | undefined;
+/**
+ * Gives every heading a GitHub-compatible id in `data.hProperties.id`.
+ * A trailing `{#custom-id}` sets the id explicitly; the marker is kept in `data.customId` so
+ * serialization can write it back.
+ */
+export declare function addHeadingIds(tree: Root, report: (d: Diagnostic) => void): void;
+export interface OutlineItem {
+    depth: number;
+    text: string;
+    id: string;
+    line?: number;
+    children: OutlineItem[];
+}
+/** The heading tree of a document. */
+export declare function outline(tree: Root): OutlineItem[];

package/dist/plugins/headings.js

@@ -0,0 +1,69 @@
+import GithubSlugger from 'github-slugger';
+import { toString as mdToString } from 'mdast-util-to-string';
+import { visit } from 'unist-util-visit';
+const CUSTOM_ID = /\s*\{#([A-Za-z][\w:.-]*)\}\s*$/;
+export function headingId(node) {
+    const id = node.data?.hProperties?.id;
+    return typeof id === 'string' ? id : undefined;
+}
+/**
+ * Gives every heading a GitHub-compatible id in `data.hProperties.id`.
+ * A trailing `{#custom-id}` sets the id explicitly; the marker is kept in `data.customId` so
+ * serialization can write it back.
+ */
+export function addHeadingIds(tree, report) {
+    const slugger = new GithubSlugger();
+    const seen = new Map();
+    visit(tree, 'heading', (node) => {
+        let id;
+        const last = node.children[node.children.length - 1];
+        if (last && last.type === 'text') {
+            const m = CUSTOM_ID.exec(last.value);
+            if (m?.[1]) {
+                id = m[1];
+                last.value = last.value.slice(0, m.index);
+                if (last.value === '')
+                    node.children.pop();
+                node.data = { ...node.data, customId: id };
+                slugger.slug(id);
+            }
+        }
+        id ??= slugger.slug(mdToString(node));
+        if (seen.has(id)) {
+            report({
+                code: 'MM003',
+                rule: 'duplicate-heading-id',
+                severity: 'warning',
+                message: `Heading id "${id}" is already used on line ${seen.get(id)}`,
+                line: node.position?.start.line,
+                column: node.position?.start.column,
+            });
+        }
+        else
+            seen.set(id, node.position?.start.line ?? 0);
+        node.data = { ...node.data, hProperties: { ...node.data?.hProperties, id } };
+    });
+}
+/** The heading tree of a document. */
+export function outline(tree) {
+    const roots = [];
+    const stack = [];
+    visit(tree, 'heading', (node) => {
+        const item = {
+            depth: node.depth,
+            text: mdToString(node),
+            id: headingId(node) ?? '',
+            line: node.position?.start.line,
+            children: [],
+        };
+        while (stack.length > 0 && stack[stack.length - 1].depth >= item.depth)
+            stack.pop();
+        const parent = stack[stack.length - 1];
+        if (parent)
+            parent.children.push(item);
+        else
+            roots.push(item);
+        stack.push(item);
+    });
+    return roots;
+}

package/dist/plugins/math-syntax.d.ts

@@ -0,0 +1,20 @@
+import type { Extension } from 'micromark-util-types';
+declare module 'micromark-util-types' {
+    interface TokenTypeMap {
+        mathFlow: 'mathFlow';
+        mathFlowFence: 'mathFlowFence';
+        mathFlowFenceMeta: 'mathFlowFenceMeta';
+        mathFlowFenceSequence: 'mathFlowFenceSequence';
+        mathFlowValue: 'mathFlowValue';
+        mathText: 'mathText';
+        mathTextData: 'mathTextData';
+        mathTextPadding: 'mathTextPadding';
+        mathTextSequence: 'mathTextSequence';
+    }
+}
+export interface MathSyntaxOptions {
+    /** Whether `$x$` (one dollar) is text math. Default `true`. */
+    singleDollarTextMath?: boolean | null | undefined;
+}
+/** micromark extension for math syntax. */
+export declare function mathSyntax(options?: MathSyntaxOptions | null): Extension;