@remigius42/morg 0.4.0

package/dist/core/mdastToUniorg/phrasing.js

@@ -0,0 +1,176 @@
+import { mdismEnabled, warn } from "./context.js";
+// html tags morg itself emits under useHtml; with interpretHtml a bare
+// open/close pair becomes the corresponding native org object
+const INLINE_HTML_ORG_TYPES = {
+    u: "underline",
+    sup: "superscript",
+    sub: "subscript"
+};
+// tag names are case-insensitive and may have whitespace before
+// the closing > (valid html); attributes disqualify the tag
+function matchInlineHtmlPair(children, i) {
+    const node = children[i];
+    if (node.type !== "html") {
+        return null;
+    }
+    const tag = /^<(u|sup|sub)\s*>$/i.exec(node.value)?.[1]?.toLowerCase();
+    const orgType = tag ? INLINE_HTML_ORG_TYPES[tag] : undefined;
+    if (!orgType) {
+        return null;
+    }
+    const closeTag = new RegExp(`^</${tag}\\s*>$`, "i");
+    const end = children.findIndex((child, j) => j > i && child.type === "html" && closeTag.test(child.value));
+    return end === -1 ? null : { orgType, end };
+}
+export function transformPhrasingChildren(ctx, children) {
+    const result = [];
+    for (let i = 0; i < children.length; i++) {
+        const node = children[i];
+        const pair = ctx.options.interpretHtml
+            ? matchInlineHtmlPair(children, i)
+            : null;
+        if (pair) {
+            result.push({
+                type: pair.orgType,
+                children: transformPhrasingChildren(ctx, children.slice(i + 1, pair.end))
+            });
+            i = pair.end;
+            continue;
+        }
+        const transformed = transformMdastPhrasingContentToUniorgObject(ctx, node);
+        if (transformed) {
+            result.push(transformed);
+        }
+    }
+    return result;
+}
+// an org bracket-link path cannot contain [ or ]; percent-encoding keeps
+// the url equivalent and, unlike org's backslash escaping, survives being
+// parsed back (uniorg does not decode `\[`). A silent normalization, not
+// a drop: dialect wikilink destinations take this path routinely.
+function orgSafeUrl(url) {
+    return url.replaceAll("[", "%5B").replaceAll("]", "%5D");
+}
+function transformMdastLink(ctx, linkNode) {
+    const [only] = linkNode.children;
+    // text equal to the url (autolinks) is no description; a plain
+    // [[url]] keeps the org side canonical
+    const linkChildren = linkNode.children.length === 1 &&
+        only?.type === "text" &&
+        only.value === linkNode.url
+        ? []
+        : transformPhrasingChildren(ctx, linkNode.children);
+    // rawLink should just be the URL, uniorg-stringify adds the brackets
+    const url = orgSafeUrl(linkNode.url);
+    return {
+        type: "link",
+        format: "bracket", // Assuming bracket format for Markdown links
+        linkType: "url",
+        rawLink: url,
+        path: url,
+        children: linkChildren
+    };
+}
+function transformMdastLinkReference(ctx, node) {
+    // org has no reference-style links: resolve to an inline link
+    const definition = ctx.definitions.get(node.identifier);
+    if (!definition) {
+        return null;
+    }
+    return transformMdastPhrasingContentToUniorgObject(ctx, {
+        type: "link",
+        url: definition.url,
+        children: node.children
+    });
+}
+function transformMdastImageReference(ctx, node) {
+    const definition = ctx.definitions.get(node.identifier);
+    if (!definition) {
+        return null;
+    }
+    return transformMdastPhrasingContentToUniorgObject(ctx, {
+        type: "image",
+        url: definition.url,
+        alt: node.alt ?? null
+    });
+}
+function transformMdastImage(ctx, node) {
+    // org has no dedicated image syntax: a plain file link renders
+    // inline, alt text becomes the link description; the title
+    // attribute has no org slot and is dropped (see README)
+    if (node.title) {
+        warn(ctx, `dropped image title "${node.title}" (${node.url})`);
+    }
+    const url = orgSafeUrl(node.url);
+    return {
+        type: "link",
+        format: "bracket",
+        linkType: "file",
+        rawLink: url,
+        path: url,
+        children: node.alt ? [{ type: "text", value: node.alt }] : []
+    };
+}
+function transformMdastInlineMath(node) {
+    const value = node.value;
+    return {
+        type: "latex-fragment",
+        value: `$${value}$`,
+        contents: value
+    };
+}
+function transformMdastPhrasingContentToUniorgObject(ctx, node) {
+    switch (node.type) {
+        case "text":
+            return { type: "text", value: node.value };
+        case "emphasis":
+            return {
+                type: "italic",
+                children: transformPhrasingChildren(ctx, node.children)
+            };
+        case "strong":
+            return {
+                type: "bold",
+                children: transformPhrasingChildren(ctx, node.children)
+            };
+        case "delete":
+            return {
+                type: "strike-through",
+                children: transformPhrasingChildren(ctx, node.children)
+            };
+        case "link":
+            return transformMdastLink(ctx, node);
+        case "linkReference":
+            return transformMdastLinkReference(ctx, node);
+        case "imageReference":
+            return transformMdastImageReference(ctx, node);
+        case "inlineCode":
+            return { type: "code", value: node.value };
+        case "inlineMath":
+            return transformMdastInlineMath(node);
+        case "break":
+            return { type: "line-break" };
+        case "footnoteReference":
+            return {
+                type: "footnote-reference",
+                label: node.identifier,
+                footnoteType: "standard",
+                children: []
+            };
+        case "html":
+            // inline raw html is a md-ism: preserved as an org export snippet
+            return mdismEnabled(ctx, "html")
+                ? {
+                    type: "export-snippet",
+                    backEnd: "html",
+                    value: node.value
+                }
+                : null;
+        case "image":
+            return transformMdastImage(ctx, node);
+        // remaining phrasing types have no mapping; dropped with a warning
+        default:
+            warn(ctx, `dropped md ${node.type}`);
+            return null;
+    }
+}

