@remigius42/morg 0.8.0 → 0.9.0

package/dist/presets/logseqVanillaMarkdown.js

@@ -0,0 +1,295 @@
+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 { visit } from "unist-util-visit";
+// Vanilla Markdown read as Logseq's outline (ADR 0006), as Logseq reads
+// a file it did not write: a list item is a block, its nested list its
+// children.
+function parse(markdown) {
+    return unified()
+        .use(remarkParse)
+        .use(remarkGfm)
+        .use(remarkFrontmatter)
+        .use(remarkMath)
+        .parse(markdown);
+}
+// a node's source lines, 0-based start and end line
+function span(node) {
+    return [
+        (node.position?.start.line ?? 1) - 1,
+        (node.position?.end.line ?? 1) - 1
+    ];
+}
+const BULLET_RE = /^\s*(?:[-*+]|\d+[.)])(?: |$)/;
+const CHECKBOX_RE = /^\[([ xX])\](?: |$)/;
+// the markers Logseq shows unchecked other than TODO, which a task item
+// writes after its checkbox
+const UNCHECKED_MARKER_RE = /^(?:NOW|LATER|DOING|IN-PROGRESS|WAIT|WAITING) /;
+const PROPERTY_RE = /^([\w.-]+)::(?: (.*))?$/;
+const HEADING_RE = /^(#{1,6})(?: (.*))?$/;
+// a task item's checkbox as Logseq's task marker
+function taskTitle(item, title) {
+    const checkbox = CHECKBOX_RE.exec(title);
+    if (item.checked === null || item.checked === undefined || !checkbox) {
+        return title;
+    }
+    const text = title.slice(checkbox[0].length);
+    if (item.checked) {
+        return `DONE ${text}`;
+    }
+    return UNCHECKED_MARKER_RE.test(text) ? text : `TODO ${text}`;
+}
+// key:: lines: planning under its org-ism names (orgismKeys maps them),
+// one planning line where the first of them was, and properties
+function readMeta(lines, context) {
+    const canonical = new Map(Object.entries(context.orgismKeys ?? {}).map(([key, custom]) => [
+        custom,
+        key
+    ]));
+    const meta = [];
+    let planning;
+    for (const line of lines) {
+        const [, rawKey = "", value = ""] = PROPERTY_RE.exec(line) ?? [];
+        const key = canonical.get(rawKey) ?? rawKey;
+        if (key !== "scheduled" && key !== "deadline") {
+            meta.push({ key: rawKey, value });
+            continue;
+        }
+        const entry = `${key.toUpperCase()}: ${value}`;
+        if (planning) {
+            planning.lines[0] += ` ${entry}`;
+        }
+        else {
+            planning = { lines: [entry] };
+            meta.push(planning);
+        }
+    }
+    return meta;
+}
+// a lazy continuation line sits anywhere left of the column
+function dedent(line, column) {
+    const indent = /^ */.exec(line)?.[0].length ?? 0;
+    return line.slice(Math.min(indent, column));
+}
+function leadingProperties(lines) {
+    const count = lines.findIndex(line => !PROPERTY_RE.test(line));
+    return count === -1 ? lines.length : count;
+}
+// an item's own lines, up to its nested list: the bullet off its first,
+// its checkbox read, continuation lines moved left past the bullet
+function itemSource(item, end, lines) {
+    const [first = "", ...rest] = lines.slice(span(item)[0], end + 1);
+    const column = BULLET_RE.exec(first)?.[0].length ?? 0;
+    return [
+        taskTitle(item, first.slice(column)),
+        ...rest.map(line => dedent(line, column))
+    ];
+}
+// a title as a heading's level and text
+function readHeading(title) {
+    const match = HEADING_RE.exec(title);
+    return match ? [match[1]?.length ?? 0, match[2] ?? ""] : [0, title];
+}
+// key:: lines below the title, or opening the content, are its meta
+function itemBlock(source, level, reader) {
+    const metaFirst = PROPERTY_RE.test(source[0] ?? "");
+    const body = metaFirst ? source : source.slice(1);
+    const count = leadingProperties(body);
+    const meta = readMeta(body.slice(0, count), reader.context);
+    if (metaFirst) {
+        return { level, heading: 0, metaFirst, meta, content: body.slice(count) };
+    }
+    const [heading, title] = readHeading(source[0] ?? "");
+    return {
+        level,
+        heading,
+        metaFirst,
+        meta,
+        content: [title, ...body.slice(count)]
+    };
+}
+function readItem(item, level, ordered, reader) {
+    // a list on the item's first line is its content, not its children
+    const nested = item.children.filter((child) => child.type === "list" && span(child)[0] > span(item)[0]);
+    const end = nested[0] ? span(nested[0])[0] - 1 : span(item)[1];
+    const block = itemBlock(itemSource(item, end, reader.lines), level, reader);
+    if (ordered) {
+        block.meta.push({ key: "logseq.order-list-type", value: "number" });
+    }
+    reader.blocks.push(block);
+    // what follows the first nested list: more lists, and text, which a
+    // block's content cannot hold after its children, as child blocks
+    const column = BULLET_RE.exec(reader.lines[span(item)[0]] ?? "")?.[0].length;
+    const rest = nested[0]
+        ? item.children.slice(item.children.indexOf(nested[0]))
+        : [];
+    for (const child of rest) {
+        if (child.type === "list") {
+            readList(child, level + 1, reader);
+            continue;
+        }
+        const [start, end] = span(child);
+        reader.blocks.push({
+            level: level + 1,
+            heading: 0,
+            metaFirst: false,
+            meta: [],
+            content: reader.lines
+                .slice(start, end + 1)
+                .map(line => dedent(line, column ?? 0))
+        });
+    }
+}
+function readList(list, level, reader) {
+    for (const item of list.children) {
+        readItem(item, level, Boolean(list.ordered), reader);
+    }
+}
+function headingBlock(node, headings, lines) {
+    while ((headings.at(-1)?.depth ?? 0) >= node.depth) {
+        headings.pop();
+    }
+    const level = (headings.at(-1)?.level ?? 0) + 1;
+    headings.push({ depth: node.depth, level });
+    return {
+        level,
+        heading: node.depth,
+        metaFirst: false,
+        meta: [],
+        content: [headingTitle(lines[span(node)[0]] ?? "")]
+    };
+}
+// a link destination as Markdown writes it inline
+function destination(url) {
+    return /[\s()<>]/.test(url) ? `<${url}>` : url;
+}
+function offsets(node) {
+    return [node.position?.start.offset ?? 0, node.position?.end.offset ?? 0];
+}
+// what spans a page cannot travel in a block: a reference link becomes
+// inline, a definition goes, and so does a footnote's definition, kept
+// for the block of its first reference (ADR 0006)
+function resolveReferences(markdown) {
+    // links first: a footnote's definition may hold one
+    const inline = inlineReferences(markdown);
+    const footnotes = new Map();
+    const edits = [];
+    visit(parse(inline), "footnoteDefinition", (node) => {
+        const [start, end] = offsets(node);
+        footnotes.set(node.label ?? "", inline.slice(start, end));
+        edits.push([start, end, ""]);
+    });
+    return { markdown: applyEdits(inline, edits), footnotes };
+}
+function inlineReferences(markdown) {
+    const tree = parse(markdown);
+    const definitions = new Map();
+    visit(tree, "definition", (node) => {
+        definitions.set(node.identifier, node);
+    });
+    const edits = [];
+    visit(tree, (node) => {
+        const [start, end] = offsets(node);
+        if (node.type === "definition") {
+            edits.push([start, end, ""]);
+        }
+        else if (node.type === "linkReference" ||
+            node.type === "imageReference") {
+            const reference = node;
+            const definition = definitions.get(reference.identifier);
+            if (definition) {
+                edits.push([start, end, inlineLink(reference, definition, markdown)]);
+            }
+        }
+    });
+    return applyEdits(markdown, edits);
+}
+// edits of nodes that do not nest, last first so offsets hold
+function applyEdits(text, edits) {
+    let result = text;
+    for (const [start, end, replacement] of edits.sort((a, b) => b[0] - a[0])) {
+        result = result.slice(0, start) + replacement + result.slice(end);
+    }
+    return result;
+}
+function inlineLink(reference, definition, markdown) {
+    const title = definition.title ? ` "${definition.title}"` : "";
+    const target = `(${destination(definition.url)}${title})`;
+    if (reference.type === "imageReference") {
+        return `![${reference.alt ?? ""}]${target}`;
+    }
+    const first = reference.children[0];
+    const last = reference.children.at(-1);
+    const text = first && last ? markdown.slice(offsets(first)[0], offsets(last)[1]) : "";
+    return `[${text}]${target}`;
+}
+// a footnote's definition, after the first block that refers to it
+function placeFootnotes(blocks, footnotes) {
+    for (const [label, definition] of footnotes) {
+        const block = blocks.find(candidate => candidate.content.some(line => line.includes(`[^${label}]`)));
+        block?.content.push("", ...definition.split("\n").map(line => line.trim()));
+    }
+}
+/**
+ * Reads a Vanilla Markdown page into Logseq's outline.
+ * @param markdown The Markdown page.
+ * @param context The conversion's org-ism key names.
+ * @returns The outline, its blocks' content in Markdown.
+ */
+export function readVanillaMarkdownOutline(markdown, context) {
+    const resolved = resolveReferences(markdown);
+    markdown = resolved.markdown;
+    const reader = {
+        lines: markdown.split(/\r?\n/),
+        blocks: [],
+        context
+    };
+    const headings = [];
+    // a heading whose body is still running: what follows it, up to a
+    // list or the next heading, is its content
+    let body;
+    const page = [];
+    for (const node of parse(markdown).children) {
+        const level = (headings.at(-1)?.level ?? 0) + 1;
+        if (node.type === "yaml") {
+            const [start, end] = span(node);
+            page.push(...reader.lines.slice(start, end + 1));
+        }
+        else if (node.type === "heading") {
+            body = headingBlock(node, headings, reader.lines);
+            reader.blocks.push(body);
+        }
+        else if (node.type === "list") {
+            body = undefined;
+            readList(node, level, reader);
+        }
+        else {
+            readText(node, level, body, reader);
+        }
+    }
+    placeFootnotes(reader.blocks, resolved.footnotes);
+    return { page, blocks: reader.blocks };
+}
+// text below a heading is its body; after a list, a block of its own
+function readText(node, level, body, reader) {
+    const [start, end] = span(node);
+    const source = reader.lines.slice(start, end + 1);
+    if (body) {
+        // the body's paragraphs keep the blank lines between them
+        body.content.push(...(body.content.length > 1 ? [""] : []), ...source);
+        return;
+    }
+    reader.blocks.push({
+        level,
+        heading: 0,
+        metaFirst: false,
+        meta: [],
+        content: source
+    });
+}
+// an ATX heading's text, without its markers
+function headingTitle(line) {
+    return line.replace(/^ {0,3}#{1,6}(?:\s+|$)/, "").replace(/\s+#+\s*$/, "");
+}

package/dist/presets/obsidian.js

@@ -7,8 +7,10 @@ import { toString } from "orgast-util-to-string";
 export function obsidian() {
     return {
         name: "obsidian",
-        applyToUniorg: rewriteAliasedWikilinks,
-        extractFromUniorg: fuzzyLinksToWikilinks
+        markdown: {
+            read: { org: rewriteAliasedWikilinks },
+            write: fuzzyLinksToWikilinks
+        }
     };
 }
 // md→org: a wikilink travels as plain text; org already reads `[[Page]]`

package/dist/presets/registry.d.ts

@@ -2,7 +2,7 @@ import type { Preset } from "./types.js";
 /**
  * Instantiates a preset by name.
  * @param presetName Preset name, or `undefined` for no preset.
- * @returns The preset, or `undefined` when no name was given.
+ * @returns The preset, or `undefined` for none or `vanilla`.
  * @throws If the name is not a known preset.
  */
 export declare function createPreset(presetName: string | undefined): Preset | undefined;

package/dist/presets/registry.js

@@ -6,15 +6,17 @@ const PRESETS = {
     logseq: () => logseq(),
     obsidian: () => obsidian()
 };
-const PRESET_NAMES = Object.keys(PRESETS);
+// the Vanilla side: no preset, but a name to set a side back to it
+const VANILLA = "vanilla";
+const PRESET_NAMES = [VANILLA, ...Object.keys(PRESETS)];
 /**
  * Instantiates a preset by name.
  * @param presetName Preset name, or `undefined` for no preset.
- * @returns The preset, or `undefined` when no name was given.
+ * @returns The preset, or `undefined` for none or `vanilla`.
  * @throws If the name is not a known preset.
  */
 export function createPreset(presetName) {
-    if (!presetName) {
+    if (!presetName || presetName === VANILLA) {
         return undefined;
     }
     const factory = PRESETS[presetName];

package/dist/presets/sides.d.ts

@@ -0,0 +1,40 @@
+import type { Preset } from "./types.js";
+/** The presets of a conversion, by side (ADR 0006). */
+export interface PresetOptions {
+    /** Sets both sides, where a side preset does not. */
+    preset?: Preset;
+    /** The dialect the input is read in. */
+    inputPreset?: Preset;
+    /** The dialect the output is written in. */
+    outputPreset?: Preset;
+}
+/** The preset each side resolved to; `undefined` is Vanilla. */
+export interface Sides {
+    input: Preset | undefined;
+    output: Preset | undefined;
+}
+/** A document format. */
+export type Format = "markdown" | "org";
+/**
+ * Resolves the preset of each side of a conversion. A side preset must
+ * have a dialect for its side's format; `preset` leaves a side it has
+ * none for Vanilla (Obsidian writes no org).
+ * @param options The conversion's preset options.
+ * @param from The input's format.
+ * @param to The output's format.
+ * @returns The preset per side.
+ * @throws If a side preset has no dialect for its side's format, or
+ * `preset` names another preset than a side preset.
+ */
+export declare function resolveSides(options: PresetOptions, from: Format, to: Format): Sides;
+/**
+ * Resolves one side's preset: the side preset, else `preset` where it
+ * has a dialect for the side's format.
+ * @param sidePreset The side's own preset, if any.
+ * @param preset The preset for both sides, if any.
+ * @param format The side's format.
+ * @param side Which side it is.
+ * @returns The side's preset; `undefined` is Vanilla.
+ * @throws If the side preset has no dialect for the format.
+ */
+export declare function resolveSide(sidePreset: Preset | undefined, preset: Preset | undefined, format: Format, side: "input" | "output"): Preset | undefined;

package/dist/presets/sides.js

@@ -0,0 +1,42 @@
+/**
+ * Resolves the preset of each side of a conversion. A side preset must
+ * have a dialect for its side's format; `preset` leaves a side it has
+ * none for Vanilla (Obsidian writes no org).
+ * @param options The conversion's preset options.
+ * @param from The input's format.
+ * @param to The output's format.
+ * @returns The preset per side.
+ * @throws If a side preset has no dialect for its side's format, or
+ * `preset` names another preset than a side preset.
+ */
+export function resolveSides(options, from, to) {
+    for (const key of ["inputPreset", "outputPreset"]) {
+        const sidePreset = options[key];
+        if (options.preset &&
+            sidePreset &&
+            sidePreset.name !== options.preset.name) {
+            throw new Error(`preset '${options.preset.name}' conflicts with ${key} '${sidePreset.name}'`);
+        }
+    }
+    return {
+        input: resolveSide(options.inputPreset, options.preset, from, "input"),
+        output: resolveSide(options.outputPreset, options.preset, to, "output")
+    };
+}
+/**
+ * Resolves one side's preset: the side preset, else `preset` where it
+ * has a dialect for the side's format.
+ * @param sidePreset The side's own preset, if any.
+ * @param preset The preset for both sides, if any.
+ * @param format The side's format.
+ * @param side Which side it is.
+ * @returns The side's preset; `undefined` is Vanilla.
+ * @throws If the side preset has no dialect for the format.
+ */
+export function resolveSide(sidePreset, preset, format, side) {
+    if (sidePreset && !sidePreset[format]) {
+        const purpose = side === "input" ? "read the input" : "write the output";
+        throw new Error(`Preset '${sidePreset.name}' has no ${format} dialect to ${purpose} in`);
+    }
+    return sidePreset ?? (preset?.[format] ? preset : undefined);
+}

package/dist/presets/types.d.ts

@@ -1,23 +1,56 @@
 import type { Root as MdastRoot } from "mdast";
 import type { OrgData } from "uniorg";
 /**
- * A dialect preset: transforms applied on top of the dialect-agnostic core.
- * `applyToMdast` runs in the md→org pipeline before the generic
- * transform, with the Markdown source at hand; `applyToUniorg` runs in the md→org pipeline after the generic transform;
- * `extractFromUniorg` runs in the org→md pipeline before the generic
- * transform, normalizing dialect conventions back to generic uniorg.
- * `convertOrg` and `convertMarkdown` take a whole conversion over, for a
- * dialect whose documents are no single org or Markdown document (an
- * outline of blocks, each its own fragment); `convert` runs the core on
- * a fragment, with the given preset's hooks.
+ * A dialect preset: transforms applied on top of the dialect-agnostic
+ * core, one dialect per format it knows (ADR 0006), each read in one
+ * direction and written in the other. `convertOrg` and
+ * `convertMarkdown` take a whole conversion over, for a dialect whose
+ * documents are no single org or Markdown document (an outline of
+ * blocks, each its own fragment); `convert` runs the core on a fragment,
+ * with the given preset's hooks.
  */
 export interface Preset {
     name: string;
-    applyToMdast?: (mdast: MdastRoot, markdown: string) => void;
-    applyToUniorg?: (uniorgAst: OrgData) => OrgData;
-    extractFromUniorg?: (uniorgAst: OrgData) => OrgData;
-    convertOrg?: (org: string, convert: FragmentConverter) => string;
-    convertMarkdown?: (markdown: string, convert: FragmentConverter) => string;
+    markdown?: MarkdownDialect;
+    org?: OrgDialect;
+    convertOrg?: (org: string, convert: FragmentConverter, context: ConversionContext) => string;
+    convertMarkdown?: (markdown: string, convert: FragmentConverter, context: ConversionContext) => string;
+}
+/**
+ * What a preset that takes a whole conversion over learns of it: the
+ * side or sides it is on (the other one is another preset's or
+ * Vanilla), and the conversion's warning callback and org-ism key names.
+ */
+export interface ConversionContext {
+    side: "both" | "input" | "output";
+    onWarning?: (message: string) => void;
+    orgismKeys?: Record<string, string>;
+}
+/**
+ * Converts a fragment with the core, the given preset's AST hooks on
+ * the taking-over preset's side or sides, and the other side's preset;
+ * a Vanilla side converts with `carried`, the preset whose syntax it
+ * carries.
+ */
+export type FragmentConverter = (fragment: string, preset?: Preset, carried?: Preset) => string;
+/**
+ * A preset's Markdown dialect. `read` runs in md→org: `mdast` on the
+ * parse, before the generic transform, with the source at hand; `org`
+ * after it. `write` runs in org→md before the generic transform.
+ */
+export interface MarkdownDialect {
+    read?: {
+        mdast?: (mdast: MdastRoot, markdown: string) => void;
+        org?: (uniorgAst: OrgData) => OrgData;
+    };
+    write?: (uniorgAst: OrgData) => OrgData;
+}
+/**
+ * A preset's org dialect. `read` runs in org→md before the generic
+ * transform, ahead of the Markdown dialect's `write`; `write` runs in
+ * md→org after the Markdown dialect was read.
+ */
+export interface OrgDialect {
+    read?: (uniorgAst: OrgData) => OrgData;
+    write?: (uniorgAst: OrgData) => OrgData;
 }
-/** Converts a fragment with the core and the given preset's AST hooks. */
-export type FragmentConverter = (fragment: string, preset?: Preset) => string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remigius42/morg",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Bidirectional Markdown ↔ Org-mode converter with round-trip convergence",
   "keywords": [
     "org-mode",