@tabnas/markdown 0.4.2 → 0.5.1

package/src/ast.ts

@@ -0,0 +1,406 @@
+/* Copyright (c) 2021-2026 Richard Rodger, MIT License */
+
+// Projection from the native CommonMark tree (node.ts) to the mdast-adjacent
+// JSON AST that `@tabnas/markdown` has always returned.
+//
+// The native tree is what the HTML renderer walks, and it carries things the
+// public AST has no room for (source positions, the block/inline distinction
+// for raw HTML, container open/closed state). This module is the one place
+// that decides what survives the crossing. Two deliberate choices:
+//
+//   * Soft breaks collapse into a single space inside the surrounding text
+//     run, which is the long-standing documented behaviour of this package
+//     (`breaks:true` promotes them to `break` nodes instead). The native tree
+//     keeps them as real `softbreak` nodes, so an HTML render is unaffected.
+//   * `spread` now follows mdast semantics — a list is spread when it is
+//     loose, an item when it holds blank-line-separated blocks. The previous
+//     implementation latched this off the file's trailing newline, so the
+//     field carried no information; nothing can have depended on it.
+
+import { MdNode } from './node.ts'
+import type { TableAlign } from './node.ts'
+import type { ParserOptions } from './options.ts'
+
+export type DocumentNode = { type: 'document'; children: Block[] }
+
+export type Block =
+  | HeadingNode
+  | ParagraphNode
+  | BlockquoteNode
+  | ListNode
+  | ListItemNode
+  | CodeNode
+  | HtmlNode
+  | ThematicBreakNode
+  | TableNode
+
+export type HeadingNode = {
+  type: 'heading'
+  depth: 1 | 2 | 3 | 4 | 5 | 6
+  children: Inline[]
+}
+export type ParagraphNode = { type: 'paragraph'; children: Inline[] }
+export type BlockquoteNode = { type: 'blockquote'; children: Block[] }
+export type ListNode = {
+  type: 'list'
+  ordered: boolean
+  start: number | null
+  spread: boolean
+  children: ListItemNode[]
+}
+export type ListItemNode = {
+  type: 'listItem'
+  spread: boolean
+  /**
+   * mdast's task list field: `true`/`false` for a GFM task list item
+   * (`- [x] foo`), `null` for an ordinary item — and therefore `null`
+   * everywhere when `gfm` is off.
+   */
+  checked: boolean | null
+  children: Block[]
+}
+export type CodeNode = {
+  type: 'code'
+  lang: string | null
+  meta: string | null
+  value: string
+}
+export type HtmlNode = { type: 'html'; value: string }
+export type ThematicBreakNode = { type: 'thematicBreak' }
+
+/**
+ * A GFM table, in mdast's shape.
+ *
+ * `align` has one entry per column — `null` where the delimiter row gave no
+ * colon — and every row has exactly that many cells, since the block phase
+ * pads short rows and truncates long ones.
+ *
+ * mdast has no header flag: the **first** row is the header row, by
+ * convention, and this projection preserves that ordering from the tree.
+ */
+export type TableNode = {
+  type: 'table'
+  align: TableAlign[]
+  children: TableRowNode[]
+}
+export type TableRowNode = { type: 'tableRow'; children: TableCellNode[] }
+export type TableCellNode = { type: 'tableCell'; children: Inline[] }
+
+export type Inline =
+  | TextNode
+  | EmphasisNode
+  | StrongNode
+  | InlineCodeNode
+  | LinkNode
+  | ImageNode
+  | BreakNode
+  | DeleteNode
+  | HtmlNode
+
+export type TextNode = { type: 'text'; value: string }
+export type EmphasisNode = { type: 'emphasis'; children: Inline[] }
+export type StrongNode = { type: 'strong'; children: Inline[] }
+export type InlineCodeNode = { type: 'inlineCode'; value: string }
+export type LinkNode = {
+  type: 'link'
+  url: string
+  title: string | null
+  children: Inline[]
+}
+export type ImageNode = {
+  type: 'image'
+  url: string
+  title: string | null
+  alt: string
+}
+export type BreakNode = { type: 'break' }
+export type DeleteNode = { type: 'delete'; children: Inline[] }
+
+/** Plain-text flattening of an image's inline children, for `alt`. */
+function collectAltText(node: MdNode): string {
+  let out = ''
+  let child = node.firstChild
+  while (child) {
+    if ('text' === child.type || 'code' === child.type || 'html_inline' === child.type) {
+      out += child.literal ?? ''
+    } else if ('softbreak' === child.type || 'linebreak' === child.type) {
+      out += '\n'
+    } else {
+      out += collectAltText(child)
+    }
+    child = child.next
+  }
+  return out
+}
+
+/**
+ * mdast semantics: an item is spread when two of its children are separated by
+ * a *blank line* — not merely when it has more than one child. `- a\n  - b`
+ * holds a paragraph and a nested list with no blank line between them, and is
+ * not spread; `- a\n\n  - b` is.
+ *
+ * Derived from the block parser's `sourcepos` rather than tracked separately:
+ * consecutive children whose line ranges are not adjacent must have had a
+ * blank line between them.
+ */
+function itemIsSpread(item: MdNode): boolean {
+  let child = item.firstChild
+  while (child && child.next) {
+    const endLine = child.sourcepos[1][0]
+    const nextStartLine = child.next.sourcepos[0][0]
+    if (nextStartLine > endLine + 1) return true
+    child = child.next
+  }
+  return false
+}
+
+function inlineChildren(node: MdNode, opts: ParserOptions): Inline[] {
+  const out: Inline[] = []
+
+  const pushText = (value: string) => {
+    if ('' === value) return
+    const last = out[out.length - 1]
+    if (last && 'text' === last.type) last.value += value
+    else out.push({ type: 'text', value })
+  }
+
+  let child = node.firstChild
+  while (child) {
+    switch (child.type) {
+      case 'text':
+        pushText(child.literal ?? '')
+        break
+
+      case 'softbreak':
+        // Documented behaviour: a soft break reads as a space in the AST.
+        if (opts.breaks) out.push({ type: 'break' })
+        else pushText(' ')
+        break
+
+      case 'linebreak':
+        out.push({ type: 'break' })
+        break
+
+      case 'code':
+        out.push({ type: 'inlineCode', value: child.literal ?? '' })
+        break
+
+      case 'html_inline':
+        out.push({ type: 'html', value: child.literal ?? '' })
+        break
+
+      case 'emph':
+        out.push({ type: 'emphasis', children: inlineChildren(child, opts) })
+        break
+
+      case 'strong':
+        out.push({ type: 'strong', children: inlineChildren(child, opts) })
+        break
+
+      case 'del':
+        out.push({ type: 'delete', children: inlineChildren(child, opts) })
+        break
+
+      case 'link':
+        out.push({
+          type: 'link',
+          url: child.destination ?? '',
+          title: child.title ?? null,
+          children: inlineChildren(child, opts),
+        })
+        break
+
+      case 'image':
+        out.push({
+          type: 'image',
+          url: child.destination ?? '',
+          title: child.title ?? null,
+          alt: collectAltText(child),
+        })
+        break
+
+      default:
+        // A block node cannot appear here in a well-formed tree; skipping is
+        // safer than emitting a node the published types do not allow.
+        break
+    }
+    child = child.next
+  }
+
+  return out
+}
+
+/** Containers whose children are blocks rather than inlines. */
+const BLOCK_CONTAINERS: Record<string, true> = {
+  document: true,
+  block_quote: true,
+  list: true,
+  item: true,
+}
+
+/**
+ * Project a container's block children.
+ *
+ * Iterative rather than recursive, because the recursion depth here is the
+ * document's container nesting depth, which untrusted input controls directly:
+ * `'> '.repeat(4000)` is 8 KB of Markdown that the block parser and the HTML
+ * renderer both handle, but that overflowed the stack in this projection —
+ * crashing the package's primary API on input the rest of the pipeline
+ * survives.
+ *
+ * Two passes. The first walks the block tree with an explicit stack, recording
+ * nodes in an order where every parent precedes its descendants. Building in
+ * reverse then guarantees a node's children are already built when it is
+ * reached, so `buildBlock` can look them up instead of recursing.
+ *
+ * The Go port keeps the recursive form: goroutine stacks grow on demand and it
+ * projects 100k-deep nesting without trouble, so the same defect does not
+ * arise there.
+ */
+function blockChildren(node: MdNode, opts: ParserOptions): Block[] {
+  const order: MdNode[] = []
+  const stack: MdNode[] = []
+
+  for (let c = node.lastChild; c; c = c.prev) stack.push(c)
+  while (0 < stack.length) {
+    const n = stack.pop() as MdNode
+    order.push(n)
+    if (true === BLOCK_CONTAINERS[n.type]) {
+      for (let c = n.lastChild; c; c = c.prev) stack.push(c)
+    }
+  }
+
+  const built = new Map<MdNode, Block>()
+  for (let i = order.length - 1; 0 <= i; i--) {
+    const n = order[i]
+    const block = buildBlock(n, opts, built)
+    if (null !== block) built.set(n, block)
+  }
+
+  const out: Block[] = []
+  for (let c = node.firstChild; c; c = c.next) {
+    const b = built.get(c)
+    if (undefined !== b) out.push(b)
+  }
+  return out
+}
+
+/** Children of `n` that have already been built, in source order. */
+function builtChildren(n: MdNode, built: Map<MdNode, Block>): Block[] {
+  const out: Block[] = []
+  for (let c = n.firstChild; c; c = c.next) {
+    const b = built.get(c)
+    if (undefined !== b) out.push(b)
+  }
+  return out
+}
+
+function buildBlock(
+  node: MdNode,
+  opts: ParserOptions,
+  built: Map<MdNode, Block>,
+): Block | null {
+  switch (node.type) {
+    case 'paragraph':
+      return { type: 'paragraph', children: inlineChildren(node, opts) }
+
+    case 'heading':
+      return {
+        type: 'heading',
+        depth: node.level as HeadingNode['depth'],
+        children: inlineChildren(node, opts),
+      }
+
+    case 'thematic_break':
+      return { type: 'thematicBreak' }
+
+    case 'block_quote':
+      return { type: 'blockquote', children: builtChildren(node, built) }
+
+    case 'code_block': {
+      const info = (node.info ?? '').trim()
+      let lang: string | null = null
+      let meta: string | null = null
+      if ('' !== info) {
+        const sp = info.search(/\s/)
+        if (-1 === sp) {
+          lang = info
+        } else {
+          lang = info.slice(0, sp)
+          meta = info.slice(sp + 1).trim() || null
+        }
+      }
+      // The native tree keeps the trailing newline because the spec's HTML
+      // for `<pre><code>` includes it; mdast's `code.value` does not. Strip
+      // exactly one, not all, so a block that genuinely ends in a blank line
+      // keeps it.
+      const raw = node.literal ?? ''
+      const value = raw.endsWith('\n') ? raw.slice(0, -1) : raw
+      return { type: 'code', lang, meta, value }
+    }
+
+    case 'html_block':
+      return { type: 'html', value: node.literal ?? '' }
+
+    case 'table': {
+      // Built here rather than through `built`, because a table's children are
+      // rows and cells rather than blocks — `blockChildren` never descends
+      // into one. The nesting is a fixed three levels deep, so unlike the
+      // block containers this cannot be driven past the stack by input.
+      const rows: TableRowNode[] = []
+      for (let row = node.firstChild; row; row = row.next) {
+        if ('table_row' !== row.type) continue
+        const cells: TableCellNode[] = []
+        for (let cell = row.firstChild; cell; cell = cell.next) {
+          if ('table_cell' !== cell.type) continue
+          cells.push({ type: 'tableCell', children: inlineChildren(cell, opts) })
+        }
+        rows.push({ type: 'tableRow', children: cells })
+      }
+      return { type: 'table', align: node.tableAlign ?? [], children: rows }
+    }
+
+    case 'list': {
+      const data = node.listData
+      const ordered = 'ordered' === data?.type
+      const items: ListItemNode[] = []
+      let child = node.firstChild
+      while (child) {
+        if ('item' === child.type) {
+          items.push({
+            type: 'listItem',
+            spread: itemIsSpread(child),
+            checked: child.checked,
+            children: builtChildren(child, built),
+          })
+        }
+        child = child.next
+      }
+      return {
+        type: 'list',
+        ordered,
+        start: ordered ? (data?.start ?? 1) : null,
+        spread: !(data?.tight ?? true),
+        children: items,
+      }
+    }
+
+    case 'item':
+      // Only reachable if an item is somehow detached from its list; a list
+      // builds its own items above.
+      return {
+        type: 'listItem',
+        spread: itemIsSpread(node),
+        checked: node.checked,
+        children: builtChildren(node, built),
+      }
+
+    default:
+      return null
+  }
+}
+
+/** Project a parsed native tree into the public JSON AST. */
+export function toAst(doc: MdNode, opts: ParserOptions): DocumentNode {
+  return { type: 'document', children: blockChildren(doc, opts) }
+}