package/dist/core/uniorgToMdast/elements.d.ts

@@ -0,0 +1,4 @@
+import type { RootContent } from "mdast";
+import type { ElementType, GreaterElementType, Text } from "uniorg";
+import { type TransformContext } from "./shared.js";
+export declare function transformNodes(ctx: TransformContext, nodes: (GreaterElementType | ElementType | Text)[]): RootContent[];

package/dist/core/uniorgToMdast/elements.js

@@ -0,0 +1,278 @@
+import { toString as orgastToString } from "orgast-util-to-string";
+import { affiliatedLines, keyName, keyValueParagraph, orgismEnabled, orgNodeToText, trimTrailingNewline, warn } from "./shared.js";
+import { transformUniorgObjects } from "./objects.js";
+import { transformFootnoteDefinition } from "./footnotes.js";
+import { transformTable } from "./tables.js";
+import { transformPlainList } from "./lists.js";
+export function transformNodes(ctx, nodes) {
+    return nodes
+        .flatMap(node => transformUniorgNodeToMdastNode(ctx, node))
+        .filter(Boolean);
+}
+function transformUniorgNodeToMdastNode(ctx, node) {
+    const result = transformUniorgElement(ctx, node);
+    const lines = affiliatedLines(node);
+    if (!result ||
+        !lines.length ||
+        (!Array.isArray(result) && result.type === "keyValue")) {
+        // verbatim passthroughs (keyValue) already carry their affiliated
+        // lines via orgNodeToText
+        return result;
+    }
+    return [
+        keyValueParagraph(lines),
+        ...(Array.isArray(result) ? result : [result])
+    ];
+}
+function transformUniorgElement(ctx, node) {
+    switch (node.type) {
+        case "section":
+            return transformSection(ctx, node);
+        case "headline":
+            return transformHeadline(ctx, node);
+        case "planning":
+            return transformPlanning(ctx, node);
+        case "drawer":
+            return transformDrawer(ctx, node);
+        case "special-block":
+        case "center-block":
+        case "verse-block":
+        case "comment-block":
+        case "fixed-width":
+        case "keyword":
+        case "babel-call":
+        case "diary-sexp":
+        case "clock":
+            // org-only blocks with no md equivalent travel the same way as
+            // drawers: verbatim org text, re-parsed natively on the return trip
+            // (keywords here are mid-file ones; leading ones became frontmatter)
+            return keyValueParagraph([orgNodeToText(node)]);
+        case "property-drawer":
+            return transformPropertyDrawer(ctx, node);
+        case "paragraph":
+            return transformParagraph(ctx, node);
+        case "text":
+            // Whitespace-only text at block level is a formatting artifact.
+            if (node.value.trim() === "") {
+                return null;
+            }
+            return { type: "text", value: node.value };
+        case "plain-list":
+            return transformPlainList(ctx, node);
+        case "table":
+            return transformTable(ctx, node);
+        case "horizontal-rule":
+            return { type: "thematicBreak" };
+        case "footnote-definition":
+            return transformFootnoteDefinition(ctx, node);
+        case "export-block":
+            return transformExportBlock(node);
+        case "quote-block":
+            return transformQuoteBlock(ctx, node);
+        case "src-block":
+            return transformSrcBlock(node);
+        case "example-block":
+            return transformExampleBlock(node);
+        case "comment":
+            return transformComment(node);
+        case "latex-environment":
+            return { type: "math", value: node.value };
+        // remaining element types have no mapping; dropped with a warning
+        default:
+            warn(ctx, `dropped org ${node.type}`);
+            return null;
+    }
+}
+function transformSection(ctx, node) {
+    if (ctx.options.taskCheckboxes) {
+        const task = sectionAsTaskItem(ctx, node.children || []);
+        if (task) {
+            return task;
+        }
+    }
+    return transformNodes(ctx, node.children || []);
+}
+// with taskCheckboxes, a section holding just a bare TODO/DONE headline
+// (no priority, tags or content) becomes a GFM task item; anything
+// richer keeps the heading (with a warning) so no metadata is lost
+function sectionAsTaskItem(ctx, children) {
+    const headline = children[0];
+    if (headline?.type !== "headline" || !headline.todoKeyword) {
+        return null;
+    }
+    const rest = children.slice(1);
+    const reason = headline.todoKeyword !== "TODO" && headline.todoKeyword !== "DONE"
+        ? `keyword ${headline.todoKeyword}`
+        : headline.priority
+            ? "has priority"
+            : headline.tags.length
+                ? "has tags"
+                : rest.some(child => !(child.type === "text" && child.value.trim() === ""))
+                    ? "has content"
+                    : null;
+    if (reason) {
+        warn(ctx, `taskCheckboxes: kept heading "${orgastToString(headline).trim()}" (${reason})`);
+        return null;
+    }
+    return {
+        type: "list",
+        ordered: false,
+        spread: false,
+        children: [
+            {
+                type: "listItem",
+                spread: false,
+                checked: headline.todoKeyword === "DONE",
+                children: [
+                    {
+                        type: "paragraph",
+                        children: transformUniorgObjects(ctx, headline.children)
+                    }
+                ]
+            }
+        ]
+    };
+}
+function transformHeadline(ctx, node) {
+    const heading = {
+        type: "heading",
+        depth: node.level,
+        children: transformUniorgObjects(ctx, node.children)
+    };
+    // org-isms serialize as key:: value lines directly below the heading
+    const isms = [];
+    if (node.todoKeyword && orgismEnabled(ctx, "todo")) {
+        isms.push(`${keyName(ctx, "todo")}:: ${node.todoKeyword}`);
+    }
+    if (node.priority && orgismEnabled(ctx, "priority")) {
+        isms.push(`${keyName(ctx, "priority")}:: ${node.priority}`);
+    }
+    if (node.tags.length && orgismEnabled(ctx, "tags")) {
+        isms.push(`${keyName(ctx, "tags")}:: ${node.tags.join(", ")}`);
+    }
+    return isms.length ? [heading, keyValueParagraph(isms)] : heading;
+}
+function transformPlanning(ctx, node) {
+    const isms = [];
+    if (node.scheduled && orgismEnabled(ctx, "scheduled")) {
+        isms.push(`${keyName(ctx, "scheduled")}:: ${node.scheduled.rawValue}`);
+    }
+    if (node.deadline && orgismEnabled(ctx, "deadline")) {
+        isms.push(`${keyName(ctx, "deadline")}:: ${node.deadline.rawValue}`);
+    }
+    if (node.closed && orgismEnabled(ctx, "closed")) {
+        isms.push(`${keyName(ctx, "closed")}:: ${node.closed.rawValue}`);
+    }
+    return isms.length ? keyValueParagraph(isms) : null;
+}
+function transformDrawer(ctx, node) {
+    if (!orgismEnabled(ctx, "drawers")) {
+        return null;
+    }
+    // generic drawers (:LOGBOOK: …) have no md equivalent; keep their
+    // org text verbatim (unescaped) so the return trip re-parses the
+    // drawer natively
+    return keyValueParagraph([orgNodeToText(node)]);
+}
+function transformPropertyDrawer(ctx, node) {
+    if (!orgismEnabled(ctx, "properties")) {
+        return null;
+    }
+    const isms = (node.children || [])
+        .filter(child => child.type === "node-property")
+        .map(property => `${property.key}:: ${property.value}`);
+    return isms.length ? keyValueParagraph(isms) : null;
+}
+function transformParagraph(ctx, node) {
+    const math = paragraphAsDisplayMath(node);
+    if (math) {
+        return math;
+    }
+    const children = transformUniorgObjects(ctx, node.children);
+    // md gives leading whitespace structural meaning (list
+    // continuation, code); collapse per-line indentation inside
+    // paragraphs — insignificant in org and in rendered md alike
+    children.forEach((child, index) => {
+        if (child.type === "text") {
+            child.value = child.value.replace(/\n[ \t]+/g, "\n");
+            if (index === 0) {
+                child.value = child.value.replace(/^[ \t]+/, "");
+            }
+        }
+    });
+    trimParagraphEdges(children);
+    // a paragraph emptied by the cleanup (whitespace-only) would
+    // stringify as stray blank lines
+    return children.length ? { type: "paragraph", children } : null;
+}
+// a paragraph holding only a display fragment ($$…$$ or \[…\]) is
+// display math and becomes a math block
+function paragraphAsDisplayMath(node) {
+    const substantial = (node.children || []).filter(child => !(child.type === "text" && child.value.trim() === ""));
+    const only = substantial[0];
+    if (substantial.length === 1 &&
+        only?.type === "latex-fragment" &&
+        (only.value.startsWith("$$") || only.value.startsWith("\\["))) {
+        return {
+            type: "math",
+            value: only.contents.replace(/^\n/, "").replace(/\n$/, "")
+        };
+    }
+    return null;
+}
+// uniorg keeps surrounding blank lines inside the paragraph node;
+// strip them so remark-stringify produces canonical spacing.
+function trimParagraphEdges(children) {
+    const last = children[children.length - 1];
+    if (last?.type === "text") {
+        last.value = last.value.replace(/\n+$/, "");
+        if (last.value === "") {
+            children.pop();
+        }
+    }
+    const head = children[0];
+    if (head?.type === "text") {
+        head.value = head.value.replace(/^\n+/, "");
+        if (head.value === "") {
+            children.shift();
+        }
+    }
+}
+function transformExportBlock(node) {
+    if (node.backend !== "html") {
+        // other backends have no md meaning; verbatim like the org-only
+        // blocks so the return trip restores them
+        return keyValueParagraph([orgNodeToText(node)]);
+    }
+    return { type: "html", value: trimTrailingNewline(node.value) };
+}
+function transformQuoteBlock(ctx, node) {
+    return {
+        type: "blockquote",
+        children: transformNodes(ctx, node.children || [])
+    };
+}
+function transformSrcBlock(node) {
+    return {
+        type: "code",
+        lang: node.language || null,
+        value: trimTrailingNewline(node.value)
+    };
+}
+function transformExampleBlock(node) {
+    return {
+        type: "code",
+        lang: null,
+        value: trimTrailingNewline(node.value)
+    };
+}
+function transformComment(node) {
+    // html comments are markdown's comment idiom (hidden by every
+    // renderer) and restore to org comments on the return trip; an
+    // embedded `-->` would close the comment early, so escape it
+    const value = node.value.replaceAll("-->", "-->");
+    return {
+        type: "html",
+        value: value.includes("\n") ? `<!--\n${value}\n-->` : `<!-- ${value} -->`
+    };
+}

