@remigius42/morg 0.4.0

package/dist/conversionOptions.d.ts

@@ -0,0 +1,32 @@
+import type { MorgConfig } from "./config.js";
+import type { MarkdownStyleOptions, MarkdownToOrgOptions, OrgToMarkdownOptions, Toggle } from "./options.js";
+import type { Preset } from "./presets/types.js";
+/** Explicitly requested option values; `undefined` leaves it to config. */
+export interface ConversionOverrides {
+    taskCheckboxes?: boolean;
+    interpretHtml?: boolean;
+    recordStyle?: boolean;
+    useHtml?: Toggle;
+    markdownStyle?: MarkdownStyleOptions;
+}
+/** Values that apply to both directions. */
+export interface SharedConversionOptions {
+    preset?: Preset;
+    onWarning?: (message: string) => void;
+    orgismKeys?: Record<string, string>;
+}
+/**
+ * Layers explicit overrides over the config file, per direction. Used by
+ * both adapters (CLI and Web UI) so the documented precedence — CLI or
+ * form > config > defaults — means the same thing in each.
+ * @param overrides Explicitly requested values; `undefined` defers to config.
+ * @param config The parsed `morg.toml`.
+ * @param shared Values that apply to both directions.
+ * @returns The options object for each direction.
+ */
+export declare function buildConversionOptions(overrides: ConversionOverrides, config: MorgConfig, shared: SharedConversionOptions): {
+    mdToOrgOptions: MarkdownToOrgOptions;
+    orgToMdOptions: OrgToMarkdownOptions & {
+        markdownStyle: MarkdownStyleOptions;
+    };
+};

package/dist/conversionOptions.js

@@ -0,0 +1,34 @@
+/**
+ * Layers explicit overrides over the config file, per direction. Used by
+ * both adapters (CLI and Web UI) so the documented precedence — CLI or
+ * form > config > defaults — means the same thing in each.
+ * @param overrides Explicitly requested values; `undefined` defers to config.
+ * @param config The parsed `morg.toml`.
+ * @param shared Values that apply to both directions.
+ * @returns The options object for each direction.
+ */
+export function buildConversionOptions(overrides, config, shared) {
+    const mdToOrgOptions = {
+        ...config.markdownToOrg,
+        ...shared,
+        ...(overrides.interpretHtml !== undefined && {
+            interpretHtml: overrides.interpretHtml
+        }),
+        ...(overrides.recordStyle !== undefined && {
+            recordStyle: overrides.recordStyle
+        })
+    };
+    const orgToMdOptions = {
+        ...config.orgToMarkdown,
+        ...shared,
+        ...(overrides.useHtml !== undefined && { useHtml: overrides.useHtml }),
+        ...(overrides.taskCheckboxes !== undefined && {
+            taskCheckboxes: overrides.taskCheckboxes
+        }),
+        markdownStyle: {
+            ...config.orgToMarkdown?.markdownStyle,
+            ...overrides.markdownStyle
+        }
+    };
+    return { mdToOrgOptions, orgToMdOptions };
+}

package/dist/core/markdownStyle.d.ts

@@ -0,0 +1,27 @@
+import type { Root } from "mdast";
+import type { OrgData } from "uniorg";
+import type { MarkdownStyleOptions } from "../options.js";
+/**
+ * The org keyword carrying a recorded Markdown style, per ADR 0004.
+ * `MORG_`-prefixed for the same reason `morg_` properties are (ADR 0002):
+ * ownership on the return trip must be unambiguous.
+ */
+export declare const STYLE_KEYWORD = "MORG_MARKDOWN_STYLE";
+/**
+ * Detects the Markdown style knobs a source document was written with,
+ * by reading the markers back out of the source at each node's position.
+ * Knobs used inconsistently are omitted rather than guessed at (see
+ * ADR 0004): style is recorded per document, so there is no honest
+ * answer for a document that mixes markers.
+ * @param mdast The parsed Markdown AST.
+ * @param markdown The Markdown source the AST was parsed from.
+ * @returns The detected knobs; keys without consistent evidence are absent.
+ */
+export declare function detectMarkdownStyle(mdast: Root, markdown: string, onWarning?: (message: string) => void): MarkdownStyleOptions;
+/**
+ * Removes a recorded-style keyword from an org AST and returns what it
+ * held, so it reaches the stringifier instead of the document body.
+ * @param uniorgAst The parsed org AST; mutated when the keyword is present.
+ * @returns The recorded knobs, or `undefined` when nothing was recorded.
+ */
+export declare function takeRecordedStyle(uniorgAst: OrgData): MarkdownStyleOptions | undefined;

