@dogsbay/format-rst 0.2.0-beta.101

package/dist/transform.js

@@ -0,0 +1,675 @@
+/**
+ * docutils XML AST → Dogsbay-MD text.
+ *
+ * The docutils document tree (emitted as XML by the Python sidecar) is a
+ * stable, well-specified node set (the Docutils DTD). This transformer
+ * walks it and emits Dogsbay-MD — the canonical `dogsbayMdToTree` then
+ * produces the TreeNode, so no new node types are needed (same shape as
+ * format-gitbook / format-asciidoc).
+ *
+ * Standard rST + core directives are handled here (Phase 1). Sphinx-only
+ * directives/roles arrive as `system_message` / `problematic` nodes under
+ * plain docutils — those are ledgered (never silent loss) and resolve
+ * properly once Sphinx mode (Phase 2) feeds a resolved tree.
+ *
+ * See plans/format-rst.md for the full node→Dogsbay-MD mapping.
+ */
+import { parseDocument } from "htmlparser2";
+import { stringify as stringifyYaml } from "yaml";
+// NOTE: guard on the node's `.type` string, never `instanceof`. htmlparser2
+// builds the tree with its own bundled copy of domhandler, which may be a
+// different module instance than the one we import — `instanceof Element`
+// then silently returns false for every node and the whole tree reads as
+// empty. `.type` is a plain string and cross-copy safe.
+function isTag(n) {
+    return n.type === "tag" || n.type === "script" || n.type === "style";
+}
+function isTextNode(n) {
+    return n.type === "text";
+}
+function textData(n) {
+    return n.data ?? "";
+}
+/** All child nodes (text + elements) — for inline rendering, which needs
+ * text nodes. (`elementChildren` is tags-only, for block iteration.) */
+function kids(el) {
+    return el.children ?? [];
+}
+/** docutils admonition element → Dogsbay callout directive name. */
+const ADMONITION_TO_CALLOUT = {
+    note: "note",
+    tip: "tip",
+    hint: "tip",
+    important: "important",
+    warning: "warning",
+    caution: "caution",
+    danger: "danger",
+    attention: "note",
+    error: "danger",
+};
+export function docutilsXmlToDogsbayMd(xml, opts = {}) {
+    const doc = parseDocument(xml, { xmlMode: true });
+    const root = findElement(doc, "document");
+    const ledger = [];
+    if (!root)
+        return { markdown: "", ledger };
+    // Sphinx omits the `title=` attr on <document>; the H1 is the first
+    // section's <title>. Plain docutils sets `title=`.
+    const title = root.attribs?.title ?? firstSectionTitle(root);
+    const docPath = opts.docPath ?? "";
+    const docDir = docPath.includes("/") ? docPath.slice(0, docPath.lastIndexOf("/")) : "";
+    // Plain docutils puts the H1 in `<document title><title>…`; start at
+    // depth 1. Sphinx wraps the whole doc in a top `<section>` whose title
+    // is the H1, so start at 0 and let that section bump it to 1.
+    const ctx = {
+        ledger,
+        depth: root.attribs?.title ? 1 : 0,
+        docDir,
+        hrefPrefix: opts.hrefPrefix ?? "",
+    };
+    // The root `<document>`'s own `<title>` is the H1; its remaining children
+    // are the body. Section titles below get depth+1.
+    const blocks = renderBlocks(elementChildren(root), ctx);
+    const md = blocks
+        .filter((b) => b.trim() !== "")
+        .join("\n\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+    return { markdown: md + "\n", title, ledger };
+}
+// ── Block level ────────────────────────────────────────────────────────────
+function renderBlocks(nodes, ctx) {
+    const out = [];
+    for (const n of nodes) {
+        if (!isTag(n))
+            continue; // whitespace text between blocks — ignore
+        const s = renderBlock(n, ctx);
+        if (s != null)
+            out.push(s);
+    }
+    return out;
+}
+function renderBlock(el, ctx) {
+    const tag = el.tagName;
+    switch (tag) {
+        case "title":
+            return `${"#".repeat(Math.min(ctx.depth, 6))} ${renderInline(kids(el), ctx).trim()}`;
+        case "section": {
+            const child = { ...ctx, depth: ctx.depth + 1 };
+            return renderBlocks(elementChildren(el), child).join("\n\n");
+        }
+        case "paragraph":
+            return renderInline(kids(el), ctx).trim();
+        case "note":
+        case "tip":
+        case "hint":
+        case "important":
+        case "warning":
+        case "caution":
+        case "danger":
+        case "attention":
+        case "error":
+            return renderAdmonition(ADMONITION_TO_CALLOUT[tag], el, ctx);
+        case "admonition":
+            return renderGenericAdmonition(el, ctx);
+        case "seealso":
+            return renderAdmonition("note", el, ctx, "See also");
+        case "literal_block":
+            return renderCodeBlock(el);
+        case "math_block": {
+            // `.. math::` display equation → `$$…$$` block (KaTeX). Was dropped.
+            const tex = textContent(el).trim();
+            return tex ? `$$\n${tex}\n$$` : null;
+        }
+        case "line_block":
+            // rST line block — significant line breaks; join with hard breaks.
+            return elementChildren(el)
+                .filter((c) => c.tagName === "line")
+                .map((line) => renderInline(kids(line), ctx).trim())
+                .join("\\\n");
+        case "container":
+            return renderContainer(el, ctx);
+        case "compound":
+            // Sphinx toctree renders as a <compound toctree-wrapper> in the body;
+            // it's navigation (extracted separately by loaders/sphinx.ts), not
+            // page content — drop it here. Other compounds render their blocks.
+            if ((el.attribs?.classes ?? "").includes("toctree-wrapper"))
+                return null;
+            return renderBlocks(elementChildren(el), ctx).join("\n\n");
+        case "bullet_list":
+            return renderList(el, ctx, false);
+        case "enumerated_list":
+            return renderList(el, ctx, true);
+        case "definition_list":
+            return renderDefinitionList(el, ctx);
+        case "field_list":
+            return renderFieldList(el, ctx);
+        case "block_quote":
+            return renderBlockQuote(el, ctx);
+        case "image":
+            return renderImage(el);
+        case "figure":
+            return renderFigure(el, ctx);
+        case "table":
+            return renderTable(el, ctx);
+        case "transition":
+            return "---";
+        case "doctest_block":
+            // `>>> …` interactive blocks → a python fence (preserving prompts).
+            return renderDoctest(el);
+        case "versionmodified":
+            // `.. versionadded::` / `.. versionchanged::` / `.. deprecated::`.
+            // Render INLINE (the paragraph already carries an "Added in version
+            // X:" prefix inline span), not as a callout box — the fidelity review
+            // showed 55 note-boxes on one API page is far heavier than the live
+            // docs, which inline these. renderInlineEl italicises the prefix.
+            return renderBlocks(elementChildren(el), ctx).join("\n\n").trim() || null;
+        case "desc":
+            return renderDesc(el, ctx);
+        case "index":
+            // Invisible index marker (`.. index::` / autodoc index entries) —
+            // no rendered content, so drop silently (not a loss to ledger).
+            return null;
+        case "target":
+        case "substitution_definition":
+        case "comment":
+            // Link targets are already inlined into references' refuri;
+            // substitutions already resolved; comments dropped.
+            return null;
+        case "system_message":
+            ctx.ledger.push({
+                construct: `system_message: ${firstParagraphText(el)}`,
+                note: "docutils diagnostic (often a Sphinx-only directive/role) — dropped; re-run in Sphinx mode",
+            });
+            return null;
+        case "literal": // stray block-level literal
+            return renderInline([el], ctx).trim();
+        default:
+            ctx.ledger.push({ construct: `<${tag}>`, note: "unmapped docutils node — dropped" });
+            return null;
+    }
+}
+function renderAdmonition(name, el, ctx, title) {
+    const inner = renderBlocks(elementChildren(el), ctx).join("\n\n").trim();
+    const attrs = title ? `{title="${title}"}` : "";
+    const fence = ":".repeat(3 + colonDepth(inner));
+    return `${fence}${name}${attrs}\n${inner}\n${fence}`;
+}
+function renderGenericAdmonition(el, ctx) {
+    // `.. admonition:: Custom title` → first <title> child is the title.
+    const titleEl = elementChildren(el).find((c) => c.tagName === "title");
+    const title = titleEl ? renderInline(kids(titleEl), ctx).trim() : undefined;
+    const body = elementChildren(el).filter((c) => c.tagName !== "title");
+    const inner = renderBlocks(body, ctx).join("\n\n").trim();
+    const attrs = title ? `{title="${escapeAttr(title)}"}` : "";
+    const fence = ":".repeat(3 + colonDepth(inner));
+    return `${fence}note${attrs}\n${inner}\n${fence}`;
+}
+function renderCodeBlock(el, title) {
+    // literal_block text may be split across highlight <inline> spans — take
+    // the full text content. Language: `language=` attr (Sphinx) or
+    // `classes="code <lang>"` (plain docutils).
+    const classes = (el.attribs?.classes ?? "").split(/\s+/);
+    const lang = el.attribs?.language ?? classes.find((c) => c && c !== "code") ?? "";
+    const code = textContent(el).replace(/\n$/, "");
+    const fence = pickCodeFence(code);
+    const info = title ? `${lang} title="${escapeAttr(title)}"` : lang;
+    return `${fence}${info}\n${code}\n${fence}`;
+}
+/**
+ * `<container>` — Sphinx wraps a captioned code block in a
+ * `literal-block-wrapper` container (`.. code-block:: … :caption:`).
+ * Extract the caption → code-fence title. Other containers render their
+ * blocks inline.
+ */
+function renderContainer(el, ctx) {
+    const classes = el.attribs?.classes ?? "";
+    if (classes.includes("literal-block-wrapper") || el.attribs?.literal_block === "1") {
+        const lit = descendant(el, "literal_block");
+        const capEl = elementChildren(el).find((c) => c.tagName === "caption");
+        const caption = capEl ? renderInline(kids(capEl), ctx).trim() : undefined;
+        return lit ? renderCodeBlock(lit, caption) : null;
+    }
+    const inner = renderBlocks(elementChildren(el), ctx).join("\n\n").trim();
+    return inner || null;
+}
+function renderDoctest(el) {
+    const code = textContent(el).replace(/\n$/, "");
+    const fence = pickCodeFence(code);
+    return `${fence}python\n${code}\n${fence}`;
+}
+/** Sphinx desctype/objtype → (dogsbay directive, ApiSymbol `kind`). */
+function apiKind(objtype) {
+    switch (objtype) {
+        case "class":
+            return { dir: "api-class", kind: "class" };
+        case "exception":
+            return { dir: "api-class", kind: "class" };
+        case "module":
+            return { dir: "api-class", kind: "module" };
+        case "method":
+        case "classmethod":
+        case "staticmethod":
+            return { dir: "api-member", kind: "meth" };
+        case "function":
+            return { dir: "api-member", kind: "func" };
+        case "attribute":
+        case "property":
+        case "data":
+            return { dir: "api-member", kind: "attr" };
+        default:
+            return { dir: "api-member", kind: objtype || "func" };
+    }
+}
+/**
+ * `<desc>` — a Sphinx domain description (autodoc: a function / class /
+ * method signature + docstring). Emit a `:::api-class` / `:::api-member`
+ * component — the SAME vocabulary autodoc-python produces for the mkdocs
+ * path — instead of a markdown heading.
+ *
+ * Why not a heading: the fidelity review vs the live tornado docs showed
+ * 100+ API signatures rendered as `<h3>/<h4>` flood the on-page TOC (141
+ * headings vs the site's 11). `ApiSymbol` renders the signature at an
+ * h2/h3 in HTML but is NOT a `heading` TreeNode, so it stays out of the
+ * TOC — and gets the proper API styling. An explicit `<a id>` preserves
+ * the cross-ref target (`:meth:` → `#fullname`) that ApiSymbol doesn't emit.
+ *
+ * See plans/format-rst.md Phase 4.
+ */
+/**
+ * Serialize a `<desc_parameterlist>` to `a, b, c`, preserving OPTIONAL
+ * groups: `<desc_optional>` wraps optional params, rendered bracketed as
+ * `a[, b]` (Sphinx convention). Recurses for nested optionals
+ * (`a[, b[, c]]`). Reading only direct `<desc_parameter>` children — the
+ * old behaviour — silently dropped every optional param.
+ */
+function serializeParams(plist) {
+    let s = "";
+    for (const c of elementChildren(plist)) {
+        if (c.tagName === "desc_parameter") {
+            const t = textContent(c).replace(/\s+/g, " ").trim();
+            s += s ? `, ${t}` : t;
+        }
+        else if (c.tagName === "desc_optional") {
+            const inner = serializeParams(c);
+            s += s ? `[, ${inner}]` : `[${inner}]`;
+        }
+    }
+    return s;
+}
+function renderDesc(el, ctx) {
+    // A `<desc>` can carry MORE THAN ONE `<desc_signature>` — overloaded
+    // functions (`@typing.overload`, C++ overloads) list each form. Render
+    // them all: every signature keeps its cross-ref anchor, and the signature
+    // strings are stacked in the one ApiSymbol (which renders them in a code
+    // block). Taking only the first would silently drop overloads.
+    const sigs = elementChildren(el).filter((c) => c.tagName === "desc_signature");
+    if (sigs.length === 0) {
+        // No signature — just render the content.
+        const c = elementChildren(el).find((x) => x.tagName === "desc_content");
+        return c ? renderBlocks(elementChildren(c), ctx).join("\n\n").trim() : "";
+    }
+    const signatureText = (sig) => {
+        const addname = textOfChild(sig, "desc_addname");
+        const shortName = textOfChild(sig, "desc_name");
+        const plist = elementChildren(sig).find((c) => c.tagName === "desc_parameterlist");
+        const params = plist ? serializeParams(plist) : "";
+        const full = `${addname}${shortName}`.trim();
+        return { full, sig: `${full}${plist ? `(${params})` : ""}`.trim() };
+    };
+    const parsed = sigs.map(signatureText);
+    const fullName = parsed.find((p) => p.full)?.full ?? "";
+    const shortName = textOfChild(sigs[0], "desc_name");
+    const signature = parsed.map((p) => p.sig).filter(Boolean).join("\n");
+    const { dir, kind } = apiKind(el.attribs?.objtype ?? el.attribs?.desctype ?? "");
+    // Body: one anchor per signature id (cross-ref targets), then the
+    // docstring. Nested `<desc>` (methods in a class) recurse into api-members.
+    const parts = [];
+    const seenIds = new Set();
+    for (const sig of sigs) {
+        const id = sig.attribs?.ids?.split(/\s+/)[0];
+        if (id && !seenIds.has(id)) {
+            seenIds.add(id);
+            parts.push(`<a id="${id}"></a>`);
+        }
+    }
+    const content = elementChildren(el).find((c) => c.tagName === "desc_content");
+    if (content) {
+        const inner = renderBlocks(elementChildren(content), ctx).join("\n\n").trim();
+        if (inner)
+            parts.push(inner);
+    }
+    const body = parts.join("\n\n");
+    const propsYaml = stringifyYaml({ name: fullName || shortName, kind, signature }).trimEnd();
+    // Fence longer than any ::: already in the body (nested api-members).
+    const fence = ":".repeat(3 + colonDepth(body));
+    return `${fence}${dir}\n---\n${propsYaml}\n---\n${body}\n${fence}`;
+}
+function textOfChild(el, tag) {
+    const c = elementChildren(el).find((x) => x.tagName === tag);
+    return c ? textContent(c) : "";
+}
+function firstSectionTitle(root) {
+    const sec = elementChildren(root).find((c) => c.tagName === "section");
+    const titleEl = sec ? elementChildren(sec).find((c) => c.tagName === "title") : undefined;
+    return titleEl ? textContent(titleEl).trim() : undefined;
+}
+function renderList(el, ctx, ordered) {
+    const items = elementChildren(el).filter((c) => c.tagName === "list_item");
+    // Honour docutils' `start` attr so a list beginning at 5 isn't renumbered
+    // to 1 (review #6). markdown renders the first number and auto-increments.
+    const start = ordered ? parseInt(el.attribs?.start ?? "1", 10) || 1 : 1;
+    const lines = [];
+    items.forEach((item, i) => {
+        const marker = ordered ? `${start + i}.` : "-";
+        const blocks = renderBlocks(elementChildren(item), ctx);
+        const body = blocks.join("\n\n").trim();
+        const [first, ...rest] = body.split("\n");
+        const pad = " ".repeat(marker.length + 1);
+        lines.push(`${marker} ${first}`);
+        for (const r of rest)
+            lines.push(r ? pad + r : r);
+    });
+    return lines.join("\n");
+}
+function renderDefinitionList(el, ctx) {
+    const out = [];
+    for (const item of elementChildren(el).filter((c) => c.tagName === "definition_list_item")) {
+        const termEl = elementChildren(item).find((c) => c.tagName === "term");
+        const defEl = elementChildren(item).find((c) => c.tagName === "definition");
+        const term = termEl ? renderInline(kids(termEl), ctx).trim() : "";
+        const defBlocks = defEl ? renderBlocks(elementChildren(defEl), ctx) : [];
+        const def = defBlocks.join("\n\n").trim();
+        const [first, ...rest] = def.split("\n");
+        out.push(`${term}\n:   ${first}`);
+        for (const r of rest)
+            out.push(r ? "    " + r : r);
+    }
+    return out.join("\n\n");
+}
+function renderFieldList(el, ctx) {
+    // Field lists (`:name: value`) → a simple bold-term list. Rare in body
+    // prose (mostly bibliographic); keep it lossless-ish and readable.
+    const out = [];
+    for (const field of elementChildren(el).filter((c) => c.tagName === "field")) {
+        const nameEl = elementChildren(field).find((c) => c.tagName === "field_name");
+        const bodyEl = elementChildren(field).find((c) => c.tagName === "field_body");
+        const name = nameEl ? renderInline(kids(nameEl), ctx).trim() : "";
+        const body = bodyEl ? renderBlocks(elementChildren(bodyEl), ctx).join(" ").trim() : "";
+        out.push(`- **${name}:** ${body}`);
+    }
+    return out.join("\n");
+}
+function renderBlockQuote(el, ctx) {
+    const inner = renderBlocks(elementChildren(el), ctx).join("\n\n").trim();
+    return inner
+        .split("\n")
+        .map((l) => (l ? `> ${l}` : ">"))
+        .join("\n");
+}
+function renderImage(el) {
+    const uri = el.attribs?.uri ?? "";
+    const alt = el.attribs?.alt ?? "";
+    return `![${escapeAlt(alt)}](${uri})`;
+}
+function renderFigure(el, ctx) {
+    const img = elementChildren(el).find((c) => c.tagName === "image");
+    const capEl = elementChildren(el).find((c) => c.tagName === "caption");
+    const imgMd = img ? renderImage(img) : "";
+    const cap = capEl ? renderInline(kids(capEl), ctx).trim() : "";
+    return cap ? `${imgMd}\n\n_${cap}_` : imgMd;
+}
+// ── Tables ──────────────────────────────────────────────────────────────────
+function renderTable(el, ctx) {
+    const tgroup = descendant(el, "tgroup");
+    if (!tgroup)
+        return "";
+    const cols = parseInt(tgroup.attribs?.cols ?? "0", 10);
+    const thead = descendant(tgroup, "thead");
+    const tbody = descendant(tgroup, "tbody");
+    const headRows = thead ? rowsOf(thead) : [];
+    const bodyRows = tbody ? rowsOf(tbody) : [];
+    // A `.. list-table:: Caption` / grid-table caption is a `<title>` child of
+    // the `<table>` (before `<tgroup>`). It rides on the pipe table as a
+    // `{caption="…"}` attribute block (dogsbay-md reattaches it as a real
+    // `<caption>` on re-parse); an HTML-fallback table gets an inline
+    // `<caption>` element.
+    const titleEl = elementChildren(el).find((c) => c.tagName === "title");
+    const caption = titleEl ? renderInline(kids(titleEl), ctx).trim() : "";
+    const withPipeCaption = (table) => caption ? `${table}\n\n{caption="${captionAttr(caption)}"}` : table;
+    // Fall back to an HTML table when any cell spans columns/rows or holds
+    // block content a GFM pipe table can't represent.
+    const complex = [...headRows, ...bodyRows].some((r) => elementChildren(r)
+        .filter((c) => c.tagName === "entry")
+        .some((e) => e.attribs?.morecols || e.attribs?.morerows || isBlockCell(e)));
+    if (complex)
+        return renderHtmlTable(headRows, bodyRows, ctx, caption);
+    const headerCells = headRows.length
+        ? cellsText(headRows[0], ctx)
+        : new Array(cols).fill("");
+    const lines = [
+        `| ${headerCells.join(" | ")} |`,
+        `| ${headerCells.map(() => "---").join(" | ")} |`,
+    ];
+    for (const r of bodyRows)
+        lines.push(`| ${cellsText(r, ctx).join(" | ")} |`);
+    return withPipeCaption(lines.join("\n"));
+}
+/** Escape a caption for a `{caption="…"}` attribute value (quotes only). */
+function captionAttr(text) {
+    return text.replace(/"/g, "&quot;").replace(/\n+/g, " ").trim();
+}
+function renderHtmlTable(headRows, bodyRows, ctx, caption = "") {
+    const cell = (e, tag) => {
+        const span = e.attribs?.morecols ? ` colspan="${parseInt(e.attribs.morecols, 10) + 1}"` : "";
+        const rspan = e.attribs?.morerows ? ` rowspan="${parseInt(e.attribs.morerows, 10) + 1}"` : "";
+        const inner = renderBlocks(elementChildren(e), ctx).join(" ").trim();
+        return `<${tag}${span}${rspan}>${inner}</${tag}>`;
+    };
+    const row = (r, tag) => `<tr>${entriesOf(r).map((e) => cell(e, tag)).join("")}</tr>`;
+    const parts = ["<table>"];
+    if (caption)
+        parts.push(`<caption>${caption}</caption>`);
+    if (headRows.length)
+        parts.push("<thead>", ...headRows.map((r) => row(r, "th")), "</thead>");
+    parts.push("<tbody>", ...bodyRows.map((r) => row(r, "td")), "</tbody>", "</table>");
+    return parts.join("");
+}
+// ── Inline level ─────────────────────────────────────────────────────────────
+function renderInline(nodes, ctx) {
+    let out = "";
+    for (const n of nodes) {
+        if (isTextNode(n)) {
+            out += escapeText(textData(n));
+            continue;
+        }
+        if (!isTag(n))
+            continue;
+        out += renderInlineEl(n, ctx);
+    }
+    return out;
+}
+function renderInlineEl(el, ctx) {
+    const tag = el.tagName;
+    const inner = () => renderInline(kids(el), ctx);
+    switch (tag) {
+        case "emphasis":
+        case "title_reference":
+            return `*${inner()}*`;
+        case "strong":
+            return `**${inner()}**`;
+        case "literal":
+            return `\`${textContent(el)}\``;
+        case "reference": {
+            const raw = el.attribs?.refuri ?? (el.attribs?.refid ? `#${el.attribs.refid}` : "");
+            const uri = resolveRef(raw, el.attribs?.internal === "1", ctx);
+            const text = inner() || uri;
+            return uri ? `[${text}](${uri})` : text;
+        }
+        case "target":
+            return "";
+        case "footnote_reference":
+            return `[^${el.attribs?.refid ?? textContent(el)}]`;
+        case "substitution_reference":
+            return inner();
+        case "math":
+            return `$${textContent(el)}$`;
+        case "problematic": {
+            ctx.ledger.push({
+                construct: textContent(el),
+                note: "Sphinx-only role under plain docutils — emitted as text; resolves in Sphinx mode",
+            });
+            return textContent(el);
+        }
+        case "inline":
+            // The "Added in version X:" prefix span of a versionmodified note —
+            // italicise it so the inline version note still reads as a note.
+            if ((el.attribs?.classes ?? "").includes("versionmodified")) {
+                const t = inner().trim();
+                return t ? `*${t}* ` : "";
+            }
+            return inner();
+        case "generated":
+            return inner();
+        case "image":
+            return renderImage(el);
+        default:
+            return inner();
+    }
+}
+// ── DOM helpers ──────────────────────────────────────────────────────────────
+function elementChildren(el) {
+    const kids = [];
+    for (const c of el.children)
+        if (isTag(c))
+            kids.push(c);
+    return kids;
+}
+function findElement(doc, tag) {
+    for (const c of doc.children)
+        if (isTag(c) && c.tagName === tag)
+            return c;
+    return undefined;
+}
+function descendant(el, tag) {
+    for (const c of el.children) {
+        if (isTag(c)) {
+            if (c.tagName === tag)
+                return c;
+            const d = descendant(c, tag);
+            if (d)
+                return d;
+        }
+    }
+    return undefined;
+}
+function rowsOf(el) {
+    return elementChildren(el).filter((c) => c.tagName === "row");
+}
+function entriesOf(row) {
+    return elementChildren(row).filter((c) => c.tagName === "entry");
+}
+function cellsText(row, ctx) {
+    return entriesOf(row).map((e) => {
+        // Single-paragraph cells → inline text; anything richer is flagged as
+        // complex upstream (renderHtmlTable), so here we join paragraphs.
+        const paras = elementChildren(e).filter((c) => c.tagName === "paragraph");
+        // `|` is already escaped by escapeText, so no extra pipe-escaping here.
+        return paras.map((p) => renderInline(kids(p), ctx).trim()).join(" ");
+    });
+}
+function isBlockCell(e) {
+    const kids = elementChildren(e);
+    if (kids.length > 1)
+        return true;
+    return kids.some((c) => c.tagName !== "paragraph");
+}
+function textContent(el) {
+    let s = "";
+    for (const c of el.children) {
+        if (isTextNode(c))
+            s += textData(c);
+        else if (isTag(c))
+            s += textContent(c);
+    }
+    return s;
+}
+function firstParagraphText(el) {
+    const p = descendant(el, "paragraph");
+    return p ? textContent(p).slice(0, 80) : "";
+}
+/**
+ * Resolve a docutils/Sphinx `<reference>` target to a Dogsbay href.
+ *
+ * Sphinx internal `:doc:`/`:ref:` refuris are doc-relative (`advanced/setup`,
+ * `intro#a-section`) — resolve them against the current doc's directory into
+ * a root-relative slug so links work under Dogsbay's directory-style URLs
+ * (same problem the AsciiDoc/Antora xref resolver solves). External URLs and
+ * pure `#anchor` refs pass through unchanged.
+ */
+function resolveRef(raw, internal, ctx) {
+    if (!raw)
+        return "";
+    if (raw[0] === "#")
+        return raw; // in-page anchor
+    if (/^[a-z][a-z0-9+.-]*:/i.test(raw) || raw.startsWith("//"))
+        return raw; // URL
+    if (!internal)
+        return raw;
+    // Strip a trailing .html Sphinx sometimes emits, split off #fragment.
+    const hashIdx = raw.indexOf("#");
+    let path = (hashIdx === -1 ? raw : raw.slice(0, hashIdx)).replace(/\.html$/i, "");
+    const frag = hashIdx === -1 ? "" : raw.slice(hashIdx);
+    if (!path)
+        return frag; // same-page ref
+    // Absolute docname (leading '/') is already root-relative.
+    const segs = path.startsWith("/") ? [] : ctx.docDir ? ctx.docDir.split("/") : [];
+    for (const part of path.replace(/^\//, "").split("/")) {
+        if (part === "" || part === ".")
+            continue;
+        if (part === "..")
+            segs.pop();
+        else
+            segs.push(part);
+    }
+    // Prefix with the site basePath so in-body links match the nav's hrefs.
+    const prefix = ctx.hrefPrefix.replace(/\/$/, "");
+    return `${prefix}/${segs.join("/")}${frag}`;
+}
+// ── Escaping / fences ────────────────────────────────────────────────────────
+function escapeText(s) {
+    // rST prose is reflowed — the source line breaks + continuation indents
+    // in a paragraph's text are NOT significant, so collapse whitespace runs
+    // (incl. newlines) to single spaces. Otherwise the 4+ leading spaces on
+    // wrapped source lines leak in and markdown reads them as indented code.
+    // (Code blocks use textContent, which preserves whitespace — unaffected.)
+    // Then neutralise markdown-active chars docutils text may contain:
+    // backslash, code/emphasis markers, link brackets, raw-HTML `<`, and the
+    // table pipe. (`<` escaping is safe — markdown renders `\<` as a literal
+    // `<`.) Leaving these unescaped let plain rST prose like `see <http://x>`
+    // or `item [1]` be reinterpreted as HTML / link syntax (review #10).
+    return s.replace(/\s+/g, " ").replace(/([\\`*_[\]<|])/g, "\\$1");
+}
+function escapeAttr(s) {
+    return s.replace(/"/g, "&quot;");
+}
+function escapeAlt(s) {
+    return s.replace(/([\]\\])/g, "\\$1");
+}
+/** Longest run of `:` in a line-start `:::…` fence within text (for nesting). */
+function colonDepth(text) {
+    let max = 0;
+    for (const line of text.split("\n")) {
+        const m = line.match(/^(:{3,})/);
+        if (m)
+            max = Math.max(max, m[1].length - 2);
+    }
+    return max;
+}
+function pickCodeFence(code) {
+    let longest = 0;
+    for (const m of code.matchAll(/^(`{3,})/gm))
+        longest = Math.max(longest, m[1].length);
+    return "`".repeat(Math.max(3, longest + 1));
+}
+//# sourceMappingURL=transform.js.map