@asciidoctor/core 3.0.3 → 4.0.0-alpha.1

package/src/footnote.js

@@ -0,0 +1,28 @@
+export class Footnote {
+  constructor(index, id, text) {
+    this.index = index
+    this.id = id ?? null
+    this.text = text
+  }
+
+  /**
+   * @returns {number} the index of this footnote.
+   */
+  getIndex() {
+    return this.index
+  }
+
+  /**
+   * @returns {string|null} the id of this footnote, or null if not set.
+   */
+  getId() {
+    return this.id
+  }
+
+  /**
+   * @returns {string} the text of this footnote.
+   */
+  getText() {
+    return this.text
+  }
+}

package/src/helpers.js

@@ -0,0 +1,355 @@
+// ESM conversion of helpers.rb
+// Internal helper functions used by the Asciidoctor parser.
+//
+// Ruby-to-JavaScript notes:
+//   - require_library / require_open_uri have no JS equivalent and are omitted.
+//   - resolve_class / class_for_name are Ruby-specific and are omitted.
+//   - BOM detection uses the Unicode BOM codepoint U+FEFF instead of raw bytes,
+//     since JS strings are always UTF-16 and never carry an encoding tag.
+//   - File.basename / File.extname are reimplemented without the Node `path` module
+//     so this module works in browser (Opal) and Node environments alike.
+//   - mkdir_p delegates to Node's fs.mkdirSync with { recursive: true }.
+//   - String#succ (nextval) is implemented for the ASCII alphanumeric subset
+//     used by Asciidoctor list-numbering sequences.
+
+import { UriSniffRx } from './rx.js'
+
+// ── BOM ──────────────────────────────────────────────────────────────────────
+// Unicode byte-order mark (U+FEFF). In a JS string (already decoded to UTF-16)
+// this is the single character that corresponds to all three BOM byte patterns:
+//   UTF-8  BOM  0xEF 0xBB 0xBF → U+FEFF
+//   UTF-16 LE   0xFF 0xFE      → U+FEFF
+//   UTF-16 BE   0xFE 0xFF      → U+FEFF
+const BOM = ''
+
+/** Trim trailing ASCII whitespace only (not Unicode line separators U+2028/U+2029). */
+const rstrip = (line) => line.replace(/[ \t\r\n\f\v]+$/, '')
+
+/**
+ * Prepare the source data Array for parsing.
+ *
+ * Strips a leading BOM from the first element if present, then trims trailing
+ * whitespace (trimEnd = true) or only the trailing newline (trimEnd = false)
+ * from every line.
+ *
+ * @param {string[]} data - the source data Array to prepare (no null/undefined entries allowed)
+ * @param {boolean} [trimEnd=true] - whether to strip all trailing whitespace (true) or only \n (false)
+ * @returns {string[]} Array of prepared lines
+ */
+export function prepareSourceArray(data, trimEnd = true) {
+  if (!data.length) return []
+  if (data[0].startsWith(BOM)) data[0] = data[0].slice(1)
+  // Strip trailing \r to normalize Windows CRLF line endings (lines were split on \n, leaving \r).
+  return trimEnd
+    ? data.map(rstrip)
+    : data.map((line) => line.replace(/\r?\n$/, '').replace(/\r$/, ''))
+}
+
+/**
+ * Prepare the source data String for parsing.
+ *
+ * Strips a leading BOM if present, splits into an array, and trims trailing
+ * whitespace (trimEnd = true) or only the trailing newline (trimEnd = false)
+ * from every line.
+ *
+ * @param {string} data - the source data String to prepare
+ * @param {boolean} [trimEnd=true] - whether to strip all trailing whitespace (true) or only \n (false)
+ * @returns {string[]} Array of prepared lines
+ */
+export function prepareSourceString(data, trimEnd = true) {
+  if (!data) return []
+  if (data.startsWith(BOM)) data = data.slice(1)
+  // Normalize Windows CRLF to LF so that split('\n') does not leave trailing \r on each line.
+  if (data.includes('\r'))
+    data = data.replace(/\r\n/g, '\n').replace(/\r/g, '\n')
+  // Ruby's each_line does not produce an empty trailing element when the string
+  // ends with \n, but JS split('\n') does. Remove the trailing empty element
+  // to match Ruby behaviour.
+  if (data.endsWith('\n')) data = data.slice(0, -1)
+  const lines = data.split('\n')
+  return trimEnd ? lines.map(rstrip) : lines
+}
+
+/**
+ * Efficiently check whether the specified String resembles a URI.
+ *
+ * Uses UriSniffRx to check whether the String begins with a URI prefix (e.g.
+ * http://). No validation of the URI is performed.
+ *
+ * @param {string} str - the String to check
+ * @returns {boolean} true if the String resembles a URI, false otherwise
+ */
+export function isUriish(str) {
+  return str.includes(':') && UriSniffRx.test(str)
+}
+
+/**
+ * Encode a URI component String for safe inclusion in a URI.
+ *
+ * Encodes all characters that are not unreserved per RFC-3986. Specifically,
+ * encodeURIComponent leaves !, ', (, ), and * unencoded; this function encodes
+ * those as well so the result matches CGI.escapeURIComponent (Ruby ≥ 3.2) /
+ * CGI.escape + gsub('+', '%20').
+ *
+ * @param {string} str - the URI component String to encode
+ * @returns {string} the encoded String
+ */
+export function encodeUriComponent(str) {
+  return encodeURIComponent(str).replace(
+    /[!'()*]/g,
+    (m) => `%${m.charCodeAt(0).toString(16)}`
+  )
+}
+
+/**
+ * Replace spaces with %20 in a URI path.
+ *
+ * @param {string} str - the String to encode
+ * @returns {string} the String with all spaces replaced with %20
+ */
+export function encodeSpacesInUri(str) {
+  return str.includes(' ') ? str.replaceAll(' ', '%20') : str
+}
+
+/**
+ * Remove the file extension from a filename and return the result.
+ *
+ * The filename is expected to be a POSIX path. The extension is only stripped
+ * when no path separator follows the last dot, so paths like
+ * "dir.with.dots/file" are returned unchanged.
+ *
+ * @param {string} filename - the String file name to process
+ * @returns {string} the String filename with the file extension removed
+ *
+ * @example
+ * rootname('part1/chapter1.adoc')
+ * // => "part1/chapter1"
+ */
+export function rootname(filename) {
+  const lastDotIdx = filename.lastIndexOf('.')
+  if (lastDotIdx < 0) return filename
+  return filename.indexOf('/', lastDotIdx) >= 0
+    ? filename
+    : filename.slice(0, lastDotIdx)
+}
+
+/**
+ * Retrieve the basename of a filename, optionally removing the extension.
+ *
+ * @param {string} filename - the String file name to process
+ * @param {boolean|string|null} [dropExt=null] - a Boolean flag or an explicit String extension to drop
+ * @returns {string} the String filename with leading directories removed and, optionally, the extension removed
+ *
+ * @example
+ * basename('images/tiger.png', true)
+ * // => "tiger"
+ *
+ * basename('images/tiger.png', '.png')
+ * // => "tiger"
+ */
+export function basename(filename, dropExt = null) {
+  // Split on both POSIX and Windows separators, take the last non-empty segment.
+  const base =
+    filename
+      .replace(/[/\\]+$/, '')
+      .split(/[/\\]/)
+      .pop() ?? filename
+  if (!dropExt) return base
+  const ext = dropExt === true ? extname(base) : dropExt
+  return ext && base.endsWith(ext) ? base.slice(0, -ext.length) : base
+}
+
+/**
+ * Return whether this path has a file extension.
+ *
+ * @param {string} path - the path String to check (expects a POSIX path)
+ * @returns {boolean} true if the path has a file extension, false otherwise
+ */
+export function isExtname(path) {
+  const lastDotIdx = path.lastIndexOf('.')
+  return lastDotIdx >= 0 && path.indexOf('/', lastDotIdx) < 0
+}
+
+/**
+ * Retrieve the file extension of the specified path.
+ *
+ * The file extension is the portion of the last path segment starting from
+ * the last period. Differs from Node's path.extname in that the fallback value
+ * is configurable.
+ *
+ * @param {string} path - the path String in which to look for a file extension
+ * @param {string} [fallback=''] - the fallback String to return if no file extension is present
+ * @returns {string} the String file extension (with the leading dot) or fallback
+ */
+export function extname(path, fallback = '') {
+  const lastDotIdx = path.lastIndexOf('.')
+  if (lastDotIdx < 0) return fallback
+  // treat both '/' and '\\' as path separators (Windows support)
+  if (path.indexOf('/', lastDotIdx) >= 0 || path.indexOf('\\', lastDotIdx) >= 0)
+    return fallback
+  return path.slice(lastDotIdx)
+}
+
+/**
+ * Async-aware string replacement using matchAll.
+ *
+ * The replacer may return a string or a Promise<string>.
+ * The regex is treated as global regardless of its flags.
+ *
+ * @param {string} str - the String to perform replacements on
+ * @param {RegExp} regex - the RegExp pattern to match
+ * @param {Function} replacer - an async function receiving the same arguments as String#replace callbacks
+ * @returns {Promise<string>} the String with all matches replaced
+ */
+export async function asyncReplace(str, regex, replacer) {
+  const gRegex = regex.flags.includes('g')
+    ? regex
+    : new RegExp(regex.source, `${regex.flags}g`)
+  const matches = [...str.matchAll(gRegex)]
+  if (matches.length === 0) return str
+  const parts = []
+  let lastIndex = 0
+  for (const match of matches) {
+    parts.push(str.slice(lastIndex, match.index))
+    // Process replacements sequentially so state mutations (e.g. footnote registration)
+    // are visible to subsequent replacements in the same string.
+    parts.push(await replacer(...match, match.index, str))
+    lastIndex = match.index + match[0].length
+  }
+  parts.push(str.slice(lastIndex))
+  return parts.join('')
+}
+
+/**
+ * Make a directory, creating all missing parent directories.
+ *
+ * @param {string} dir - the String path of the directory to create
+ * @returns {Promise<void>} Throws if the path cannot be created
+ */
+export async function mkdirP(dir) {
+  const { mkdir } = await import('node:fs/promises')
+  await mkdir(dir, { recursive: true })
+}
+
+// ── Roman numeral helpers ─────────────────────────────────────────────────────
+
+const ROMAN_NUMERALS_WITH_REDUCERS = [
+  ['M', 1000],
+  ['CM', 900],
+  ['D', 500],
+  ['CD', 400],
+  ['C', 100],
+  ['XC', 90],
+  ['L', 50],
+  ['XL', 40],
+  ['X', 10],
+  ['IX', 9],
+  ['V', 5],
+  ['IV', 4],
+  ['I', 1],
+]
+
+const ROMAN_NUMERALS = { I: 1, V: 5, X: 10, L: 50, C: 100, D: 500, M: 1000 }
+
+/**
+ * Convert an integer to a Roman numeral.
+ *
+ * @param {number} val - the integer value to convert
+ * @returns {string} the String Roman numeral
+ */
+export function intToRoman(val) {
+  let result = ''
+  for (const [l, i] of ROMAN_NUMERALS_WITH_REDUCERS) {
+    const repeat = Math.floor(val / i)
+    val %= i
+    result += l.repeat(repeat)
+  }
+  return result
+}
+
+/**
+ * Convert an uppercase Roman numeral to an integer.
+ *
+ * @param {string} val - the String Roman numeral in uppercase to convert
+ * @returns {number} the integer value
+ */
+export function romanToInt(val) {
+  const valmap = [...val].map((c) => ROMAN_NUMERALS[c])
+  let result = 0
+  for (let idx = 0; idx < valmap.length; idx++) {
+    const v = valmap[idx]
+    const succ = valmap[idx + 1]
+    result += succ && succ > v ? -v : v
+  }
+  return result
+}
+
+/**
+ * Get the next value in a sequence.
+ *
+ * Handles integer sequences (numeric increment) and alphabetic sequences
+ * (ASCII letter increment with carry, matching Ruby's String#succ for the
+ * alphanumeric subset used by Asciidoctor list labels).
+ *
+ * @param {string|number} current - the value to increment
+ * @returns {string|number} the next value in the sequence
+ */
+export function nextval(current) {
+  if (typeof current === 'number') return current + 1
+  const intval = parseInt(current, 10)
+  if (String(intval) === String(current)) return intval + 1
+  // Mirrors Ruby's String#succ for single- and multi-character strings.
+  // Strategy: find the rightmost ASCII-alphanumeric character and increment it
+  // with carry.  If NO alphanumeric character exists, increment the rightmost
+  // character's Unicode code point instead.
+  const chars = [...current] // split by Unicode code point (handles surrogate pairs)
+  let hasAlnum = false
+  for (let i = chars.length - 1; i >= 0; i--) {
+    const code = chars[i].codePointAt(0)
+    const isLower = code >= 97 && code <= 122
+    const isUpper = code >= 65 && code <= 90
+    const isDigit = code >= 48 && code <= 57
+    if (!isLower && !isUpper && !isDigit) continue
+    hasAlnum = true
+    const atEnd =
+      (isLower && code === 122) ||
+      (isUpper && code === 90) ||
+      (isDigit && code === 57)
+    if (!atEnd) {
+      chars[i] = String.fromCodePoint(code + 1)
+      return chars.join('')
+    }
+    // Carry: wrap this char and continue to the next alphanumeric to the left.
+    chars[i] = isLower ? 'a' : isUpper ? 'A' : '0'
+    // Find next alphanumeric to carry into.
+    let carried = false
+    for (let j = i - 1; j >= 0; j--) {
+      const c2 = chars[j].codePointAt(0)
+      const l2 = c2 >= 97 && c2 <= 122
+      const u2 = c2 >= 65 && c2 <= 90
+      const d2 = c2 >= 48 && c2 <= 57
+      if (!l2 && !u2 && !d2) continue
+      const end2 = (l2 && c2 === 122) || (u2 && c2 === 90) || (d2 && c2 === 57)
+      if (!end2) {
+        chars[j] = String.fromCodePoint(c2 + 1)
+        carried = true
+        break
+      }
+      chars[j] = l2 ? 'a' : u2 ? 'A' : '0'
+    }
+    if (!carried) {
+      // All alphanumeric characters wrapped — prepend carry character.
+      const carry = isLower ? 'a' : isUpper ? 'A' : '1'
+      return carry + chars.join('')
+    }
+    return chars.join('')
+  }
+  if (!hasAlnum) {
+    // No alphanumeric chars: increment the rightmost character's code point.
+    const last = chars.length - 1
+    const code = chars[last].codePointAt(0)
+    chars[last] = String.fromCodePoint(code + 1)
+    return chars.join('')
+  }
+  return current
+}

package/src/index.js

@@ -0,0 +1,138 @@
+import packageJson from '../package.json' with { type: 'json' }
+import { load as _load, loadFile as _loadFile } from './load.js'
+import { convert, convertFile } from './convert.js'
+import {
+  Document,
+  DocumentTitle,
+  Author,
+  Footnote,
+  ImageReference,
+  RevisionInfo,
+} from './document.js'
+import { Logger, LoggerManager, MemoryLogger, NullLogger } from './logging.js'
+import { SafeMode, ContentModel } from './constants.js'
+import { Timings } from './timings.js'
+import { AbstractNode } from './abstract_node.js'
+import { AbstractBlock } from './abstract_block.js'
+import {
+  Registry,
+  Processor,
+  ProcessorExtension,
+  Preprocessor,
+  TreeProcessor,
+  Postprocessor,
+  IncludeProcessor,
+  DocinfoProcessor,
+  BlockProcessor,
+  InlineMacroProcessor,
+  BlockMacroProcessor,
+  Extensions,
+} from './extensions.js'
+import {
+  Converter,
+  ConverterBase,
+  CustomFactory,
+  DefaultFactory as DefaultConverterFactory,
+  deriveBackendTraits,
+} from './converter.js'
+import { Inline } from './inline.js'
+import { Block } from './block.js'
+import { List, ListItem } from './list.js'
+import { Section } from './section.js'
+import { Cursor, Reader } from './reader.js'
+import Html5Converter from './converter/html5.js'
+import {
+  SyntaxHighlighter,
+  SyntaxHighlighterBase,
+  DefaultFactory as DefaultSyntaxHighlighterFactory,
+} from './syntax_highlighter.js'
+
+const ASCIIDOCTOR_CORE_VERSION = '2.0.26'
+
+/**
+ * Get the version of Asciidoctor.js.
+ *
+ * @returns {string} - the version of Asciidoctor.js
+ */
+export function getVersion() {
+  return packageJson.version
+}
+
+/**
+ * Get Asciidoctor core version number.
+ *
+ * @returns {string} - the version of Asciidoctor core (Ruby)
+ */
+export function getCoreVersion() {
+  return ASCIIDOCTOR_CORE_VERSION
+}
+
+/**
+ * Parse the AsciiDoc source input into a Document.
+ *
+ * @param {string|string[]|Buffer} input - the AsciiDoc source as a String, String Array, or Buffer
+ * @param {Object} [options={}] - a plain object of options to control processing
+ * @returns {Promise<Document>} - the parsed Document
+ */
+export async function load(input, options = {}) {
+  return _load(input, options)
+}
+
+/**
+ * Parse the contents of the AsciiDoc source file into a Document.
+ *
+ * @param {string} filename - the path to the AsciiDoc source file
+ * @param {Object} [options={}] - a plain object of options to control processing
+ * @returns {Promise<Document>} - the parsed Document
+ */
+export async function loadFile(filename, options = {}) {
+  return _loadFile(filename, options)
+}
+
+export { convert, convertFile }
+
+export {
+  Document,
+  DocumentTitle,
+  Author,
+  Footnote,
+  ImageReference,
+  RevisionInfo,
+  Logger,
+  AbstractNode,
+  AbstractBlock,
+  Inline,
+  Block,
+  List,
+  ListItem,
+  Section,
+  Reader,
+  SyntaxHighlighterBase,
+  LoggerManager,
+  MemoryLogger,
+  NullLogger,
+  SafeMode,
+  ContentModel,
+  Timings,
+  Registry,
+  Processor,
+  ProcessorExtension,
+  Preprocessor,
+  TreeProcessor,
+  Postprocessor,
+  IncludeProcessor,
+  DocinfoProcessor,
+  BlockProcessor,
+  InlineMacroProcessor,
+  BlockMacroProcessor,
+  Extensions,
+  Cursor,
+  Converter as ConverterFactory,
+  ConverterBase,
+  CustomFactory as ConverterCustomFactory,
+  DefaultConverterFactory,
+  deriveBackendTraits,
+  DefaultSyntaxHighlighterFactory,
+  Html5Converter,
+  SyntaxHighlighter,
+}

package/src/inline.js

@@ -0,0 +1,158 @@
+// ESM conversion of inline.rb
+
+import { AbstractNode } from './abstract_node.js'
+
+/**
+ * Represents an inline element in an AsciiDoc document.
+ */
+export class Inline extends AbstractNode {
+  /** @type {string|null} */
+  id
+  /** @type {string|null} */
+  type
+  /** @type {string|null} */
+  target
+  /** @type {string|null} */
+  text
+
+  /**
+   * @param {AbstractNode} parent
+   * @param {string} context
+   * @param {string|null} [text=null] - The String text of this inline element.
+   * @param {Object} [opts={}] - A plain object of options:
+   *   id     - The String id of this inline element.
+   *   type   - The String type qualifier (e.g. 'ref', 'bibref').
+   *   target - The String target (e.g. a URI).
+   */
+  constructor(parent, context, text = null, opts = {}) {
+    super(parent, context, opts)
+    this.nodeName = `inline_${context}`
+    this.text = text
+    this.id = opts.id ?? null
+    this.type = opts.type ?? null
+    this.target = opts.target ?? null
+  }
+
+  isBlock() {
+    return false
+  }
+  isInline() {
+    return true
+  }
+
+  /**
+   * Convert this inline element using the document's converter.
+   * @returns {Promise<string>}
+   */
+  async convert() {
+    return this.converter.convert(this)
+  }
+
+  /** @deprecated Use convert() instead. */
+  render() {
+    return this.convert()
+  }
+
+  /**
+   * Get the converted content (alias for text).
+   * @returns {string|null}
+   */
+  content() {
+    return this.text
+  }
+
+  /**
+   * Alias for {@link getAlt}.
+   * @see {getAlt}
+   */
+  get alt() {
+    return this.getAttribute('alt') || ''
+  }
+
+  /**
+   * Check whether this inline node has reftext.
+   * For ref and bibref nodes the text acts as the reftext.
+   * @returns {boolean}
+   */
+  hasReftext() {
+    return !!(this.text && (this.type === 'ref' || this.type === 'bibref'))
+  }
+
+  /**
+   * Get the reftext for this inline node with substitutions applied.
+   * The result is pre-computed during Document.parse() via precomputeReftext().
+   * Falls back to the raw text if precomputeReftext() has not been called yet.
+   * @returns {string|null}
+   */
+  get reftext() {
+    if (this._convertedReftext !== undefined) return this._convertedReftext
+    return this.text ?? null
+  }
+
+  /**
+   * @internal
+   * Pre-compute the reftext with substitutions applied asynchronously.
+   * Called during Document.parse() so the synchronous getter works during conversion.
+   * @returns {Promise<void>}
+   */
+  async precomputeReftext() {
+    const val = this.text
+    this._convertedReftext =
+      val != null ? await this.applyReftextSubs(val) : null
+  }
+
+  /**
+   * Generate cross-reference text (xreftext) that can be used to refer to this inline node.
+   *
+   * Uses the explicit reftext for this inline node, if specified, retrieved by calling the
+   * reftext method. Otherwise, returns null.
+   *
+   * @param {string|null} [_xrefstyle=null] - Not currently used.
+   * @returns {string|null} the reftext to refer to this inline node, or null if no reftext is defined.
+   */
+  xreftext(_xrefstyle = null) {
+    return this.reftext
+  }
+
+  // ── JavaScript-style accessors ────────────────────────────────────────────────
+
+  /**
+   * Return the text of this inline node.
+   * @returns {string|null}
+   */
+  getText() {
+    return this.text
+  }
+
+  /**
+   * Return the type qualifier of this inline node (e.g. 'ref', 'bibref').
+   * @returns {string|null}
+   */
+  getType() {
+    return this.type
+  }
+
+  /**
+   * Return the target (e.g. URI or anchor) of this inline node.
+   * @returns {string|null}
+   */
+  getTarget() {
+    return this.target
+  }
+
+  /**
+   * Get the alt text for this inline image.
+   * @returns {string} the value of the alt attribute, or ''.
+   */
+  getAlt() {
+    return this.alt
+  }
+
+  /**
+   * Get the reftext for this inline node with substitutions applied.
+   * @returns {string|null}
+   */
+  getReftext() {
+    return this.reftext
+  }
+}