package/dist/core/markdownStyle.js

@@ -0,0 +1,108 @@
+import { visit } from "unist-util-visit";
+/**
+ * The org keyword carrying a recorded Markdown style, per ADR 0004.
+ * `MORG_`-prefixed for the same reason `morg_` properties are (ADR 0002):
+ * ownership on the return trip must be unambiguous.
+ */
+export const STYLE_KEYWORD = "MORG_MARKDOWN_STYLE";
+/**
+ * Detects the Markdown style knobs a source document was written with,
+ * by reading the markers back out of the source at each node's position.
+ * Knobs used inconsistently are omitted rather than guessed at (see
+ * ADR 0004): style is recorded per document, so there is no honest
+ * answer for a document that mixes markers.
+ * @param mdast The parsed Markdown AST.
+ * @param markdown The Markdown source the AST was parsed from.
+ * @returns The detected knobs; keys without consistent evidence are absent.
+ */
+export function detectMarkdownStyle(mdast, markdown, onWarning) {
+    const seen = {
+        bullet: new Set(),
+        emphasis: new Set(),
+        strong: new Set(),
+        fence: new Set(),
+        rule: new Set()
+    };
+    // the rule is the one marker whose length also matters
+    const rules = new Set();
+    visit(mdast, (node, _index, parent) => {
+        const offset = node.position?.start.offset;
+        if (offset === undefined) {
+            return;
+        }
+        const marker = markdown[offset];
+        const knob = knobOf(node.type, marker, parent);
+        if (knob) {
+            seen[knob].add(marker);
+        }
+        if (node.type === "thematicBreak") {
+            rules.add(markdown.slice(offset, node.position?.end.offset).replace(/\s/g, ""));
+        }
+    });
+    const style = {};
+    for (const knob of KNOBS) {
+        record(style, knob, seen[knob], onWarning);
+    }
+    recordRuleRepetition(style, rules);
+    return style;
+}
+const KNOBS = ["bullet", "emphasis", "strong", "fence", "rule"];
+function knobOf(type, marker, parent) {
+    switch (type) {
+        case "emphasis":
+            return "emphasis";
+        case "strong":
+            return "strong";
+        case "thematicBreak":
+            return "rule";
+        case "code":
+            // an indented code block has no fence to read
+            return marker === "`" || marker === "~" ? "fence" : undefined;
+        case "listItem":
+            // an ordered item starts with its number, not with a bullet
+            return parent?.type === "list" && !parent.ordered ? "bullet" : undefined;
+        default:
+            return undefined;
+    }
+}
+// "---" is remark's own default repetition, so only a longer run is
+// worth recording; a document mixing lengths records none
+function recordRuleRepetition(style, rules) {
+    const lengths = new Set([...rules].map(rule => rule.length));
+    const [length] = [...lengths];
+    if (style.rule && lengths.size === 1 && length !== undefined && length > 3) {
+        style.ruleRepetition = length;
+    }
+}
+// a marker with no instances in the document has nothing to record and
+// nothing to warn about; one used two ways has no honest single answer
+function record(style, knob, markers, onWarning) {
+    if (markers.size === 1) {
+        Object.assign(style, { [knob]: [...markers][0] });
+        return;
+    }
+    if (markers.size > 1) {
+        onWarning?.(`${knob} marker is not used consistently; not recorded`);
+    }
+}
+/**
+ * Removes a recorded-style keyword from an org AST and returns what it
+ * held, so it reaches the stringifier instead of the document body.
+ * @param uniorgAst The parsed org AST; mutated when the keyword is present.
+ * @returns The recorded knobs, or `undefined` when nothing was recorded.
+ */
+export function takeRecordedStyle(uniorgAst) {
+    const index = uniorgAst.children.findIndex(child => child.type === "keyword" &&
+        child.key === STYLE_KEYWORD);
+    if (index === -1) {
+        return undefined;
+    }
+    const [keyword] = uniorgAst.children.splice(index, 1);
+    const value = keyword.value;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/core/mdastToUniorg/blocks.d.ts

@@ -0,0 +1,20 @@
+import type { RootContent, PhrasingContent } from "mdast";
+import type { ElementType } from "uniorg";
+import { type TransformContext } from "./context.js";
+export declare function frontmatterToKeywords(yamlValue: string): ElementType[];
+export declare function transformMdastTable(ctx: TransformContext, node: Extract<RootContent, {
+    type: "table";
+}>): ElementType;
+export declare function transformMdastHtml(ctx: TransformContext, node: Extract<RootContent, {
+    type: "html";
+}>): ElementType | null;
+export declare function transformMdastCode(node: Extract<RootContent, {
+    type: "code";
+}>): ElementType;
+export declare function transformMdastMath(node: RootContent | PhrasingContent): ElementType;
+export declare function transformMdastHeading(ctx: TransformContext, node: Extract<RootContent, {
+    type: "heading";
+}>): ElementType;
+export declare function keywordOnlyLines(node: {
+    children: PhrasingContent[];
+}): string[] | null;

package/dist/core/mdastToUniorg/blocks.js

@@ -0,0 +1,211 @@
+import { toString } from "orgast-util-to-string";
+import { parse as parseYaml } from "yaml";
+import { mdismEnabled } from "./context.js";
+import { transformPhrasingChildren } from "./phrasing.js";
+// a keyword is a single line, so anything that is not a single-line
+// scalar is JSON-encoded and restored by JSON.parse on the way back
+function keywordValue(value) {
+    if (value !== null && typeof value === "object") {
+        return JSON.stringify(value);
+    }
+    const text = String(value);
+    return text.includes("\n") ? JSON.stringify(text) : text;
+}
+// frontmatter entries become #+KEY: value keywords; scalar values as-is,
+// structured values JSON-encoded on a single line (see ADR 0002)
+export function frontmatterToKeywords(yamlValue) {
+    const data = parseYaml(yamlValue);
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+        return [];
+    }
+    return Object.entries(data).flatMap(([key, value]) => {
+        // a sequence becomes repeated keywords -- org's own way of carrying
+        // several values for one key, and what they read back as
+        const values = Array.isArray(value) && value.length ? value : [value];
+        return values.map(item => ({
+            type: "keyword",
+            affiliated: {},
+            key: key.toUpperCase(),
+            value: keywordValue(item)
+        }));
+    });
+}
+export function transformMdastTable(ctx, node) {
+    const [headerRow, ...bodyRows] = node.children;
+    // GFM column alignment maps to an org alignment cookie row
+    // (| <l> | <r> | <c> |) directly below the header rule
+    const cookieRow = (node.align || []).some(Boolean)
+        ? [
+            {
+                type: "table-row",
+                rowType: "standard",
+                children: (node.align || []).map(align => ({
+                    type: "table-cell",
+                    children: align
+                        ? [{ type: "text", value: `<${align.charAt(0)}>` }]
+                        : []
+                }))
+            }
+        ]
+        : [];
+    const rows = [
+        ...(headerRow ? [transformMdastTableRow(ctx, headerRow)] : []),
+        { type: "table-row", rowType: "rule", children: [] },
+        ...cookieRow,
+        ...bodyRows.map(row => transformMdastTableRow(ctx, row))
+    ];
+    return {
+        type: "table",
+        tableType: "org",
+        tblfm: null,
+        children: rows
+    };
+}
+function transformMdastTableRow(ctx, row) {
+    return {
+        type: "table-row",
+        rowType: "standard",
+        children: row.children.map(cell => ({
+            type: "table-cell",
+            children: transformPhrasingChildren(ctx, cell.children)
+        }))
+    };
+}
+export function transformMdastHtml(ctx, node) {
+    // html comments are markdown's comment idiom and map natively to
+    // org comments (not an md-ism)
+    const comment = /^<!--([\s\S]*?)-->\s*$/.exec(node.value);
+    if (comment) {
+        return {
+            type: "comment",
+            // inverse of the escaping applied when the comment was emitted
+            value: (comment[1] ?? "").trim().replaceAll("--&gt;", "-->")
+        };
+    }
+    if (ctx.options.interpretHtml) {
+        const descriptiveList = interpretDefinitionList(node.value);
+        if (descriptiveList) {
+            return descriptiveList;
+        }
+    }
+    // block raw html is a md-ism: preserved as an org export block
+    return mdismEnabled(ctx, "html")
+        ? {
+            type: "export-block",
+            backend: "html",
+            value: node.value
+        }
+        : null;
+}
+// a bare <dl> whose body is nothing but attribute-less <dt>/<dd> pairs
+// (any whitespace between tags) becomes a ` :: ` list — the same
+// markdown convention descriptive lists use without useHtml, so the
+// org side re-parses it as a native descriptive list; anything richer
+// stays a preserved md-ism
+// inverse of the escaping the useHtml side applies to <dt>/<dd> text
+function unescapeHtmlText(text) {
+    return text
+        .trim()
+        .replaceAll("&lt;", "<")
+        .replaceAll("&gt;", ">")
+        .replaceAll("&amp;", "&");
+}
+function interpretDefinitionList(html) {
+    const body = /^<dl\s*>([\s\S]*)<\/dl\s*>\s*$/i.exec(html.trim())?.[1];
+    if (!body) {
+        return null;
+    }
+    const entries = [];
+    const leftover = body.replace(/<dt\s*>([^<]*)<\/dt\s*>\s*<dd\s*>([^<]*)<\/dd\s*>/gi, (_match, term, definition) => {
+        entries.push([unescapeHtmlText(term), unescapeHtmlText(definition)]);
+        return "";
+    });
+    if (!entries.length || leftover.trim() !== "") {
+        return null;
+    }
+    return {
+        type: "plain-list",
+        listType: "unordered",
+        indent: 0,
+        affiliated: {},
+        children: entries.map(([term, definition]) => ({
+            type: "list-item",
+            indent: 0,
+            bullet: "- ",
+            counter: null,
+            checkbox: null,
+            children: [{ type: "text", value: `${term} :: ${definition}\n` }],
+            contentsBegin: 0,
+            contentsEnd: 0
+        })),
+        contentsBegin: 0,
+        contentsEnd: 0
+    };
+}
+export function transformMdastCode(node) {
+    // a table.el-tagged fence restores the verbatim table.el table it
+    // was serialized from
+    if (node.lang === "table.el") {
+        return {
+            type: "table",
+            tableType: "table.el",
+            tblfm: "",
+            value: `${node.value}\n`
+        };
+    }
+    return (node.lang
+        ? { type: "src-block", language: node.lang, value: node.value }
+        : {
+            type: "example-block",
+            value: node.value
+        });
+}
+// \begin… blocks restore to latex environments; plain display math
+// becomes a $$…$$ fragment (org's display form)
+export function transformMdastMath(node) {
+    const value = node.value;
+    if (value.startsWith("\\begin{")) {
+        return {
+            type: "latex-environment",
+            affiliated: {},
+            value
+        };
+    }
+    return {
+        type: "paragraph",
+        children: [
+            {
+                type: "latex-fragment",
+                value: `$$\n${value}\n$$`,
+                contents: `\n${value}\n`
+            }
+        ],
+        contentsBegin: 0,
+        contentsEnd: 0
+    };
+}
+export function transformMdastHeading(ctx, node) {
+    return {
+        type: "headline",
+        level: node.depth,
+        todoKeyword: null,
+        priority: null,
+        commented: false,
+        rawValue: toString(node),
+        tags: [],
+        children: transformPhrasingChildren(ctx, node.children)
+    };
+}
+const KEYWORD_LINE_RE = /^#\+\S+: /;
+export function keywordOnlyLines(node) {
+    if (!node.children.every(child => child.type === "text")) {
+        return null;
+    }
+    const lines = node.children
+        .map(child => child.value)
+        .join("")
+        .split("\n");
+    return lines.length && lines.every(line => KEYWORD_LINE_RE.test(line))
+        ? lines
+        : null;
+}

