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

package/build/node/index.cjs

@@ -5,7 +5,7 @@ const node_fs = require('node:fs');
 const path = require('node:path');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
-var version = "4.0.0-alpha.2";
+var version = "4.0.0-alpha.3";
 const packageJson = {
 	version: version};
 
@@ -1514,6 +1514,65 @@ function resolveSeverity(severity) {
   return severity ?? Severity.UNKNOWN
 }
 
+// ── Per-execution logger context ─────────────────────────────────────────────
+
+// Holds an AsyncLocalStorage instance once it is lazily initialised.
+// Allows per-execution logger isolation without mutating the global singleton,
+// making concurrent test execution (e.g. Deno's node:test) safe.
+let _loggerStore = null;
+
+// Promise singleton — ensures AsyncLocalStorage is initialised at most once.
+let _loggerStorePromise = null;
+
+/**
+ * Lazily initialise an AsyncLocalStorage for per-execution logger context.
+ * Falls back to null in environments that do not support node:async_hooks (e.g. browsers).
+ * @returns {Promise<import('node:async_hooks').AsyncLocalStorage|null>}
+ */
+async function _ensureLoggerStore() {
+  if (_loggerStorePromise === null) {
+    _loggerStorePromise = import('node:async_hooks')
+      .then(({ AsyncLocalStorage }) => {
+        const store = new AsyncLocalStorage();
+        _loggerStore = store;
+        return store
+      })
+      .catch(() => null);
+  }
+  return _loggerStorePromise
+}
+
+/** @internal — returns the logger bound to the current async context, or null */
+function getContextLogger() {
+  return _loggerStore?.getStore() ?? null
+}
+
+/**
+ * Run fn() within an async-local logger context so that all log calls via
+ * `this.logger` (from applyLogging) automatically route to the provided logger
+ * for the duration of the async execution chain.
+ *
+ * Falls back to global mutation in environments without node:async_hooks (e.g. browsers).
+ *
+ * @param {Logger|MemoryLogger|NullLogger} logger - The logger to activate.
+ * @param {() => any} fn - The function to execute within the logger context.
+ * @returns {Promise<any>}
+ */
+async function withLogger(logger, fn) {
+  const store = await _ensureLoggerStore();
+  if (store) {
+    return store.run(logger, fn)
+  }
+  // Fallback for environments without node:async_hooks (browsers).
+  const prev = LoggerManager.logger;
+  if (logger !== prev) LoggerManager.logger = logger;
+  try {
+    return await fn()
+  } finally {
+    if (logger !== prev) LoggerManager.logger = prev;
+  }
+}
+
 // ── Logger ────────────────────────────────────────────────────────────────────
 
 /** Standard logger that writes formatted messages to stderr or a custom pipe. */
