UNPKG

open-agreements

Version:

Open-source legal template filling CLI and library

300 lines • 13.2 kB
// DOCX → Markdown serializer. // // This is a *serializer over the existing structured document model* — it does no OOXML // parsing. `DocxDocument.buildDocumentView({ showFormatting: true })` already yields a // `DocumentViewNode[]` carrying headings, list metadata, grid-aware table context, injected // `[^n]` footnote markers, and an HTML-shaped inline-tag string (`tagged_text`). This module // turns that model into GitHub-Flavored Markdown. // // Markdown is intentionally *lossy*: there is no round-trip guarantee. Constructs without a // Markdown equivalent (highlighting, font runs, merged/nested table cells, layout) are // downgraded as documented below rather than preserved. // // The inline tokenizer (`inlineTagsToMarkdown`) is the reusable core; the planned HTML // emitter (#304) renders the same tokens, so neither serializer reasons about the tag // grammar independently and drifts from the emitter in `formatting_tags.ts`. import { tokenizeToonInline } from './document_view.js'; import { LabelType } from './list_labels.js'; /** Footnote markers already injected into `tagged_text`, e.g. `[^1]`, `[^12]`. */ const FOOTNOTE_MARKER_RE = /\[\^\d+\]/g; /** * Backslash-escape the inline Markdown-significant characters that would otherwise be * interpreted mid-line. GFM honours backslash escapes for ASCII punctuation, so `\*` * renders a literal `*`. We escape only the characters that trigger *inline* constructs * (emphasis, code, links, raw HTML, table pipes); block-level triggers (`#`, `-`, `>`, …) * are handled per-line by {@link escapeLeadingBlockSyntax} so we don't litter prose with * `\.` and `\-` on every sentence. * * Already-present `[^n]` footnote markers are protected: escaping their `[`/`]`/`^` would * sever them from the appended `[^n]: …` definitions. */ function escapeInlineText(text) { const escapeSpan = (s) => s.replace(/[\\`*_[\]<|]/g, (c) => `\\${c}`); let out = ''; let lastIndex = 0; for (const match of text.matchAll(FOOTNOTE_MARKER_RE)) { const idx = match.index ?? 0; out += escapeSpan(text.slice(lastIndex, idx)); out += match[0]; // leave the footnote marker untouched lastIndex = idx + match[0].length; } out += escapeSpan(text.slice(lastIndex)); return out; } /** * Escape a leading block-level trigger so a normal paragraph whose visible text begins with * `#`, `>`, `-`, `+`, `* `, or `N.`/`N)` is not mis-read as a heading, quote, or list. * Block triggers always require a trailing space, whereas the emphasis we emit (`**`, `*`) * never does — so matching the space-terminated forms cannot corrupt generated Markdown. */ function escapeLeadingBlockSyntax(line) { return line.replace(/^(\s*)(#{1,6}(?= )|>(?= )|[-+*](?= )|\d+[.)](?= ))/, (_m, ws, trig) => { if (/^\d/.test(trig)) { // ordered-list trigger: escape the delimiter (the `.` or `)`), keep the digits return `${ws}${trig.slice(0, -1)}\\${trig.slice(-1)}`; } return `${ws}\\${trig[0]}${trig.slice(1)}`; }); } export function inlineTagsToMarkdown(text) { const ops = []; const linkUrls = []; // stack of open <a> hrefs (links don't nest meaningfully) for (const token of tokenizeToonInline(text)) { if (token.kind === 'text') { ops.push({ t: 'md', v: escapeInlineText(token.value) }); continue; } const tag = token.value; if (tag === '<b>') ops.push({ t: 'emph', kind: 'b', dir: 1 }); else if (tag === '</b>') ops.push({ t: 'emph', kind: 'b', dir: -1 }); else if (tag === '<i>') ops.push({ t: 'emph', kind: 'i', dir: 1 }); else if (tag === '</i>') ops.push({ t: 'emph', kind: 'i', dir: -1 }); else if (tag === '<u>' || tag === '</u>') ops.push({ t: 'md', v: tag }); // raw HTML passthrough else if (tag.startsWith('<a ')) { linkUrls.push(/href="([^"]*)"/.exec(tag)?.[1] ?? ''); ops.push({ t: 'md', v: '[' }); } else if (tag === '</a>') { ops.push({ t: 'md', v: `](${linkUrls.pop() ?? ''})` }); } // <highlight>, </highlight>, <font …>, </font> → strip (emit nothing, keep inner text) } // Defensive: an unbalanced <a> (no closing tag) would leave a dangling "["; close it. while (linkUrls.length > 0) { ops.push({ t: 'md', v: `](${linkUrls.pop()})` }); } // Emit emphasis delimiters only where the *active* emphasis state actually changes // between two text spans. Word splits a single formatted phrase into many runs, so // `tagged_text` carries boundary noise: `</b></i><b><i>` (state unchanged across the // boundary), interleaved different-kind toggles `</b></i><i><b>`, or empty `<b></b>` // pairs. Mapping each toggle naively yields runs like `******` / `****` that render as // literal asterisks. Tracking the state and reconciling on a stack collapses all of that // to the minimal delimiters while keeping nesting well-formed (`**a*b*c**`). const DELIM = { b: '**', i: '*' }; let out = ''; const activeStack = []; // emphasis kinds currently open, in open order const desired = new Set(); // running target state as we scan emph ops const reconcile = () => { // Close from the top until every still-open kind is wanted, remembering any wanted // kinds we had to close (because they sat above an unwanted one) so we can reopen them. const reopen = []; while (activeStack.length > 0 && !activeStack.every((k) => desired.has(k))) { const k = activeStack.pop(); out += DELIM[k]; if (desired.has(k)) reopen.push(k); } // Open the kinds that are wanted but not currently open: the reopened ones first (in // their original open order), then any brand-new kinds in a stable order (b before i). const active = new Set(activeStack); const toOpen = [...reopen.reverse(), ...['b', 'i'].filter((k) => desired.has(k))]; for (const k of toOpen) { if (active.has(k)) continue; active.add(k); activeStack.push(k); out += DELIM[k]; } }; for (const op of ops) { if (op.t === 'emph') { if (op.dir === 1) desired.add(op.kind); else desired.delete(op.kind); continue; } reconcile(); // realize pending state changes before emitting literal text/Markdown out += op.v; } desired.clear(); reconcile(); // close any still-open emphasis at end of string return out; } /** A heading is structural (gets `#`) only when Word's style told us so and gave a level. */ function isStructuralHeading(node) { return node.heading?.source === 'word_style' && typeof node.heading.level === 'number'; } function renderListItem(node) { const lm = node.list_metadata; const level = Math.max(0, lm.list_level); const indent = ' '.repeat(level); const text = inlineTagsToMarkdown(node.tagged_text).trim(); const label = lm.label_string?.trim() ?? ''; // True auto-numbered numeric lists render as a Markdown ordered list (let the renderer // number them). Everything else preserves the *literal* label — legal documents carry // meaningful labels like `Section 2.1`, `Article IV`, `(a)`, `(i)` that a bare `1.` would // silently destroy. if (lm.label_type === LabelType.NUMBER && lm.is_auto_numbered) { return `${indent}1. ${text}`.trimEnd(); } if (label) { return `${indent}- ${label} ${text}`.trimEnd(); } return `${indent}- ${text}`.trimEnd(); } /** * Render a run of nodes that share a `table_context.table_id` as a GFM table. * * Lossy by design (GFM has no merged/nested-cell support): * - Horizontally merged cells (`gridSpan`) advance `col_index`, leaving grid gaps that we * fill with empty cells so the column count stays consistent and viewers don't break. * - Vertically merged cells (`vMerge`) and nested tables are flattened into the body-level * grid; multi-paragraph cells are joined with `<br>`. */ function renderTable(group) { let totalCols = 0; for (const n of group) { const tc = n.table_context; if (!tc) continue; totalCols = Math.max(totalCols, tc.total_cols, tc.col_index + 1); } if (totalCols <= 0) return []; const rows = new Map(); const rowOrder = []; const headerRows = new Set(); for (const n of group) { const tc = n.table_context; if (!tc) continue; if (!rows.has(tc.row_index)) { rows.set(tc.row_index, new Map()); rowOrder.push(tc.row_index); } const cellMap = rows.get(tc.row_index); // A raw newline inside a cell (from a line break) would split the GFM table row and // break the whole table, so collapse intra-cell newlines to `<br>`. const cellText = inlineTagsToMarkdown(n.tagged_text).replace(/\s*\n+\s*/g, '<br>').trim(); const parts = cellMap.get(tc.col_index) ?? []; if (cellText) parts.push(cellText); cellMap.set(tc.col_index, parts); if (tc.is_header_row) headerRows.add(tc.row_index); } rowOrder.sort((a, b) => a - b); if (rowOrder.length === 0) return []; const cellsFor = (rowIndex) => { const cellMap = rows.get(rowIndex) ?? new Map(); const cells = []; for (let c = 0; c < totalCols; c++) { cells.push((cellMap.get(c) ?? []).join('<br>')); } return cells; }; // GFM requires exactly one header row. Prefer the first row Word flagged as a header; // otherwise treat the first row as the header (the common case). const headerRowIndex = rowOrder.find((ri) => headerRows.has(ri)) ?? rowOrder[0]; const lines = []; lines.push(`| ${cellsFor(headerRowIndex).join(' | ')} |`); lines.push(`| ${Array.from({ length: totalCols }, () => '---').join(' | ')} |`); for (const ri of rowOrder) { if (ri === headerRowIndex) continue; lines.push(`| ${cellsFor(ri).join(' | ')} |`); } return lines; } /** * Serialize a structured document view to GitHub-Flavored Markdown. * * @param nodes Block nodes from `buildDocumentView({ showFormatting: true }).nodes`. * @param footnotes Footnotes from `DocxDocument.getFootnotes()` (already sorted by * `displayNumber`); appended as `[^n]: …` definitions. */ export function serializeToMarkdown(nodes, footnotes = [], _opts = {}) { const blocks = []; let inList = false; const closeList = () => { if (inList) { blocks.push(''); inList = false; } }; for (let i = 0; i < nodes.length; i++) { const node = nodes[i]; // ── Tables: consume the whole run of same-table_id nodes at once ── if (node.table_context) { closeList(); const tableId = node.table_context.table_id; const group = []; while (i < nodes.length && nodes[i].table_context?.table_id === tableId) { group.push(nodes[i]); i++; } i--; // for-loop will re-increment const tableLines = renderTable(group); if (tableLines.length > 0) { blocks.push(tableLines.join('\n')); blocks.push(''); } continue; } // ── Structural (Word-styled) headings ── if (isStructuralHeading(node)) { closeList(); const level = Math.min(6, Math.max(1, node.heading.level)); const text = inlineTagsToMarkdown(node.tagged_text).trim(); blocks.push(`${'#'.repeat(level)} ${text}`.trimEnd()); blocks.push(''); continue; } // ── List items ── if (node.list_metadata.list_level >= 0) { inList = true; blocks.push(renderListItem(node)); continue; } // ── Normal paragraphs (heuristic headings land here: their run-in bold already lives // in the inline tags, so we keep them as paragraphs rather than inventing a `#`). ── closeList(); const text = escapeLeadingBlockSyntax(inlineTagsToMarkdown(node.tagged_text)); if (text.trim() === '') { blocks.push(''); } else { blocks.push(text); blocks.push(''); } } closeList(); // ── Footnote definitions ── const defs = footnotes.filter((fn) => fn.displayNumber > 0); if (defs.length > 0) { blocks.push(''); for (const fn of defs) { const body = escapeInlineText(fn.text.replace(/\s+/g, ' ').trim()); blocks.push(`[^${fn.displayNumber}]: ${body}`); } } return `${blocks.join('\n').replace(/\n{3,}/g, '\n\n').trim()}\n`; } //# sourceMappingURL=serialize_markdown.js.map