package/dist/core/mdastToUniorg/context.d.ts

@@ -0,0 +1,15 @@
+import { type Toggle } from "../../options.js";
+export interface MdastToUniorgOptions {
+    preserveMdisms?: Toggle;
+    interpretHtml?: boolean;
+    onWarning?: (message: string) => void;
+}
+export interface TransformContext {
+    options: MdastToUniorgOptions;
+    definitions: Map<string, {
+        url: string;
+        title?: string;
+    }>;
+}
+export declare function mdismEnabled(ctx: TransformContext, key: string): boolean;
+export declare function warn(ctx: TransformContext, message: string): void;

package/dist/core/mdastToUniorg/context.js

@@ -0,0 +1,7 @@
+import { toggleEnabled } from "../../options.js";
+export function mdismEnabled(ctx, key) {
+    return toggleEnabled(ctx.options.preserveMdisms, key);
+}
+export function warn(ctx, message) {
+    ctx.options.onWarning?.(message);
+}

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

@@ -0,0 +1,13 @@
+import type { Root as MdastRoot, RootContent, PhrasingContent } from "mdast";
+import type { OrgData, Text, ElementType, GreaterElementType } from "uniorg";
+import { type TransformContext } from "./context.js";
+export type { MdastToUniorgOptions, TransformContext } from "./context.js";
+import type { MdastToUniorgOptions } from "./context.js";
+/**
+ * Transforms a mdast (Markdown AST) to a uniorg AST.
+ * @param mdast The mdast tree to transform.
+ * @param options Controls md-ism preservation (e.g. raw HTML).
+ * @returns The transformed uniorg AST.
+ */
+export declare function transformMdastToUniorgAst(mdast: MdastRoot, options?: MdastToUniorgOptions): OrgData;
+export declare function transformMdastNodeToUniorgNode(ctx: TransformContext, node: RootContent | PhrasingContent): GreaterElementType | ElementType | Text | null;

