@asciidoctor/core 4.0.0-alpha.2 → 4.0.0-alpha.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asciidoctor/core",
-  "version": "4.0.0-alpha.2",
+  "version": "4.0.0-alpha.3",
   "description": "Asciidoctor.js: AsciiDoc in JavaScript powered by Asciidoctor",
   "type": "module",
   "main": "build/node/index.cjs",
@@ -28,6 +28,7 @@
     "build:types": "tsc && node scripts/strip-internal.js && node scripts/patch-jsdoc.js",
     "docs": "typedoc --tsconfig tsconfig.docs.json",
     "test": "node --test test/**.test.js",
+    "test:deno": "deno test --allow-env --no-check --allow-read --allow-sys --allow-write --allow-run --allow-net test/*.test.js",
     "test:coverage": "node --test --experimental-test-coverage --test-coverage-include='src/**' test/**.test.js",
     "test:browser": "vitest run --config vitest.browser.config.js",
     "lint": "biome lint src test",
@@ -65,7 +66,7 @@
   },
   "homepage": "https://github.com/asciidoctor/asciidoctor.js",
   "volta": {
-    "node": "24.14.1"
+    "node": "24.15.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.13",

package/src/attribute_entry.js

@@ -1,3 +1,19 @@
+// Symbol key used to store attribute entries on a block-attributes object without
+// polluting the public attributes (invisible to Object.keys / for-in / JSON.stringify).
+// Spread ({ ...attrs }) copies Symbol-keyed properties, so the entry survives the
+// shallow clone made in AbstractNode's constructor.
+export const ATTR_ENTRIES_KEY = Symbol('attribute_entries')
+
+/**
+ * Return the attribute entries stored for the given block attributes object,
+ * or undefined if none have been saved.
+ * @param {Object} blockAttributes
+ * @returns {AttributeEntry[]|undefined}
+ */
+export function getAttributeEntries(blockAttributes) {
+  return blockAttributes[ATTR_ENTRIES_KEY]
+}
+
 export class AttributeEntry {
   constructor(name, value, negate = null) {
     this.name = name
@@ -6,7 +22,7 @@ export class AttributeEntry {
   }
 
   saveTo(blockAttributes) {
-    ;(blockAttributes.attribute_entries ??= []).push(this)
+    ;(blockAttributes[ATTR_ENTRIES_KEY] ??= []).push(this)
     return this
   }
 }

package/src/browser/reader.js

@@ -5,7 +5,7 @@
 //
 // This logic is specific to Asciidoctor.js and has no equivalent in the upstream Ruby asciidoctor
 // implementation. It handles the case where the document is loaded in a browser environment
-// (XMLHttpRequest / Fetch IO module) where paths can be file:// or http(s):// URIs.
+// where paths can be file:// or http(s):// URIs.
 //
 // The key behavioural differences from the standard file-system resolver:
 //   - Relative targets are resolved by string concatenation against a URI context dir,
@@ -55,7 +55,7 @@ function _linkReplacement(reader, target, attrlist) {
  * 1. target starts with file:// → inc_path = relpath = target
  * 2. target is a URI → must descend from baseDir or allow-uri-read; else → link
  * 3. target is an absolute OS path → prepend file:// (or file:///)
- * 4. baseDir == '.' → inc_path = relpath = target  (resolved by XMLHttpRequest/fetch)
+ * 4. baseDir == '.' → inc_path = relpath = target  (resolved by fetch)
  * 5. baseDir starts with file:// OR baseDir is not a URI → inc_path = baseDir/target; relpath = target
  * 6. baseDir is an absolute URL → inc_path = baseDir/target; relpath = target
  *

package/src/converter/template.js

@@ -276,7 +276,7 @@ export class TemplateConverter extends ConverterBase {
 
     let entries
     try {
-      entries = await fsp.readdir(templateDir)
+      entries = (await fsp.readdir(templateDir)).sort()
     } catch {
       return result
     }

package/src/document.js

@@ -68,7 +68,11 @@ export class ImageReference {
 import { Footnote } from './footnote.js'
 export { Footnote }
 
-import { AttributeEntry } from './attribute_entry.js'
+import {
+  AttributeEntry,
+  getAttributeEntries,
+  ATTR_ENTRIES_KEY,
+} from './attribute_entry.js'
 export { AttributeEntry }
 
 /**
@@ -927,8 +931,9 @@ export class Document extends AbstractBlock {
    * @param {Object} blockAttributes
    */
   playbackAttributes(blockAttributes) {
-    if (!('attribute_entries' in blockAttributes)) return
-    for (const entry of blockAttributes.attribute_entries) {
+    const entries = getAttributeEntries(blockAttributes)
+    if (!entries) return
+    for (const entry of entries) {
       if (entry.negate) {
         delete this.attributes[entry.name]
         if (entry.name === 'compat-mode') this.compatMode = false
@@ -1657,6 +1662,12 @@ export class Document extends AbstractBlock {
    * Handles titles (AbstractBlock), list item text, table cell text, and reftexts.
    */
   async _resolveAllTexts(block) {
+    // The header section lives outside document.blocks; pre-compute its title here so
+    // that doc.doctitle() returns the fully-substituted title (with replacements applied,
+    // e.g. ' → ’) rather than the header-subs-only fallback.
+    if (block === this && this.header) {
+      await this.header.precomputeTitle?.()
+    }
     // Skip title pre-computation for blocks with an explicit empty id ([id=]).
     // In Ruby, apply_title_subs is lazy: it is never called during parsing for such
     // blocks because section.title is never accessed.  An explicit empty id is
@@ -1740,7 +1751,7 @@ export class Document extends AbstractBlock {
    * @internal
    */
   _clearPlaybackAttributes(attributes) {
-    delete attributes.attribute_entries
+    delete attributes[ATTR_ENTRIES_KEY]
   }
 
   /**

package/src/extensions.js

@@ -27,6 +27,94 @@ import { basename } from './helpers.js'
 import { ATTR_REF_HEAD } from './constants.js'
 import { MacroNameRx, CC_ANY } from './rx.js'
 
+// Type-only imports for JSDoc
+/**
+ * @typedef {import('./document.js').Document} Document
+ * @typedef {import('./abstract_block.js').AbstractBlock} AbstractBlock
+ */
+
+// ── DSL interface types ───────────────────────────────────────────────────────
+
+/**
+ * DSL interface for configuring a {@link Processor} instance.
+ * Applied to a processor instance via `Object.assign(instance, DslMixin)`.
+ *
+ * The `process` property behaves as a setter when called with a single Function
+ * argument (stores the process block), or as a passthrough caller otherwise.
+ *
+ * @typedef {object} ProcessorDslInterface
+ * @property {(key: string, value: unknown) => void} option - Set a config option.
+ * @property {(fn: (...args: unknown[]) => unknown) => void} process - Register the process function.
+ * @property {() => boolean} processBlockGiven - Returns true if a process function has been registered.
+ */
+
+/**
+ * DSL interface for document processors (Preprocessor, TreeProcessor, Postprocessor, DocinfoProcessor).
+ *
+ * @typedef {ProcessorDslInterface & { prefer(): void; prepend(): void }} DocumentProcessorDslInterface
+ */
+
+/**
+ * DSL interface for syntax processors (BlockProcessor, BlockMacroProcessor, InlineMacroProcessor).
+ *
+ * @typedef {ProcessorDslInterface & {
+ *   named(value: string): void;
+ *   contentModel(value: string): void;
+ *   parseContentAs(value: string): void;
+ *   positionalAttributes(...value: string[]): void;
+ *   namePositionalAttributes(...value: string[]): void;
+ *   positionalAttrs(...value: string[]): void;
+ *   defaultAttributes(value: Record<string, string>): void;
+ *   defaultAttrs(value: Record<string, string>): void;
+ *   resolveAttributes(...args: unknown[]): void;
+ *   resolvesAttributes(...args: unknown[]): void;
+ * }} SyntaxProcessorDslInterface
+ */
+
+/**
+ * DSL interface for include processors.
+ *
+ * @typedef {DocumentProcessorDslInterface & {
+ *   handles(fn: (doc: Document, target: string) => boolean): void;
+ * }} IncludeProcessorDslInterface
+ */
+
+/**
+ * DSL interface for docinfo processors.
+ *
+ * @typedef {DocumentProcessorDslInterface & {
+ *   atLocation(value: string): void;
+ * }} DocinfoProcessorDslInterface
+ */
+
+/**
+ * DSL interface for block processors.
+ *
+ * @typedef {SyntaxProcessorDslInterface & {
+ *   contexts(...value: (string | string[])[]): void;
+ *   onContexts(...value: (string | string[])[]): void;
+ *   onContext(...value: (string | string[])[]): void;
+ *   bindTo(...value: (string | string[])[]): void;
+ * }} BlockProcessorDslInterface
+ */
+
+/**
+ * DSL interface for macro processors (block and inline macros).
+ *
+ * @typedef {SyntaxProcessorDslInterface} MacroProcessorDslInterface
+ */
+
+/**
+ * DSL interface for inline macro processors.
+ *
+ * @typedef {MacroProcessorDslInterface & {
+ *   format(value: string): void;
+ *   matchFormat(value: string): void;
+ *   usingFormat(value: string): void;
+ *   match(value: RegExp): void;
+ * }} InlineMacroProcessorDslInterface
+ */
+
 // ── DSL Mixins ────────────────────────────────────────────────────────────────
 
 /**
@@ -625,7 +713,12 @@ export class Processor {
  * Extensions.register(function () { this.preprocessor(CommentStripPreprocessor) })
  */
 export class Preprocessor extends Processor {
-  process(_document, _reader) {
+  /**
+   * @param {Document} document - The document being parsed.
+   * @param {Reader} reader - The reader positioned at the beginning of the source.
+   * @returns {Reader|undefined} The same or a substitute Reader, or undefined to use the original.
+   */
+  process(document, reader) {
     throw new Error(
       `${this.constructor.name} must implement the process method`
     )
@@ -650,7 +743,11 @@ Preprocessor.DSL = DocumentProcessorDsl
  * Extensions.register(function () { this.treeProcessor(ShoutTreeProcessor) })
  */
 export class TreeProcessor extends Processor {
-  process(_document) {
+  /**
+   * @param {Document} document - The parsed document.
+   * @returns {void}
+   */
+  process(document) {
     throw new Error(
       `${this.constructor.name} must implement the process method`
     )
@@ -679,7 +776,12 @@ export const Treeprocessor = TreeProcessor
  * Extensions.register(function () { this.postprocessor(FooterPostprocessor) })
  */
 export class Postprocessor extends Processor {
-  process(_document, _output) {
+  /**
+   * @param {Document} document - The converted document.
+   * @param {string} output - The converted output string.
+   * @returns {string} The (possibly modified) output string.
+   */
+  process(document, output) {
     throw new Error(
       `${this.constructor.name} must implement the process method`
     )
@@ -693,13 +795,25 @@ Postprocessor.DSL = DocumentProcessorDsl
  * Implementations must extend IncludeProcessor.
  */
 export class IncludeProcessor extends Processor {
-  process(_document, _reader, _target, _attributes) {
+  /**
+   * @param {Document} document - The document being parsed.
+   * @param {Reader} reader - The reader for the including document.
+   * @param {string} target - The target of the include directive.
+   * @param {Record<string, string>} attributes - The parsed include attributes.
+   * @returns {void}
+   */
+  process(document, reader, target, attributes) {
     throw new Error(
       `${this.constructor.name} must implement the process method`
     )
   }
 
-  handles(_doc, _target) {
+  /**
+   * @param {Document} doc - The document being parsed.
+   * @param {string} target - The target of the include directive.
+   * @returns {boolean} true if this processor handles the given target.
+   */
+  handles(doc, target) {
     return true
   }
 }
@@ -717,7 +831,11 @@ export class DocinfoProcessor extends Processor {
     this.config.location ??= 'head'
   }
 
-  process(_document) {
+  /**
+   * @param {Document} document - The document being converted.
+   * @returns {string} The docinfo content to inject into the document.
+   */
+  process(document) {
     throw new Error(
       `${this.constructor.name} must implement the process method`
     )
@@ -773,7 +891,13 @@ export class BlockProcessor extends Processor {
     this.config.content_model ??= 'compound'
   }
 
-  process(_parent, _reader, _attributes) {
+  /**
+   * @param {AbstractBlock} parent - The enclosing block.
+   * @param {Reader} reader - The reader positioned at the block content.
+   * @param {Record<string, unknown>} attributes - The parsed block attributes.
+   * @returns {Block|void} A block node, or void to let the parser handle it.
+   */
+  process(parent, reader, attributes) {
     throw new Error(
       `${this.constructor.name} must implement the process method`
     )
@@ -791,7 +915,13 @@ export class MacroProcessor extends Processor {
     this.config.content_model ??= 'attributes'
   }
 
-  process(_parent, _target, _attributes) {
+  /**
+   * @param {AbstractBlock} parent - The enclosing block.
+   * @param {string} target - The macro target (text between `name:` and `[`).
+   * @param {Record<string, unknown>} attributes - The parsed macro attributes.
+   * @returns {Block|Inline|void}
+   */
+  process(parent, target, attributes) {
     throw new Error(
       `${this.constructor.name} must implement the process method`
     )
@@ -837,6 +967,16 @@ export class BlockMacroProcessor extends MacroProcessor {
   set name(value) {
     this._name = value
   }
+
+  /**
+   * @param {AbstractBlock} parent - The enclosing block.
+   * @param {string} target - The macro target.
+   * @param {Record<string, unknown>} attributes - The parsed macro attributes.
+   * @returns {Block} A block node created with one of the `createBlock` helpers.
+   */
+  process(parent, target, attributes) {
+    return super.process(parent, target, attributes)
+  }
 }
 BlockMacroProcessor.DSL = MacroProcessorDsl
 
@@ -880,6 +1020,16 @@ export class InlineMacroProcessor extends MacroProcessor {
     ))
   }
 
+  /**
+   * @param {AbstractBlock} parent - The enclosing block.
+   * @param {string} target - The macro target.
+   * @param {Record<string, unknown>} attributes - The parsed macro attributes.
+   * @returns {Inline} An Inline node created with `this.createInline(...)`.
+   */
+  process(parent, target, attributes) {
+    return super.process(parent, target, attributes)
+  }
+
   resolveRegexp(name, format) {
     if (!MacroNameRx.test(name)) {
       throw new Error(`invalid name for inline macro: ${name}`)
@@ -1263,6 +1413,15 @@ export class Registry {
     return !!this._block_extensions
   }
 
+  /**
+   * Retrieve all BlockProcessor Extension proxy objects.
+   *
+   * @returns {ProcessorExtension[]}
+   */
+  blocks() {
+    return this._block_extensions ? Object.values(this._block_extensions) : []
+  }
+
   /**
    * Check whether a BlockProcessor is registered for the given name and context.
    *
@@ -1309,6 +1468,17 @@ export class Registry {
     return !!this._block_macro_extensions
   }
 
+  /**
+   * Retrieve all BlockMacroProcessor Extension proxy objects.
+   *
+   * @returns {ProcessorExtension[]}
+   */
+  blockMacros() {
+    return this._block_macro_extensions
+      ? Object.values(this._block_macro_extensions)
+      : []
+  }
+
   /**
    * Check whether a BlockMacroProcessor is registered for the given name.
    *
@@ -1414,6 +1584,85 @@ export class Registry {
     return extension
   }
 
+  // ── JavaScript-style accessors ───────────────────────────────────────────────
+
+  /** @returns {object} the plain Object that maps names to groups for this registry. */
+  getGroups() {
+    return this.groups
+  }
+
+  /** Alias for {@link preprocessors}. */
+  getPreprocessors() {
+    return this.preprocessors()
+  }
+
+  /** Alias for {@link treeProcessors}. */
+  getTreeProcessors() {
+    return this.treeProcessors()
+  }
+
+  /** Alias for {@link includeProcessors}. */
+  getIncludeProcessors() {
+    return this.includeProcessors()
+  }
+
+  /** Alias for {@link postprocessors}. */
+  getPostprocessors() {
+    return this.postprocessors()
+  }
+
+  /**
+   * Alias for {@link docinfoProcessors}.
+   *
+   * @param {string|null} [location=null]
+   */
+  getDocinfoProcessors(location = null) {
+    return this.docinfoProcessors(location)
+  }
+
+  /** Alias for {@link blocks}. */
+  getBlocks() {
+    return this.blocks()
+  }
+
+  /** Alias for {@link blockMacros}. */
+  getBlockMacros() {
+    return this.blockMacros()
+  }
+
+  /** Alias for {@link inlineMacros}. */
+  getInlineMacros() {
+    return this.inlineMacros()
+  }
+
+  /**
+   * Alias for {@link registeredForInlineMacro}.
+   *
+   * @param {string} name
+   */
+  getInlineMacroFor(name) {
+    return this.registeredForInlineMacro(name)
+  }
+
+  /**
+   * Alias for {@link registeredForBlock}.
+   *
+   * @param {string} name
+   * @param {string} context
+   */
+  getBlockFor(name, context) {
+    return this.registeredForBlock(name, context)
+  }
+
+  /**
+   * Alias for {@link registeredForBlockMacro}.
+   *
+   * @param {string} name
+   */
+  getBlockMacroFor(name) {
+    return this.registeredForBlockMacro(name)
+  }
+
   // ── Private helpers ──────────────────────────────────────────────────────────
 
   /** @internal */
@@ -1639,6 +1888,15 @@ export const Extensions = {
     return _groups
   },
 
+  /**
+   * Alias for {@link groups}.
+   *
+   * @returns {object}
+   */
+  getGroups() {
+    return this.groups()
+  },
+
   /**
    * Create a new Registry, optionally pre-populated with a named block.
    *

package/src/helpers.js

@@ -38,7 +38,16 @@ const rstrip = (line) => line.replace(/[ \t\r\n\f\v]+$/, '')
  */
 export function prepareSourceArray(data, trimEnd = true) {
   if (!data.length) return []
-  if (data[0].startsWith(BOM)) data[0] = data[0].slice(1)
+  if (data[0].startsWith(BOM)) {
+    data[0] = data[0].slice(1)
+  } else if (
+    data[0].charCodeAt(0) === 0xef &&
+    data[0].charCodeAt(1) === 0xbb &&
+    data[0].charCodeAt(2) === 0xbf
+  ) {
+    // Strip UTF-8 BOM encoded as three raw characters ( / \xEF\xBB\xBF) if not already decoded to U+FEFF
+    data[0] = data[0].slice(3)
+  }
   // Strip trailing \r to normalize Windows CRLF line endings (lines were split on \n, leaving \r).
   return trimEnd
     ? data.map(rstrip)
@@ -58,7 +67,16 @@ export function prepareSourceArray(data, trimEnd = true) {
  */
 export function prepareSourceString(data, trimEnd = true) {
   if (!data) return []
-  if (data.startsWith(BOM)) data = data.slice(1)
+  if (data.startsWith(BOM)) {
+    data = data.slice(1)
+  } else if (
+    data.charCodeAt(0) === 0xef &&
+    data.charCodeAt(1) === 0xbb &&
+    data.charCodeAt(2) === 0xbf
+  ) {
+    // Strip UTF-8 BOM encoded as three raw characters ( / \xEF\xBB\xBF) if not already decoded to U+FEFF
+    data = data.slice(3)
+  }
   // 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')

package/src/index.js

@@ -28,6 +28,18 @@ import {
   BlockMacroProcessor,
   Extensions,
 } from './extensions.js'
+
+// Re-export DSL interface types for TypeScript consumers.
+/**
+ * @typedef {import('./extensions.js').ProcessorDslInterface} ProcessorDslInterface
+ * @typedef {import('./extensions.js').DocumentProcessorDslInterface} DocumentProcessorDslInterface
+ * @typedef {import('./extensions.js').SyntaxProcessorDslInterface} SyntaxProcessorDslInterface
+ * @typedef {import('./extensions.js').IncludeProcessorDslInterface} IncludeProcessorDslInterface
+ * @typedef {import('./extensions.js').DocinfoProcessorDslInterface} DocinfoProcessorDslInterface
+ * @typedef {import('./extensions.js').BlockProcessorDslInterface} BlockProcessorDslInterface
+ * @typedef {import('./extensions.js').MacroProcessorDslInterface} MacroProcessorDslInterface
+ * @typedef {import('./extensions.js').InlineMacroProcessorDslInterface} InlineMacroProcessorDslInterface
+ */
 import {
   Converter,
   ConverterBase,

package/src/load.js

@@ -17,7 +17,7 @@
 
 import { SpaceDelimiterRx, EscapedSpaceRx } from './rx.js'
 import { NULL, BACKEND_ALIASES } from './constants.js'
-import { LoggerManager, NullLogger } from './logging.js'
+import { NullLogger, withLogger, getContextLogger } from './logging.js'
 import { basename, extname } from './helpers.js'
 import { Document } from './document.js'
 import { Converter } from './converter.js'
@@ -58,17 +58,23 @@ export async function load(input, options = {}) {
   // Shallow-copy options so we don't mutate the caller's object.
   options = Object.assign({}, options)
 
-  const timings = options.timings ?? null
-  if (timings) timings.start('read')
-
   // ── Logger override ───────────────────────────────────────────────────────
+  // When a logger option is supplied, run the conversion in an async-local
+  // context so the logger is scoped to this call only — no global mutation,
+  // which makes concurrent callers (e.g. parallel Deno tests) safe.
   if ('logger' in options) {
-    const logger = options.logger
-    if (logger !== LoggerManager.logger) {
-      LoggerManager.logger = logger ?? new NullLogger()
-    }
+    const newLogger = options.logger ?? new NullLogger()
+    delete options.logger
+    return withLogger(newLogger, () => _doLoad(input, options, newLogger))
   }
 
+  return _doLoad(input, options)
+}
+
+async function _doLoad(input, options, explicitLogger = null) {
+  const timings = options.timings ?? null
+  if (timings) timings.start('read')
+
   // ── Attributes normalisation ──────────────────────────────────────────────
   let attrs = options.attributes
   if (!attrs) {
@@ -100,11 +106,9 @@ export async function load(input, options = {}) {
       attrs.docname = basename(inputPath, docfilesuffix)
     }
     source = await _readStream(input)
-  } else if (
-    typeof input === 'object' &&
-    input?.constructor?.name === 'Buffer'
-  ) {
-    source = input.toString('utf8')
+  } else if (input instanceof Uint8Array) {
+    // Covers both Node.js Buffer (a Uint8Array subclass) and browser Uint8Array shims.
+    source = new TextDecoder('utf-8').decode(input)
   } else if (typeof input === 'string') {
     source = input
   } else if (Array.isArray(input)) {
@@ -167,6 +171,19 @@ export async function load(input, options = {}) {
   }
 
   if (timings) timings.record('parse')
+
+  // Persist the logger on the Document instance so that doc.convert()
+  // (called by convert.js after the async-local context ends) still routes
+  // logging through the caller-supplied logger.
+  // ALS provides it in Node.js/Deno; the explicit parameter covers browser fallback.
+  const contextLogger = getContextLogger() ?? explicitLogger
+  if (contextLogger) {
+    Object.defineProperty(doc, 'logger', {
+      get: () => contextLogger,
+      configurable: true,
+    })
+  }
+
   return doc
 }