package/dist/core/uniorgToMdast/footnotes.d.ts

@@ -0,0 +1,10 @@
+import type { PhrasingContent, RootContent } from "mdast";
+import type { GreaterElementType, ObjectType } from "uniorg";
+import { type TransformContext } from "./shared.js";
+export declare function collectFootnoteLabels(ctx: TransformContext, node: unknown): void;
+export declare function transformFootnoteReference(ctx: TransformContext, node: Extract<ObjectType, {
+    type: "footnote-reference";
+}>): PhrasingContent;
+export declare function transformFootnoteDefinition(ctx: TransformContext, node: Extract<GreaterElementType, {
+    type: "footnote-definition";
+}>): RootContent;

package/dist/core/uniorgToMdast/footnotes.js

@@ -0,0 +1,54 @@
+import {} from "./shared.js";
+import { transformUniorgObjects } from "./objects.js";
+import { transformNodes } from "./elements.js";
+function nextFreeFootnoteLabel(ctx) {
+    let candidate = 1;
+    while (ctx.usedFootnoteLabels.has(String(candidate))) {
+        candidate++;
+    }
+    const label = String(candidate);
+    ctx.usedFootnoteLabels.add(label);
+    return label;
+}
+export function collectFootnoteLabels(ctx, node) {
+    if (!node || typeof node !== "object") {
+        return;
+    }
+    const candidate = node;
+    if ((candidate.type === "footnote-reference" ||
+        candidate.type === "footnote-definition") &&
+        candidate.label) {
+        ctx.usedFootnoteLabels.add(candidate.label);
+    }
+    for (const child of candidate.children || []) {
+        collectFootnoteLabels(ctx, child);
+    }
+}
+export function transformFootnoteReference(ctx, node) {
+    if (node.footnoteType === "inline") {
+        return transformInlineFootnoteReference(ctx, node);
+    }
+    return {
+        type: "footnoteReference",
+        identifier: node.label,
+        label: node.label
+    };
+}
+function transformInlineFootnoteReference(ctx, node) {
+    const label = node.label || nextFreeFootnoteLabel(ctx);
+    const content = transformUniorgObjects(ctx, node.children);
+    const firstChild = content[0];
+    if (firstChild?.type === "text") {
+        firstChild.value = firstChild.value.trimStart();
+    }
+    ctx.inlineFootnotes.push({ label, children: content });
+    return { type: "footnoteReference", identifier: label, label };
+}
+export function transformFootnoteDefinition(ctx, node) {
+    return {
+        type: "footnoteDefinition",
+        identifier: node.label,
+        label: node.label,
+        children: transformNodes(ctx, node.children || [])
+    };
+}