package/dist/core/mdastToUniorg/index.js

@@ -0,0 +1,95 @@
+import { visit } from "unist-util-visit";
+import { warn } from "./context.js";
+import { frontmatterToKeywords, keywordOnlyLines, transformMdastCode, transformMdastHeading, transformMdastHtml, transformMdastMath, transformMdastTable } from "./blocks.js";
+import { transformMdastList } from "./lists.js";
+import { transformPhrasingChildren } from "./phrasing.js";
+/**
+ * Transforms a mdast (Markdown AST) to a uniorg AST.
+ * @param mdast The mdast tree to transform.
+ * @param options Controls md-ism preservation (e.g. raw HTML).
+ * @returns The transformed uniorg AST.
+ */
+export function transformMdastToUniorgAst(mdast, options = {}) {
+    const ctx = { options, definitions: new Map() };
+    visit(mdast, "definition", (definition) => {
+        ctx.definitions.set(definition.identifier, {
+            url: definition.url,
+            ...(definition.title != null && { title: definition.title })
+        });
+    });
+    const children = mdast.children
+        .flatMap(child => 
+    // frontmatter maps to org keywords, a native construct (one mdast
+    // node fans out to one keyword per entry)
+    child.type === "yaml"
+        ? frontmatterToKeywords(child.value)
+        : [transformMdastNodeToUniorgNode(ctx, child)])
+        .filter(Boolean);
+    const orgAst = {
+        type: "org-data",
+        children: children,
+        contentsBegin: 0, // Placeholder
+        contentsEnd: 0 // Placeholder
+    };
+    return orgAst;
+}
+function transformBlockChildren(ctx, children) {
+    return children
+        .map(child => transformMdastNodeToUniorgNode(ctx, child))
+        .filter(Boolean);
+}
+export function transformMdastNodeToUniorgNode(ctx, node) {
+    switch (node.type) {
+        case "heading":
+            return transformMdastHeading(ctx, node);
+        case "paragraph": {
+            // a paragraph of only #+KEY: lines is affiliated keywords (or
+            // mid-file keywords) traveling verbatim; emit as raw text so they
+            // glue to the following element without a blank line — org only
+            // attaches affiliated keywords when directly above their element
+            const keywordLines = keywordOnlyLines(node);
+            if (keywordLines) {
+                return { type: "text", value: `${keywordLines.join("\n")}\n` };
+            }
+            return {
+                type: "paragraph",
+                children: transformPhrasingChildren(ctx, node.children),
+                contentsBegin: 0, // Placeholder
+                contentsEnd: 0 // Placeholder
+            };
+        }
+        case "text":
+            return { type: "text", value: node.value };
+        case "list":
+            return transformMdastList(ctx, node, 0);
+        case "table":
+            return transformMdastTable(ctx, node);
+        case "html":
+            return transformMdastHtml(ctx, node);
+        case "thematicBreak":
+            return { type: "horizontal-rule" };
+        case "footnoteDefinition":
+            return {
+                type: "footnote-definition",
+                label: node.identifier,
+                affiliated: {},
+                children: transformBlockChildren(ctx, node.children)
+            };
+        case "blockquote":
+            return {
+                type: "quote-block",
+                children: transformBlockChildren(ctx, node.children)
+            };
+        case "code":
+            return transformMdastCode(node);
+        case "math":
+            return transformMdastMath(node);
+        case "definition":
+            // consumed by reference-style link resolution
+            return null;
+        // remaining block types have no mapping; dropped with a warning
+        default:
+            warn(ctx, `dropped md ${node.type}`);
+            return null;
+    }
+}

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

