@dogsbay/format-myst 0.2.0-beta.101

package/dist/translate.js

@@ -0,0 +1,678 @@
+/**
+ * MyST Markdown → Dogsbay-MD text translator.
+ *
+ * MyST (Markedly Structured Text) is CommonMark + Sphinx-style
+ * **directives**, **roles**, and **targets**. Dogsbay-MD is CommonMark +
+ * `:::` block directives + `{attrs}`. So — exactly like the GitBook and
+ * AsciiDoc pipelines — translation is largely a delimiter rewrite: prose,
+ * lists, tables, and normal fenced code pass through untouched; only the
+ * MyST-specific constructs are rewritten, after which the canonical
+ * `dogsbayMdToTree` parser is the definition of correctness (zero new
+ * TreeNode types).
+ *
+ * Three MyST construct classes:
+ *   - **Directives** — a fenced block, either ```` ```{name} ```` (backtick)
+ *     or `:::{name}` (colon fence). An optional argument follows the name on
+ *     the opener line; `:key: value` option lines may follow; then a blank
+ *     line and the body. These map to `:::` block directives (callouts,
+ *     tabs, grid, details, figure, math, code) and can NEST — emitted with
+ *     DEPTH-AWARE fence lengths (outer gets more colons), mirroring
+ *     format-dogsbay-md's serializer and format-gitbook's translator.
+ *   - **Roles** — inline ``{name}`content` `` → a link / math / `<sub>` /
+ *     code span / emphasis, per role.
+ *   - **Targets** — `(label)=` on its own line before a block → a `{#label}`
+ *     anchor on the following heading (or a bare `<a id>` otherwise), so
+ *     `{ref}`label`` cross-references resolve.
+ *
+ * Fence-aware throughout: MyST syntax inside a plain fenced code block is
+ * literal and never rewritten. Anything unmapped is recorded in the
+ * returned `ledger` (never silent loss — same discipline as format-dita /
+ * format-gitbook) and passed through as best-effort text.
+ *
+ * See plans/format-myst.md.
+ */
+/**
+ * MyST admonition directive → Dogsbay callout name. Sphinx/docutils ship
+ * ten admonition types; MyST/sphinx-design add a couple. Dogsbay has
+ * note/tip/warning/danger/info/success/caution/important — the rest fold
+ * onto the nearest match.
+ */
+const ADMONITION_TO_CALLOUT = {
+    note: "note",
+    tip: "tip",
+    hint: "tip",
+    important: "important",
+    warning: "warning",
+    attention: "warning",
+    caution: "caution",
+    danger: "danger",
+    error: "danger",
+    seealso: "note",
+};
+/** Directives dropped from the body entirely (structural / auto-generated). */
+const DROPPED_DIRECTIVES = new Set(["contents", "tableofcontents", "toctree"]);
+// ── Fence / opener recognition ─────────────────────────────────────────────
+const CODE_FENCE_RE = /^(\s*)(`{3,}|~{3,})(.*)$/;
+/**
+ * Match a directive opener: 3+ backticks OR 3+ colons, immediately
+ * followed by `{name}` and an optional argument. Returns null for a plain
+ * code fence (no `{…}`) or non-fence lines.
+ */
+function matchDirectiveOpener(line) {
+    const m = line.match(/^\s*(`{3,}|:{3,})\{([a-zA-Z0-9_+-]+)\}\s*(.*?)\s*$/);
+    if (!m)
+        return null;
+    return {
+        char: m[1][0],
+        len: m[1].length,
+        name: m[2].toLowerCase(),
+        arg: m[3] ?? "",
+    };
+}
+/** Is `line` a closing fence for a block opened with `char` × `len`? */
+function isCloseFence(line, char, len) {
+    const re = char === "`"
+        ? new RegExp(`^\\s*\`{${len},}\\s*$`)
+        : new RegExp(`^\\s*:{${len},}\\s*$`);
+    return re.test(line);
+}
+// ── Block capture (nesting-aware) ─────────────────────────────────────────
+/**
+ * Given a directive opened at `openIdx`, return its body lines and the
+ * index of the line AFTER its close. Nested fenced blocks (directives or
+ * plain code) are skipped so their own closes don't terminate the outer
+ * block — correct regardless of the relative fence lengths MyST authors
+ * choose. An unterminated directive runs to EOF.
+ */
+function captureBlock(lines, openIdx, char, len) {
+    const body = [];
+    let j = openIdx + 1;
+    while (j < lines.length) {
+        const line = lines[j];
+        if (isCloseFence(line, char, len)) {
+            return { body, nextIdx: j + 1 };
+        }
+        // Skip a nested directive block wholesale.
+        const nested = matchDirectiveOpener(line);
+        if (nested) {
+            const inner = captureBlock(lines, j, nested.char, nested.len);
+            for (let k = j; k < inner.nextIdx; k++)
+                body.push(lines[k]);
+            j = inner.nextIdx;
+            continue;
+        }
+        // Skip a nested PLAIN code fence (```lang … ```), so a stray ::: or
+        // ``` inside example code can't close the directive.
+        const cf = line.match(CODE_FENCE_RE);
+        if (cf) {
+            const marker = cf[2];
+            body.push(line);
+            j++;
+            while (j < lines.length) {
+                body.push(lines[j]);
+                const cm = lines[j].match(CODE_FENCE_RE);
+                if (cm && cm[2][0] === marker[0] && cm[2].length >= marker.length && !cm[3].trim()) {
+                    j++;
+                    break;
+                }
+                j++;
+            }
+            continue;
+        }
+        body.push(line);
+        j++;
+    }
+    return { body, nextIdx: j };
+}
+/** Split a directive body into `:key: value` options + the remaining body. */
+function splitOptions(body) {
+    const options = {};
+    let i = 0;
+    // Skip a leading blank line (some authors put one before options).
+    while (i < body.length && !body[i].trim())
+        i++;
+    for (; i < body.length; i++) {
+        const m = body[i].match(/^\s*:([a-zA-Z][\w-]*):\s?(.*)$/);
+        if (!m)
+            break;
+        options[m[1].toLowerCase()] = m[2].trim();
+    }
+    // One blank line customarily separates options from content — drop it.
+    if (i < body.length && !body[i].trim())
+        i++;
+    return { options, rest: body.slice(i) };
+}
+// ── Main entry ─────────────────────────────────────────────────────────────
+export function mystToDogsbayMd(src) {
+    const ledger = [];
+    const toctree = [];
+    const lines = src.replace(/\r\n?/g, "\n").split("\n");
+    const out = translateLines(lines, 0, ledger, toctree);
+    return { markdown: out.trimEnd() + "\n", ledger, toctree };
+}
+/**
+ * Translate a run of lines (a whole doc, or a directive body). `baseLine`
+ * is the 1-based source line of `lines[0]` for ledger accuracy.
+ */
+function translateLines(lines, baseLine, ledger, toctree) {
+    const parts = [];
+    let i = 0;
+    let pendingTarget = null;
+    const flushTargetAsAnchor = () => {
+        if (pendingTarget) {
+            parts.push(`<a id="${pendingTarget}"></a>`);
+            pendingTarget = null;
+        }
+    };
+    while (i < lines.length) {
+        const line = lines[i];
+        const lineNo = baseLine + i + 1;
+        // Plain fenced code block (no `{…}`): copy verbatim.
+        const cf = line.match(CODE_FENCE_RE);
+        if (cf && !matchDirectiveOpener(line)) {
+            const marker = cf[2];
+            const block = [line];
+            i++;
+            while (i < lines.length) {
+                block.push(lines[i]);
+                const cm = lines[i].match(CODE_FENCE_RE);
+                i++;
+                if (cm && cm[2][0] === marker[0] && cm[2].length >= marker.length && !cm[3].trim())
+                    break;
+            }
+            flushTargetAsAnchor();
+            parts.push(block.join("\n"));
+            continue;
+        }
+        // Directive opener.
+        const opener = matchDirectiveOpener(line);
+        if (opener) {
+            const { body, nextIdx } = captureBlock(lines, i, opener.char, opener.len);
+            const emitted = emitDirective(opener, body, baseLine + i, ledger, toctree);
+            i = nextIdx;
+            if (emitted === null) {
+                // Dropped (toctree / contents). A target that pointed AT this
+                // directive must not leak onto the next block — emit it here as a
+                // bare anchor so the label resolves to this position (or is a
+                // harmless orphan) rather than mis-attaching downstream.
+                flushTargetAsAnchor();
+                continue;
+            }
+            flushTargetAsAnchor();
+            parts.push(emitted);
+            continue;
+        }
+        // Target `(label)=` — attach to the following heading, else emit an anchor.
+        const target = line.match(/^\(([A-Za-z0-9_.:+-]+)\)=\s*$/);
+        if (target) {
+            pendingTarget = target[1];
+            i++;
+            continue;
+        }
+        // Line comment `% …` — MyST comment, dropped.
+        if (/^\s*%(\s|$)/.test(line)) {
+            i++;
+            continue;
+        }
+        // Block break `+++` (MyST cell/part break) — dropped.
+        if (/^\s*\+\+\+/.test(line)) {
+            i++;
+            continue;
+        }
+        // A pending target attaches to the FOLLOWING block. Blank lines between
+        // the `(label)=` and that block are common in MyST — skip them without
+        // discarding the target.
+        if (pendingTarget) {
+            if (!line.trim()) {
+                parts.push(line);
+                i++;
+                continue;
+            }
+            const h = line.match(/^(#{1,6})\s+(.*?)\s*(\{#([^}]+)\})?\s*$/);
+            if (h) {
+                const authorId = h[4];
+                if (authorId && authorId !== pendingTarget) {
+                    // Heading already has an explicit id — keep it, and emit the
+                    // target as a separate anchor so BOTH cross-refs resolve.
+                    parts.push(`<a id="${pendingTarget}"></a>`);
+                    parts.push(`${h[1]} ${transformInline(h[2], ledger, lineNo)} {#${authorId}}`);
+                }
+                else {
+                    parts.push(`${h[1]} ${transformInline(h[2], ledger, lineNo)} {#${pendingTarget}}`);
+                }
+                pendingTarget = null;
+                i++;
+                continue;
+            }
+            // Non-heading block: emit a bare anchor, then render the line.
+            flushTargetAsAnchor();
+        }
+        parts.push(transformInline(line, ledger, lineNo));
+        i++;
+    }
+    return parts.join("\n").replace(/\n{3,}/g, "\n\n");
+}
+// ── Directive emission ─────────────────────────────────────────────────────
+/**
+ * Render one directive to Dogsbay-MD, or null when it should be dropped
+ * from the body (toctree / contents). Recurses into the body for nested
+ * directives + inline roles.
+ */
+function emitDirective(opener, rawBody, openLineIdx, ledger, toctree) {
+    const { name, arg } = opener;
+    const line = openLineIdx + 1;
+    const { options, rest } = splitOptions(rawBody);
+    // Structural directives collected/dropped, not rendered inline.
+    if (name === "toctree") {
+        for (const raw of rest) {
+            const t = raw.trim();
+            if (t && !t.startsWith(":"))
+                toctree.push(t);
+        }
+        return null;
+    }
+    if (DROPPED_DIRECTIVES.has(name))
+        return null;
+    const bodyText = () => translateLines(rest, openLineIdx + 1 + (rawBody.length - rest.length), ledger, toctree).trim();
+    // Admonitions → callouts.
+    if (name in ADMONITION_TO_CALLOUT) {
+        const title = arg.trim();
+        const attrs = title ? attrBlock({ title }) : "";
+        return fenced(ADMONITION_TO_CALLOUT[name], attrs, bodyText());
+    }
+    if (name === "admonition") {
+        // Generic admonition: `:class:` picks the style, arg is the title.
+        const cls = (options.class ?? "").toLowerCase().split(/\s+/).find((c) => c in ADMONITION_TO_CALLOUT);
+        const dir = cls ? ADMONITION_TO_CALLOUT[cls] : "note";
+        const title = arg.trim();
+        return fenced(dir, title ? attrBlock({ title }) : "", bodyText());
+    }
+    switch (name) {
+        // sphinx-design tabs.
+        case "tab-set":
+            return fenced("tabs", "", bodyText());
+        case "tab-item":
+            return fenced("tab", arg.trim() ? attrBlock({ title: arg.trim() }) : "", bodyText());
+        // sphinx-design grid + cards.
+        case "grid":
+            return fenced("grid", "", bodyText());
+        case "grid-item":
+            return fenced("grid-item", "", bodyText());
+        case "grid-item-card":
+        case "card":
+            return fenced("card", arg.trim() ? attrBlock({ title: arg.trim() }) : "", bodyText());
+        // Collapsible.
+        case "dropdown":
+            return fenced("details", arg.trim() ? attrBlock({ title: arg.trim() }) : "", bodyText());
+        // Figures / images.
+        case "figure":
+            return emitFigure(arg.trim(), options, rest, ledger, toctree, openLineIdx);
+        case "image":
+            return emitImage(arg.trim(), options);
+        // Math.
+        case "math":
+            return emitMath(options, rest);
+        // Code.
+        case "code-block":
+        case "code":
+        case "sourcecode":
+            return emitCode(arg.trim(), options, rest, ledger, line);
+        // Version notes → inline emphasis (mirrors format-rst Phase 4: a badge,
+        // not a heavy callout box).
+        case "versionadded":
+        case "versionchanged":
+        case "deprecated": {
+            const label = name === "versionadded" ? "Added in version" : name === "deprecated" ? "Deprecated since version" : "Changed in version";
+            const prefix = arg.trim() ? `*${label} ${arg.trim()}.*` : `*${label}.*`;
+            const body = bodyText();
+            return body ? `${prefix} ${body}` : prefix;
+        }
+        // Rubric — an unnumbered heading-like label.
+        case "rubric":
+            return arg.trim() ? `**${transformInline(arg.trim(), ledger, line)}**` : bodyText();
+        // Block quotes with attribution.
+        case "epigraph":
+        case "pull-quote":
+        case "highlights": {
+            const body = bodyText();
+            return body
+                .split("\n")
+                .map((l) => (l ? `> ${l}` : ">"))
+                .join("\n");
+        }
+        // Table directives → a real Markdown table. Cells are run through the
+        // inline transformer so roles inside them resolve. If parsing yields no
+        // rows, fall back to keeping the raw body + a ledger entry (never worse).
+        case "list-table":
+        case "csv-table": {
+            const rows = name === "list-table" ? parseListTable(rest) : parseCsvTable(rest, options);
+            const headerRows = name === "list-table"
+                ? Math.max(0, parseInt(options["header-rows"] ?? "0", 10) || 0)
+                : options.header
+                    ? 1
+                    : 0;
+            const table = renderMarkdownTable(rows, headerRows, (c) => transformInline(c, ledger, line));
+            if (table) {
+                // The caption rides as a `{caption="…"}` attribute block after the
+                // table — dogsbay-md reattaches it as a real `<caption>` on re-parse.
+                const cap = arg.trim();
+                return cap ? `${table}\n\n{caption="${captionAttr(cap)}"}` : table;
+            }
+            ledger.push({
+                construct: `{${name}}`,
+                note: `table body could not be parsed — kept as raw content`,
+                line,
+            });
+            const title = arg.trim() ? `**${arg.trim()}**\n\n` : "";
+            return title + bodyText();
+        }
+        // Includes — Dogsbay resolves includes at build; ledger the reference.
+        case "include":
+        case "literalinclude": {
+            ledger.push({
+                construct: `{${name}} ${arg.trim()}`,
+                note: `file include not inlined at migrate time; wire up a build-time include or paste the content`,
+                line,
+            });
+            return `<!-- ${name}: ${arg.trim()} -->`;
+        }
+        default: {
+            // Unknown directive: keep the body (translated), ledger the wrapper.
+            ledger.push({
+                construct: `{${name}}`,
+                note: `unknown directive — body kept, wrapper dropped`,
+                line,
+            });
+            return bodyText();
+        }
+    }
+}
+/**
+ * Emit a `:::name{attrs}\nbody\n:::` with a colon fence strictly longer
+ * than any `:::` fence already in the body — markdown-it-container closes
+ * an outer `:::` at the first bare `:::`, so a nested directive needs the
+ * outer to use MORE colons. Minimal (`inner + 1`), mirroring
+ * format-gitbook's fence-scaling.
+ */
+function fenced(name, attrs, body) {
+    const colons = ":".repeat(Math.max(3, longestColonFence(body) + 1));
+    return `${colons}${name}${attrs}\n${body}\n${colons}`;
+}
+// ── Tables ─────────────────────────────────────────────────────────────────
+/** Escape a caption for a `{caption="…"}` attribute value (quotes only). */
+function captionAttr(text) {
+    return text.replace(/"/g, "&quot;").replace(/\n+/g, " ").trim();
+}
+/** Strip the common leading indentation from a block of lines. */
+function dedent(lines) {
+    const indents = lines
+        .filter((l) => l.trim())
+        .map((l) => l.match(/^\s*/)[0].length);
+    const min = indents.length ? Math.min(...indents) : 0;
+    return lines.map((l) => l.slice(min));
+}
+/**
+ * Parse a `{list-table}` body — a bulleted list where each top-level bullet
+ * is a ROW and its nested bullets are the CELLS:
+ *
+ *   * - Name          → row 1: ["Name", "Age"]
+ *     - Age
+ *   * - Alice
+ *     - 30
+ *
+ * Both the inline `* - cell` form and a lone `*` row marker (cells on
+ * following `- cell` lines) are handled. Continuation lines append to the
+ * current cell. A cell that itself contains a nested bullet list is a known
+ * limitation (rare in list-tables).
+ */
+function parseListTable(rawLines) {
+    const lines = dedent(rawLines);
+    const rows = [];
+    let cur = null;
+    for (const line of lines) {
+        // Row start with an inline first cell: `* - content`
+        const rowInline = line.match(/^[*+-][ \t]+[*+-][ \t]?(.*)$/);
+        if (rowInline) {
+            cur = [rowInline[1]];
+            rows.push(cur);
+            continue;
+        }
+        // A lone row bullet: `*` (cells follow on `- cell` lines)
+        if (/^[*+-][ \t]*$/.test(line)) {
+            cur = [];
+            rows.push(cur);
+            continue;
+        }
+        // Another cell in the current row: `- content` (indented under the row)
+        const cellM = line.match(/^\s*[*+-][ \t]?(.*)$/);
+        if (cellM && cur) {
+            cur.push(cellM[1]);
+            continue;
+        }
+        // Continuation of the current cell.
+        if (cur && cur.length && line.trim()) {
+            cur[cur.length - 1] += ` ${line.trim()}`;
+        }
+    }
+    return rows.map((r) => r.map((c) => c.trim()));
+}
+/** Parse one CSV record (comma-delimited, `"`-quoted, `""` escape). */
+function parseCsvLine(line) {
+    const out = [];
+    let cur = "";
+    let inQuote = false;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (inQuote) {
+            if (ch === '"') {
+                if (line[i + 1] === '"') {
+                    cur += '"';
+                    i++;
+                }
+                else
+                    inQuote = false;
+            }
+            else
+                cur += ch;
+        }
+        else if (ch === '"') {
+            inQuote = true;
+        }
+        else if (ch === ",") {
+            out.push(cur.trim());
+            cur = "";
+        }
+        else
+            cur += ch;
+    }
+    out.push(cur.trim());
+    return out;
+}
+/** Parse a `{csv-table}` body (+ its `:header:` option) into rows. */
+function parseCsvTable(rawLines, options) {
+    const rows = [];
+    if (options.header)
+        rows.push(parseCsvLine(options.header));
+    for (const line of dedent(rawLines)) {
+        if (!line.trim())
+            continue;
+        rows.push(parseCsvLine(line));
+    }
+    return rows;
+}
+/**
+ * Emit a GitHub-flavoured Markdown table. `headerRows` says how many
+ * leading rows are header: 0 → an empty header row (Markdown requires one);
+ * ≥1 → the FIRST row is the header (extra header rows fall through as body,
+ * since Markdown supports a single header row). Cells are passed through
+ * `cell()` (inline transform) and pipe-escaped.
+ */
+function renderMarkdownTable(rows, headerRows, cell) {
+    if (rows.length === 0)
+        return null;
+    const ncol = Math.max(...rows.map((r) => r.length));
+    if (ncol === 0)
+        return null;
+    const fmt = (s) => cell(s).replace(/\n+/g, " ").replace(/\|/g, "\\|").trim();
+    const pad = (r) => {
+        const c = r.map(fmt);
+        while (c.length < ncol)
+            c.push("");
+        return c;
+    };
+    const out = [];
+    const header = headerRows > 0 ? pad(rows[0]) : new Array(ncol).fill("");
+    out.push(`| ${header.join(" | ")} |`);
+    out.push(`| ${new Array(ncol).fill("---").join(" | ")} |`);
+    for (let i = headerRows > 0 ? 1 : 0; i < rows.length; i++) {
+        out.push(`| ${pad(rows[i]).join(" | ")} |`);
+    }
+    return out.join("\n");
+}
+function emitFigure(src, options, rest, ledger, toctree, openLineIdx) {
+    const alt = options.alt ?? "";
+    const img = `![${alt}](${src})`;
+    // The figure body (after options) is the caption + optional legend.
+    const caption = translateLines(rest, openLineIdx + 2, ledger, toctree).trim();
+    return caption ? `${img}\n\n*${caption.replace(/\n+/g, " ")}*` : img;
+}
+function emitImage(src, options) {
+    const alt = options.alt ?? "";
+    return `![${alt}](${src})`;
+}
+function emitMath(options, rest) {
+    const expr = rest.join("\n").trim();
+    const label = options.label;
+    const anchor = label ? `<a id="${label}"></a>\n` : "";
+    return `${anchor}$$\n${expr}\n$$`;
+}
+function emitCode(lang, options, rest, ledger, line) {
+    const code = rest.join("\n").replace(/\n+$/, "");
+    const attrs = [];
+    if (options.caption)
+        attrs.push(`title="${options.caption.replace(/"/g, "&quot;")}"`);
+    if ("linenos" in options || "lineno-start" in options)
+        attrs.push(`lineNumbers="true"`);
+    if (options["emphasize-lines"]) {
+        ledger.push({
+            construct: `{code-block} :emphasize-lines:`,
+            note: `line emphasis dropped — Dogsbay CodeRich uses a different highlight syntax`,
+            line,
+        });
+    }
+    const info = [lang, ...attrs].filter(Boolean).join(" ");
+    return "```" + info + "\n" + code + "\n```";
+}
+// ── Inline roles ───────────────────────────────────────────────────────────
+/**
+ * Rewrite inline MyST roles ``{name}`content` `` on a content line. Prose,
+ * links, emphasis, and — crucially — inline **code spans** pass through
+ * untouched.
+ *
+ * A role and a code span are both delimited by backticks, so a plain regex
+ * can't tell ``{ref}`x` `` (role) from `` `{ref}` `` (a code span that
+ * merely CONTAINS `{ref}`). We therefore scan left-to-right: a backtick is
+ * the start of a role only when the text just emitted ends with `{name}`
+ * (the MyST role form — no space between `}` and the backtick); otherwise
+ * it opens an ordinary inline code span, which is copied verbatim so a role
+ * name mentioned inside example code is never rewritten.
+ */
+function transformInline(line, ledger, lineNo) {
+    let out = "";
+    let i = 0;
+    const n = line.length;
+    while (i < n) {
+        const ch = line[i];
+        if (ch === "`") {
+            const roleMatch = out.match(/\{([a-zA-Z0-9_+-]+)\}$/);
+            const close = line.indexOf("`", i + 1);
+            if (roleMatch && close !== -1) {
+                // {name}`content` — a role. Drop the already-emitted `{name}`.
+                out = out.slice(0, out.length - roleMatch[0].length);
+                out += renderRole(roleMatch[1].toLowerCase(), line.slice(i + 1, close), ledger, lineNo);
+                i = close + 1;
+                continue;
+            }
+            // Ordinary inline code span (or an unterminated backtick) — verbatim.
+            if (close !== -1) {
+                out += line.slice(i, close + 1);
+                i = close + 1;
+                continue;
+            }
+        }
+        out += ch;
+        i++;
+    }
+    return out;
+}
+/** Render one MyST role `{name}` with body `content` to Dogsbay-MD inline. */
+function renderRole(role, content, ledger, lineNo) {
+    switch (role) {
+        case "doc":
+        case "ref":
+        case "numref":
+        case "eq":
+        case "download": {
+            const { text, target } = splitRoleTarget(content);
+            const href = role === "doc" || role === "download" ? target : `#${target}`;
+            return `[${text || target}](${href})`;
+        }
+        case "math":
+            return `$${content}$`;
+        case "sub":
+            return `<sub>${content}</sub>`;
+        case "sup":
+            return `<sup>${content}</sup>`;
+        case "kbd":
+            return `<kbd>${content}</kbd>`;
+        case "abbr": {
+            // {abbr}`HTML (HyperText Markup Language)`
+            const m = content.match(/^(.*?)\s*\(([^)]*)\)\s*$/);
+            if (m)
+                return `<abbr title="${m[2].replace(/"/g, "&quot;")}">${m[1]}</abbr>`;
+            return content;
+        }
+        case "file":
+        case "command":
+        case "samp":
+        case "program":
+        case "code":
+            return `\`${content}\``;
+        case "guilabel":
+        case "menuselection":
+            return `**${content}**`;
+        case "term":
+            // Glossary term — no glossary target model yet; keep the text.
+            ledger.push({ construct: "{term}", note: "glossary term rendered as plain text", line: lineNo });
+            return content;
+        default:
+            ledger.push({ construct: `{${role}}`, note: "unknown role — rendered as plain text", line: lineNo });
+            return content;
+    }
+}
+/** Split a role body of the form `Explicit Text <target>` → {text, target}. */
+function splitRoleTarget(content) {
+    const m = content.match(/^(.*?)\s*<([^>]+)>\s*$/);
+    if (m)
+        return { text: m[1].trim(), target: m[2].trim() };
+    return { text: "", target: content.trim() };
+}
+// ── Attributes / fences ────────────────────────────────────────────────────
+function attrBlock(attrs) {
+    const keys = Object.keys(attrs).filter((k) => attrs[k] !== "");
+    if (keys.length === 0)
+        return "";
+    const inner = keys.map((k) => `${k}="${attrs[k].replace(/"/g, "&quot;")}"`).join(" ");
+    return `{${inner}}`;
+}
+/** Longest run of `:` in a line-start `:::…` directive fence within text. */
+function longestColonFence(text) {
+    let max = 0;
+    for (const l of text.split("\n")) {
+        const m = l.match(/^(:{3,})/);
+        if (m)
+            max = Math.max(max, m[1].length);
+    }
+    return max;
+}
+//# sourceMappingURL=translate.js.map