package/dist/core/uniorgToMdast/index.d.ts

@@ -0,0 +1,11 @@
+import type { Root as MdastRoot } from "mdast";
+import type { OrgData } from "uniorg";
+import type { UniorgToMdastOptions } from "./shared.js";
+export type { UniorgToMdastOptions } from "./shared.js";
+/**
+ * Transforms a uniorg AST to a mdast (Markdown AST).
+ * @param uniorgAst The uniorg AST to transform.
+ * @param options Controls org-ism serialization (`key:: value` lines).
+ * @returns The transformed mdast.
+ */
+export declare function transformUniorgAstToMdast(uniorgAst: OrgData, options?: UniorgToMdastOptions): MdastRoot;

package/dist/core/uniorgToMdast/index.js

@@ -0,0 +1,84 @@
+import { stringify as stringifyYaml } from "yaml";
+import { collectFootnoteLabels } from "./footnotes.js";
+import { transformNodes } from "./elements.js";
+/**
+ * Transforms a uniorg AST to a mdast (Markdown AST).
+ * @param uniorgAst The uniorg AST to transform.
+ * @param options Controls org-ism serialization (`key:: value` lines).
+ * @returns The transformed mdast.
+ */
+export function transformUniorgAstToMdast(uniorgAst, options = {}) {
+    const ctx = {
+        options,
+        inlineFootnotes: [],
+        usedFootnoteLabels: new Set()
+    };
+    collectFootnoteLabels(ctx, uniorgAst);
+    const nodes = uniorgAst.children || [];
+    // leading #+KEY: value keywords map to md frontmatter, a native
+    // construct; JSON-encoded values restore their structure (ADR 0002)
+    const collected = new Map();
+    let first = 0;
+    while (nodes[first]?.type === "keyword") {
+        const keyword = nodes[first];
+        const key = keyword.key.toLowerCase();
+        // a keyword may legally repeat; collect the values instead of
+        // letting the last one win
+        collected.set(key, [
+            ...(collected.get(key) ?? []),
+            parseKeywordValue(keyword.value)
+        ]);
+        first++;
+    }
+    const frontmatter = Object.fromEntries([...collected].map(([key, values]) => [
+        key,
+        values.length === 1 ? values[0] : values
+    ]));
+    const children = transformNodes(ctx, nodes.slice(first));
+    // adjacent single-item task lists (one per converted TODO section)
+    // merge into one list, or the output would not be a fixed point
+    if (options.taskCheckboxes) {
+        mergeAdjacentTaskLists(children);
+    }
+    if (first > 0) {
+        children.unshift({
+            type: "yaml",
+            value: stringifyYaml(frontmatter).trimEnd()
+        });
+    }
+    for (const footnote of ctx.inlineFootnotes) {
+        children.push({
+            type: "footnoteDefinition",
+            identifier: footnote.label,
+            label: footnote.label,
+            children: [{ type: "paragraph", children: footnote.children }]
+        });
+    }
+    return { type: "root", children: children };
+}
+function parseKeywordValue(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+function isTaskList(node) {
+    return (node?.type === "list" &&
+        !node.ordered &&
+        node.children.every(item => item.checked !== null));
+}
+function mergeAdjacentTaskLists(children) {
+    for (let i = 0; i < children.length - 1;) {
+        const current = children[i];
+        const next = children[i + 1];
+        if (isTaskList(current) && isTaskList(next)) {
+            current.children.push(...next.children);
+            children.splice(i + 1, 1);
+        }
+        else {
+            i++;
+        }
+    }
+}

package/dist/core/uniorgToMdast/lists.d.ts

@@ -0,0 +1,4 @@
+import type { RootContent } from "mdast";
+import type { List } from "uniorg";
+import { type TransformContext } from "./shared.js";
+export declare function transformPlainList(ctx: TransformContext, node: List): RootContent | RootContent[];