@@ -1822,8 +1881,9 @@ class MemoryLogger {
 // ── NullLogger ────────────────────────────────────────────────────────────────
 
 /** Logger that discards all messages but still tracks the maximum severity. */
-class NullLogger {
+class NullLogger extends Logger {
   constructor() {
+    super();
     this.level = Severity.UNKNOWN;
     this._maxSeverity = null;
   }
@@ -1968,12 +2028,12 @@ const LoggerManager = (() => {
 function applyLogging(proto) {
   Object.defineProperty(proto, 'logger', {
     get() {
-      return LoggerManager.logger
+      return _loggerStore?.getStore() ?? LoggerManager.logger
     },
     configurable: true,
   });
 
-  proto.getLogger = () => LoggerManager.logger;
+  proto.getLogger = () => _loggerStore?.getStore() ?? LoggerManager.logger;
 
   proto.messageWithContext = (text, context = {}) =>
     Logger.AutoFormattingMessage.attach({ text, ...context });
@@ -2020,7 +2080,16 @@ const rstrip = (line) => line.replace(/[ \t\r\n\f\v]+$/, '');
  */
 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)
@@ -2040,7 +2109,16 @@ function prepareSourceArray(data, trimEnd = true) {
  */
 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');
@@ -5972,7 +6050,7 @@ const SyntaxHighlighter = new DefaultFactory();
 //
 // 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,
@@ -6021,7 +6099,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
  *
@@ -6743,7 +6821,7 @@ class Reader {
     return this.source()
   }
   getLogger() {
-    return LoggerManager.logger
+    return this._document?.logger ?? LoggerManager.logger
   }
   createLogMessage(text, context = {}) {
     return Logger.AutoFormattingMessage.attach({ text, ...context })
@@ -9568,6 +9646,22 @@ class AttributeList {
   }
 }
 
+// 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.
+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}
+ */
+function getAttributeEntries(blockAttributes) {
+  return blockAttributes[ATTR_ENTRIES_KEY]
+}
+
 class AttributeEntry {
   constructor(name, value, negate = null) {
     this.name = name;
@@ -9576,7 +9670,7 @@ class AttributeEntry {
   }
 
   saveTo(blockAttributes) {
-(blockAttributes.attribute_entries ??= []).push(this);
+(blockAttributes[ATTR_ENTRIES_KEY] ??= []).push(this);
     return this
   }
 }
@@ -11051,7 +11145,7 @@ class Parser {
       const Rdr = Reader;
       const result = await extension.processMethod(
         parent,
-        blockReader ?? new Rdr(lines),
+        blockReader ?? new Rdr(lines, null, { document: parent.document }),
         { ...attributes }
       );
       if (!result || result === parent) return null
@@ -13173,6 +13267,94 @@ function _uniform(str, chr, len) {
 //     references; they will be resolved when those modules implement the methods.
 
 
+// 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 ────────────────────────────────────────────────────────────────
 
 /**
@@ -13768,7 +13950,12 @@ class Processor {
  * Extensions.register(function () { this.preprocessor(CommentStripPreprocessor) })
  */
 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`
     )
@@ -13793,7 +13980,11 @@ Preprocessor.DSL = DocumentProcessorDsl;
  * Extensions.register(function () { this.treeProcessor(ShoutTreeProcessor) })
  */
 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`
     )
@@ -13819,7 +14010,12 @@ TreeProcessor.DSL = DocumentProcessorDsl;
  * Extensions.register(function () { this.postprocessor(FooterPostprocessor) })
  */
 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`
     )
@@ -13833,13 +14029,25 @@ Postprocessor.DSL = DocumentProcessorDsl;
  * Implementations must extend IncludeProcessor.
  */
 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
   }
 }
@@ -13857,7 +14065,11 @@ 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`
     )
@@ -13913,7 +14125,13 @@ 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`
     )
@@ -13931,7 +14149,13 @@ 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`
     )
@@ -13977,6 +14201,16 @@ 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;
 
@@ -14020,6 +14254,16 @@ 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}`)
@@ -14383,6 +14627,15 @@ 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.
    *
@@ -14429,6 +14682,17 @@ 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.
    *
@@ -14534,6 +14798,85 @@ 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 */
@@ -14759,6 +15102,15 @@ 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.
    *
@@ -15986,8 +16338,9 @@ 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;
@@ -16716,6 +17069,12 @@ 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. ' → &#8217;) 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
@@ -16799,7 +17158,7 @@ class Document extends AbstractBlock {
    * @internal
    */
   _clearPlaybackAttributes(attributes) {
-    delete attributes.attribute_entries;
+    delete attributes[ATTR_ENTRIES_KEY];
   }
 
   /**
@@ -19527,17 +19886,23 @@ async function load$1(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) {
@@ -19569,11 +19934,9 @@ async function load$1(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)) {
@@ -19636,6 +19999,19 @@ async function load$1(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
 }
 
@@ -22534,7 +22910,7 @@ class TemplateConverter extends ConverterBase {
 
     let entries;
     try {
-      entries = await node_fs.promises.readdir(templateDir);
+      entries = (await node_fs.promises.readdir(templateDir)).sort();
     } catch {
       return result
     }