@@ -0,0 +1,4 @@
+import type { List as MdastList } from "mdast";
+import type { List } from "uniorg";
+import type { TransformContext } from "./context.js";
+export declare function transformMdastList(ctx: TransformContext, listNode: MdastList, indent: number): List;

package/dist/core/mdastToUniorg/lists.js

@@ -0,0 +1,45 @@
+import { transformPhrasingChildren } from "./phrasing.js";
+// circular import with index.js is fine in ESM: both sides only export
+// hoisted function declarations called after module initialization
+import { transformMdastNodeToUniorgNode } from "./index.js";
+// Mirrors the AST shape uniorg-parse produces for lists: ordered numbering
+// lives in each item's bullet, and nested lists sit inside the parent
+// item's children with indent = parent indent + bullet length.
+export function transformMdastList(ctx, listNode, indent) {
+    const start = listNode.start ?? 1;
+    return {
+        type: "plain-list",
+        listType: listNode.ordered ? "ordered" : "unordered",
+        indent,
+        affiliated: {},
+        children: listNode.children.map((item, i) => transformMdastListItem(ctx, item, indent, listNode.ordered ? `${start + i}. ` : "- ")),
+        contentsBegin: 0,
+        contentsEnd: 0
+    };
+}
+function transformMdastListItem(ctx, item, indent, bullet) {
+    const children = item.children
+        .flatMap((child) => {
+        if (child.type === "list") {
+            return [transformMdastList(ctx, child, indent + bullet.length)];
+        }
+        if (child.type === "paragraph") {
+            return [
+                ...transformPhrasingChildren(ctx, child.children),
+                { type: "text", value: "\n" }
+            ];
+        }
+        return [transformMdastNodeToUniorgNode(ctx, child)];
+    })
+        .filter(Boolean);
+    return {
+        type: "list-item",
+        indent,
+        bullet,
+        counter: null,
+        checkbox: item.checked === true ? "on" : item.checked === false ? "off" : null,
+        children,
+        contentsBegin: 0,
+        contentsEnd: 0
+    };
+}

package/dist/core/mdastToUniorg/phrasing.d.ts

@@ -0,0 +1,4 @@
+import type { PhrasingContent } from "mdast";
+import type { ObjectType } from "uniorg";
+import { type TransformContext } from "./context.js";
+export declare function transformPhrasingChildren(ctx: TransformContext, children: PhrasingContent[]): ObjectType[];