@remigius42/morg 0.4.0

package/dist/markdownToOrg.js

@@ -0,0 +1,194 @@
+import { unified } from "unified";
+import remarkParse from "remark-parse";
+import remarkGfm from "remark-gfm";
+import remarkFrontmatter from "remark-frontmatter";
+import remarkMath from "remark-math";
+import { uniorgStringify } from "uniorg-stringify";
+import { visit } from "unist-util-visit";
+import { transformMdastToUniorgAst } from "./core/mdastToUniorg/index.js";
+import { detectMarkdownStyle, STYLE_KEYWORD } from "./core/markdownStyle.js";
+/**
+ * Converts a Markdown string to an Org-mode string.
+ * @param markdown The Markdown string to convert.
+ * @param options Conversion options (md-ism preservation, dialect preset).
+ * @returns The converted Org-mode string.
+ */
+export function convertMarkdownToOrg(markdown, options = {}) {
+    // Phase 1: Parse Markdown to mdast
+    const mdast = unified()
+        .use(remarkParse)
+        .use(remarkGfm)
+        .use(remarkFrontmatter)
+        .use(remarkMath)
+        .parse(markdown);
+    // Phase 2: Generic mdast to uniorg-ast transformation
+    let uniorgAst = transformMdastToUniorgAst(mdast, {
+        ...(options.preserveMdisms !== undefined && {
+            preserveMdisms: options.preserveMdisms
+        }),
+        ...(options.interpretHtml !== undefined && {
+            interpretHtml: options.interpretHtml
+        }),
+        ...(options.onWarning !== undefined && { onWarning: options.onWarning })
+    });
+    // Phase 2b: restore key:: value lines below headings to native org
+    // syntax (see ADR 0002): known keys become TODO keywords, priorities,
+    // tags and planning; unknown keys become property drawer entries.
+    // orgismKeys maps custom names back to canonical (per-config).
+    const canonicalKeys = new Map(Object.entries(options.orgismKeys ?? {}).map(([canonical, custom]) => [
+        custom,
+        canonical
+    ]));
+    restoreOrgisms(uniorgAst, canonicalKeys);
+    // Phase 2c: formatting-as-structure — adjacent lists need two blank
+    // lines between them, or org's parser merges them into one list.
+    separateAdjacentLists(uniorgAst);
+    // Phase 2d: record the source's own style markers, so the return trip
+    // can reproduce them instead of morg's canonical ones (ADR 0004)
+    if (options.recordStyle) {
+        recordStyleKeyword(uniorgAst, detectMarkdownStyle(mdast, markdown, options.onWarning));
+    }
+    // Phase 3: Apply dialect preset, if any
+    if (options.preset?.applyToUniorg) {
+        uniorgAst = options.preset.applyToUniorg(uniorgAst);
+    }
+    // Phase 4: Render uniorg-ast to Org-mode string
+    const processor = unified().use(uniorgStringify);
+    const orgContent = processor.stringify(uniorgAst);
+    return orgContent;
+}
+// leads the document so it survives the frontmatter keywords following it
+function recordStyleKeyword(uniorgAst, style) {
+    if (!Object.keys(style).length) {
+        return;
+    }
+    uniorgAst.children.unshift({
+        type: "keyword",
+        key: STYLE_KEYWORD,
+        value: JSON.stringify(style)
+    });
+}
+const KEY_VALUE_LINE_RE = /^([\w-]+):: (.*)$/;
+function parseKeyValueParagraph(node) {
+    if (node?.type !== "paragraph" || !node.children?.length) {
+        return null;
+    }
+    if (!node.children.every(child => child.type === "text")) {
+        return null;
+    }
+    const lines = node.children
+        .map(child => child.value ?? "")
+        .join("")
+        .split("\n");
+    const entries = [];
+    for (const line of lines) {
+        const match = KEY_VALUE_LINE_RE.exec(line);
+        if (!match) {
+            return null;
+        }
+        entries.push([match[1], match[2]]);
+    }
+    return entries;
+}
+function makeTimestamp(rawValue) {
+    return { type: "timestamp", rawValue };
+}
+// the headline slots have a syntax of their own: a value org could not
+// carry there (a drawer property that merely shares the name, a
+// hand-written line) stays a property instead of corrupting the title
+const TODO_KEYWORD_RE = /^[A-Z][A-Z0-9_-]*$/;
+const PRIORITY_RE = /^[A-Z]$/;
+const TAG_LIST_RE = /^[\w@#%]+(?:,\s*[\w@#%]+)*$/;
+const TIMESTAMP_RE = /^[<[].*[>\]]$/;
+function applyOrgismEntry(headline, planning, properties, key, value) {
+    switch (key) {
+        case "todo":
+            if (!TODO_KEYWORD_RE.test(value)) {
+                break;
+            }
+            headline.todoKeyword = value;
+            return;
+        case "priority":
+            if (!PRIORITY_RE.test(value)) {
+                break;
+            }
+            headline.priority = value;
+            return;
+        case "tags":
+            if (!TAG_LIST_RE.test(value)) {
+                break;
+            }
+            headline.tags = value.split(/,\s*/);
+            return;
+        case "scheduled":
+        case "deadline":
+        case "closed":
+            if (!TIMESTAMP_RE.test(value)) {
+                break;
+            }
+            planning[key] = makeTimestamp(value);
+            return;
+        default:
+            break;
+    }
+    properties.push({ type: "node-property", key, value });
+}
+function consumeOrgismParagraphs(children, i, canonicalKeys) {
+    const headline = children[i];
+    const planning = {};
+    const properties = [];
+    let consumed = 0;
+    let entries;
+    while ((entries = parseKeyValueParagraph(children[i + 1 + consumed]))) {
+        for (const [rawKey, value] of entries) {
+            const key = canonicalKeys.get(rawKey) ?? rawKey;
+            applyOrgismEntry(headline, planning, properties, key, value);
+        }
+        consumed++;
+    }
+    return { planning, properties, consumed };
+}
+function buildOrgismReplacements(planning, properties) {
+    const replacements = [];
+    if (Object.keys(planning).length) {
+        replacements.push({
+            type: "planning",
+            scheduled: planning.scheduled ?? null,
+            deadline: planning.deadline ?? null,
+            closed: planning.closed ?? null
+        });
+    }
+    if (properties.length) {
+        replacements.push({
+            type: "property-drawer",
+            children: properties,
+            contentsBegin: 0,
+            contentsEnd: 0
+        });
+    }
+    return replacements;
+}
+function restoreOrgisms(uniorgAst, canonicalKeys) {
+    const children = uniorgAst.children;
+    for (let i = 0; i < children.length; i++) {
+        if (children[i]?.type !== "headline") {
+            continue;
+        }
+        const { planning, properties, consumed } = consumeOrgismParagraphs(children, i, canonicalKeys);
+        if (!consumed) {
+            continue;
+        }
+        const replacements = buildOrgismReplacements(planning, properties);
+        children.splice(i + 1, consumed, ...replacements);
+    }
+}
+function separateAdjacentLists(uniorgAst) {
+    visit(uniorgAst, "plain-list", (_node, index, parent) => {
+        if (parent.children[index + 1]?.type === "plain-list") {
+            const separator = { type: "text", value: "\n\n" };
+            parent.children.splice(index + 1, 0, separator);
+            return index + 2;
+        }
+        return undefined;
+    });
+}

package/dist/normalize.d.ts

@@ -0,0 +1,26 @@
+import type { MarkdownToOrgOptions, OrgToMarkdownOptions } from "./options.js";
+/**
+ * The full option set of both directions: normalization uses the same
+ * configuration as conversion — Convergence is per-config (see ADR
+ * 0002), so a file must be normalized with the exact config (preset,
+ * style, key names, toggles) it will be converted with.
+ */
+export type NormalizeOptions = MarkdownToOrgOptions & OrgToMarkdownOptions;
+/**
+ * Normalizes a Markdown string to morg's canonical form: one full round
+ * trip (`md → org → md`), whose output is a fixed point (see ADR 0001).
+ * This canonicalizes, it does not just re-style — org-isms and md-isms
+ * are rewritten the same way a conversion would rewrite them.
+ * @param markdown The Markdown string to normalize.
+ * @param options Warning callback and dialect preset.
+ * @returns The canonical-form Markdown string.
+ */
+export declare function normalizeMarkdown(markdown: string, options?: NormalizeOptions): string;
+/**
+ * Normalizes an Org string to morg's canonical form: one full round trip
+ * (`org → md → org`), whose output is a fixed point (see ADR 0001).
+ * @param org The Org string to normalize.
+ * @param options Warning callback and dialect preset.
+ * @returns The canonical-form Org string.
+ */
+export declare function normalizeOrg(org: string, options?: NormalizeOptions): string;

package/dist/normalize.js

@@ -0,0 +1,24 @@
+import { convertMarkdownToOrg } from "./markdownToOrg.js";
+import { convertOrgToMarkdown } from "./orgToMarkdown.js";
+/**
+ * Normalizes a Markdown string to morg's canonical form: one full round
+ * trip (`md → org → md`), whose output is a fixed point (see ADR 0001).
+ * This canonicalizes, it does not just re-style — org-isms and md-isms
+ * are rewritten the same way a conversion would rewrite them.
+ * @param markdown The Markdown string to normalize.
+ * @param options Warning callback and dialect preset.
+ * @returns The canonical-form Markdown string.
+ */
+export function normalizeMarkdown(markdown, options = {}) {
+    return convertOrgToMarkdown(convertMarkdownToOrg(markdown, options), options);
+}
+/**
+ * Normalizes an Org string to morg's canonical form: one full round trip
+ * (`org → md → org`), whose output is a fixed point (see ADR 0001).
+ * @param org The Org string to normalize.
+ * @param options Warning callback and dialect preset.
+ * @returns The canonical-form Org string.
+ */
+export function normalizeOrg(org, options = {}) {
+    return convertMarkdownToOrg(convertOrgToMarkdown(org, options), options);
+}

package/dist/options.d.ts

@@ -0,0 +1,102 @@
+import type { Preset } from "./presets/types.js";
+/**
+ * A feature toggle: `true`/`false` switches everything on/off, a record
+ * toggles individual constructs by name. Unlisted keys fall back to the
+ * flag's default. Mirrors the shape of the (planned) TOML config entries.
+ */
+export type Toggle = boolean | Record<string, boolean>;
+export declare function toggleEnabled(toggle: Toggle | undefined, key: string, defaultValue?: boolean): boolean;
+export interface MarkdownToOrgOptions {
+    /**
+     * Preserve Markdown constructs without a native Org equivalent (e.g.
+     * raw HTML as export blocks/snippets, see ADR 0002). Default: `true`.
+     */
+    preserveMdisms?: Toggle;
+    /**
+     * Interpret the HTML vocabulary morg itself emits under `useHtml`
+     * (bare `<u>`, `<sup>`, `<sub>`, `<dl>/<dt>/<dd>` without attributes)
+     * as native Org constructs instead of preserving it as an md-ism.
+     * The inverse of `useHtml`; with both enabled the round trip is
+     * lossless. Any other HTML still preserves per `preserveMdisms`.
+     * Default: `false`.
+     */
+    interpretHtml?: boolean;
+    /**
+     * Record the Markdown style knobs detected in the source as a
+     * `#+MORG_MARKDOWN_STYLE:` keyword, so the return trip restores the source's own
+     * markers instead of morg's canonical ones (ADR 0004). Widens the set
+     * of inputs the Round Trip leaves untouched; it does not replace
+     * Convergence. Knobs used inconsistently are not recorded and warn.
+     * Default: `false`.
+     */
+    recordStyle?: boolean;
+    /**
+     * Custom names for org-ism `key::` lines, canonical → custom (e.g.
+     * `{ todo: "state" }`). Must match the mapping the file was written
+     * with — Convergence is per-config (ADR 0002).
+     */
+    orgismKeys?: Record<string, string>;
+    /** Called for each construct dropped without an equivalent. */
+    onWarning?: (message: string) => void;
+    /** Dialect preset applied on top of the generic conversion. */
+    preset?: Preset;
+}
+/**
+ * Markdown stringifier style knobs (subset of remark-stringify options).
+ * Canonical form is parameterized by these (see ADR 0001): round trips
+ * must use the same style, and files formatted under one style are not
+ * a fixed point under another. Defaults: `-` bullet, `*` emphasis /
+ * `*` strong (i.e. `**bold**`), backtick fences, `-` rule — prettier's
+ * choices except emphasis (`emphasis: "_"` aligns with prettier).
+ */
+export interface MarkdownStyleOptions {
+    /** Unordered list marker. Default: `"-"`. */
+    bullet?: "-" | "*" | "+";
+    /** Emphasis (italic) marker. Default: `"*"`. */
+    emphasis?: "*" | "_";
+    /** Strong (bold) marker, doubled in output. Default: `"*"`. */
+    strong?: "*" | "_";
+    /** Code fence marker. Default: `` "`" ``. */
+    fence?: "`" | "~";
+    /** Thematic break marker, tripled in output. Default: `"-"`. */
+    rule?: "-" | "*" | "_";
+    /**
+     * How often to repeat the thematic break marker (minimum 3).
+     * Default: `3`. mdformat writes 70 underscores (`rule: "_"`,
+     * `ruleRepetition: 70`).
+     */
+    ruleRepetition?: number;
+}
+export interface OrgToMarkdownOptions {
+    /**
+     * Serialize Org constructs without a native Markdown equivalent as
+     * `key:: value` lines and verbatim passthroughs (see ADR 0002).
+     * Default: `true`.
+     */
+    preserveOrgisms?: Toggle;
+    /**
+     * Render Org constructs without a Markdown equivalent as raw HTML
+     * (`<u>`, `<sup>`, `<sub>`, `<dl>`) instead of keeping their org markup
+     * verbatim. HTML round-trips as a preserved md-ism (export blocks and
+     * snippets), not back to native org markup — a one-way door unless
+     * the return trip enables its inverse, `interpretHtml`.
+     * Default: `false`.
+     */
+    useHtml?: Toggle;
+    /**
+     * Map bare `TODO`/`DONE` leaf headlines (no priority, tags or content)
+     * to GFM task items (`- [ ]` / `- [x]`). Documented lossy export mode:
+     * headings become list items and do not restore to TODO headlines on
+     * the return trip; unmappable states keep the heading and warn.
+     * Default: `false`.
+     */
+    taskCheckboxes?: boolean;
+    /** Markdown output style; canonical form is per-config (ADR 0001). */
+    markdownStyle?: MarkdownStyleOptions;
+    /** Custom names for org-ism `key::` lines, canonical → custom. */
+    orgismKeys?: Record<string, string>;
+    /** Called for each construct dropped without an equivalent. */
+    onWarning?: (message: string) => void;
+    /** Dialect preset extracted before the generic conversion. */
+    preset?: Preset;
+}

package/dist/options.js

@@ -0,0 +1,9 @@
+export function toggleEnabled(toggle, key, defaultValue = true) {
+    if (toggle === undefined) {
+        return defaultValue;
+    }
+    if (typeof toggle === "boolean") {
+        return toggle;
+    }
+    return toggle[key] ?? defaultValue;
+}

package/dist/orgToMarkdown.d.ts

@@ -0,0 +1,8 @@
+import type { OrgToMarkdownOptions } from "./options.js";
+/**
+ * Converts an Org-mode string to a Markdown string.
+ * @param org The Org-mode string to convert.
+ * @param options Conversion options (org-ism serialization, dialect preset).
+ * @returns The converted Markdown string.
+ */
+export declare function convertOrgToMarkdown(org: string, options?: OrgToMarkdownOptions): string;

package/dist/orgToMarkdown.js

@@ -0,0 +1,61 @@
+import { unified } from "unified";
+import uniorgParse from "uniorg-parse";
+import remarkStringify from "remark-stringify";
+import remarkGfm from "remark-gfm";
+import remarkFrontmatter from "remark-frontmatter";
+import remarkMath from "remark-math";
+import { transformUniorgAstToMdast } from "./core/uniorgToMdast/index.js";
+import { takeRecordedStyle } from "./core/markdownStyle.js";
+/**
+ * Converts an Org-mode string to a Markdown string.
+ * @param org The Org-mode string to convert.
+ * @param options Conversion options (org-ism serialization, dialect preset).
+ * @returns The converted Markdown string.
+ */
+export function convertOrgToMarkdown(org, options = {}) {
+    // Phase 1: Parse Org-mode to uniorg-ast
+    let uniorgAst = unified().use(uniorgParse).parse(org);
+    // Phase 1b: a recorded style is morg's own (ADR 0004) — consume it so
+    // it does not travel on as frontmatter; explicit options still win
+    const recordedStyle = takeRecordedStyle(uniorgAst);
+    // Phase 2: Extract dialect preset conventions, if any
+    if (options.preset?.extractFromUniorg) {
+        uniorgAst = options.preset.extractFromUniorg(uniorgAst);
+    }
+    // Phase 3: Generic uniorg-ast to mdast transformation
+    const mdast = transformUniorgAstToMdast(uniorgAst, {
+        ...(options.preserveOrgisms !== undefined && {
+            preserveOrgisms: options.preserveOrgisms
+        }),
+        ...(options.useHtml !== undefined && { useHtml: options.useHtml }),
+        ...(options.taskCheckboxes !== undefined && {
+            taskCheckboxes: options.taskCheckboxes
+        }),
+        ...(options.orgismKeys !== undefined && {
+            orgismKeys: options.orgismKeys
+        }),
+        ...(options.onWarning !== undefined && { onWarning: options.onWarning })
+    });
+    // Phase 4: Render mdast to Markdown string
+    // bullet and rule "-" (not remark's default "*") are morg's canonical
+    // Markdown form; markdownStyle knobs override it (canonical form is
+    // then per-config, see ADR 0001)
+    const markdownContent = unified()
+        .use(remarkStringify, {
+        bullet: "-",
+        rule: "-",
+        ...recordedStyle,
+        ...options.markdownStyle,
+        handlers: {
+            // key:: value blocks and preset inline passthroughs (e.g.
+            // wikilinks) are emitted verbatim, unescaped
+            keyValue: (node) => node.value,
+            verbatimInline: (node) => node.value
+        }
+    })
+        .use(remarkGfm)
+        .use(remarkFrontmatter)
+        .use(remarkMath)
+        .stringify(mdast);
+    return markdownContent;
+}

package/dist/presets/logseq.d.ts

@@ -0,0 +1,25 @@
+import type { OrgData } from "uniorg";
+import type { Preset } from "./types.js";
+export interface LogseqPresetOptions {
+    /**
+     * Content following a heading becomes children of that heading's block
+     * in Logseq's outline: paragraphs turn into child block headlines one
+     * level deeper; other constructs stay in the preceding block's body.
+     * Default: `true`.
+     */
+    nestUnderHeadings?: boolean;
+}
+/**
+ * Logseq dialect preset: `heading::` properties and outline nesting.
+ */
+export declare function logseq(options?: LogseqPresetOptions): Preset;
+/**
+ * Applies Logseq-specific conventions to a uniorg AST: every heading gets
+ * a `:heading:` property drawer, and with `nestUnderHeadings` following
+ * paragraphs become child block headlines (in Logseq's org format every
+ * outline block is a headline).
+ * @param uniorgAst The uniorg AST to transform.
+ * @param nestUnderHeadings Nest content as child blocks. Default: `true`.
+ * @returns The Logseq-flavored uniorg AST.
+ */
+export declare function applyLogseqSpecificsToUniorgAst(uniorgAst: OrgData, nestUnderHeadings?: boolean): OrgData;