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

package/src/logging.js

@@ -39,6 +39,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 */
+export 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>}
+ */
+export 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. */
@@ -347,8 +406,9 @@ export class MemoryLogger {
 // ── NullLogger ────────────────────────────────────────────────────────────────
 
 /** Logger that discards all messages but still tracks the maximum severity. */
-export class NullLogger {
+export class NullLogger extends Logger {
   constructor() {
+    super()
     this.level = Severity.UNKNOWN
     this._maxSeverity = null
   }
@@ -493,12 +553,12 @@ export const LoggerManager = (() => {
 export 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 })
@@ -512,10 +572,10 @@ export function applyLogging(proto) {
  */
 export const Logging = {
   get logger() {
-    return LoggerManager.logger
+    return _loggerStore?.getStore() ?? LoggerManager.logger
   },
   getLogger() {
-    return LoggerManager.logger
+    return _loggerStore?.getStore() ?? LoggerManager.logger
   },
   messageWithContext(text, context = {}) {
     return Logger.AutoFormattingMessage.attach({ text, ...context })

package/src/parser.js

@@ -1549,7 +1549,7 @@ export 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

package/src/reader.js

@@ -661,7 +661,7 @@ export class Reader {
     return this.source()
   }
   getLogger() {
-    return LoggerManager.logger
+    return this._document?.logger ?? LoggerManager.logger
   }
   createLogMessage(text, context = {}) {
     return Logger.AutoFormattingMessage.attach({ text, ...context })

package/types/attribute_entry.d.ts

@@ -1,3 +1,11 @@
+/**
+ * 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: any): AttributeEntry[] | undefined;
+export const ATTR_ENTRIES_KEY: unique symbol;
 export class AttributeEntry {
     constructor(name: any, value: any, negate?: any);
     name: any;

package/types/browser/reader.d.ts

@@ -7,7 +7,7 @@
  * 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/types/extensions.d.ts

@@ -224,7 +224,12 @@ export class Processor {
  * Extensions.register(function () { this.preprocessor(CommentStripPreprocessor) })
  */
 export class Preprocessor extends Processor {
-    process(_document: any, _reader: any): void;
+    /**
+     * @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: Document, reader: Reader): Reader | undefined;
 }
 export namespace Preprocessor {
     export { DocumentProcessorDsl as DSL };
@@ -246,7 +251,11 @@ export namespace Preprocessor {
  * Extensions.register(function () { this.treeProcessor(ShoutTreeProcessor) })
  */
 export class TreeProcessor extends Processor {
-    process(_document: any): void;
+    /**
+     * @param {Document} document - The parsed document.
+     * @returns {void}
+     */
+    process(document: Document): void;
 }
 export namespace TreeProcessor {
     export { DocumentProcessorDsl as DSL };
@@ -271,7 +280,12 @@ export const Treeprocessor: typeof TreeProcessor;
  * Extensions.register(function () { this.postprocessor(FooterPostprocessor) })
  */
 export class Postprocessor extends Processor {
-    process(_document: any, _output: any): void;
+    /**
+     * @param {Document} document - The converted document.
+     * @param {string} output - The converted output string.
+     * @returns {string} The (possibly modified) output string.
+     */
+    process(document: Document, output: string): string;
 }
 export namespace Postprocessor {
     export { DocumentProcessorDsl as DSL };
@@ -282,8 +296,20 @@ export namespace Postprocessor {
  * Implementations must extend IncludeProcessor.
  */
 export class IncludeProcessor extends Processor {
-    process(_document: any, _reader: any, _target: any, _attributes: any): void;
-    handles(_doc: any, _target: any): boolean;
+    /**
+     * @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: Document, reader: Reader, target: string, attributes: Record<string, string>): void;
+    /**
+     * @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: Document, target: string): boolean;
 }
 export namespace IncludeProcessor {
     export { IncludeProcessorDsl as DSL };
@@ -295,7 +321,11 @@ export namespace IncludeProcessor {
  * Implementations must extend DocinfoProcessor.
  */
 export class DocinfoProcessor extends Processor {
-    process(_document: any): void;
+    /**
+     * @param {Document} document - The document being converted.
+     * @returns {string} The docinfo content to inject into the document.
+     */
+    process(document: Document): string;
 }
 export namespace DocinfoProcessor {
     export { DocinfoProcessorDsl as DSL };
@@ -331,7 +361,13 @@ export namespace DocinfoProcessor {
 export class BlockProcessor extends Processor {
     constructor(name?: any, config?: {});
     name: any;
-    process(_parent: any, _reader: any, _attributes: any): void;
+    /**
+     * @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: AbstractBlock, reader: Reader, attributes: Record<string, unknown>): Block | void;
 }
 export namespace BlockProcessor {
     export { BlockProcessorDsl as DSL };
@@ -342,7 +378,13 @@ export namespace BlockProcessor {
 export class MacroProcessor extends Processor {
     constructor(name?: any, config?: {});
     name: any;
-    process(_parent: any, _target: any, _attributes: any): void;
+    /**
+     * @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: AbstractBlock, target: string, attributes: Record<string, unknown>): Block | Inline | void;
 }
 /**
  * BlockMacroProcessors handle block macros with a custom name.
@@ -370,6 +412,13 @@ export class MacroProcessor extends Processor {
  */
 export class BlockMacroProcessor extends MacroProcessor {
     _name: any;
+    /**
+     * @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: AbstractBlock, target: string, attributes: Record<string, unknown>): Block;
 }
 export namespace BlockMacroProcessor {
     export { MacroProcessorDsl as DSL };
@@ -407,6 +456,13 @@ export class InlineMacroProcessor extends MacroProcessor {
      * @returns {RegExp}
      */
     get regexp(): RegExp;
+    /**
+     * @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: AbstractBlock, target: string, attributes: Record<string, unknown>): Inline;
     resolveRegexp(name: any, format: any): any;
 }
 export namespace InlineMacroProcessor {
@@ -456,7 +512,7 @@ export class Registry {
      * @returns {Registry} this Registry.
      */
     activate(document: Document): Registry;
-    document: any;
+    document: import("./document.js").Document;
     /**
      * Register a Preprocessor with the extension registry.
      *
@@ -609,6 +665,12 @@ export class Registry {
      * @returns {boolean}
      */
     hasBlocks(): boolean;
+    /**
+     * Retrieve all BlockProcessor Extension proxy objects.
+     *
+     * @returns {ProcessorExtension[]}
+     */
+    blocks(): ProcessorExtension[];
     /**
      * Check whether a BlockProcessor is registered for the given name and context.
      *
@@ -639,6 +701,12 @@ export class Registry {
      * @returns {boolean}
      */
     hasBlockMacros(): boolean;
+    /**
+     * Retrieve all BlockMacroProcessor Extension proxy objects.
+     *
+     * @returns {ProcessorExtension[]}
+     */
+    blockMacros(): ProcessorExtension[];
     /**
      * Check whether a BlockMacroProcessor is registered for the given name.
      *
@@ -700,6 +768,47 @@ export class Registry {
      * @returns {ProcessorExtension} the Extension stored in the registry.
      */
     prefer(...args: any[]): ProcessorExtension;
+    /** @returns {object} the plain Object that maps names to groups for this registry. */
+    getGroups(): object;
+    /** Alias for {@link preprocessors}. */
+    getPreprocessors(): ProcessorExtension[];
+    /** Alias for {@link treeProcessors}. */
+    getTreeProcessors(): ProcessorExtension[];
+    /** Alias for {@link includeProcessors}. */
+    getIncludeProcessors(): ProcessorExtension[];
+    /** Alias for {@link postprocessors}. */
+    getPostprocessors(): ProcessorExtension[];
+    /**
+     * Alias for {@link docinfoProcessors}.
+     *
+     * @param {string|null} [location=null]
+     */
+    getDocinfoProcessors(location?: string | null): ProcessorExtension[];
+    /** Alias for {@link blocks}. */
+    getBlocks(): ProcessorExtension[];
+    /** Alias for {@link blockMacros}. */
+    getBlockMacros(): ProcessorExtension[];
+    /** Alias for {@link inlineMacros}. */
+    getInlineMacros(): ProcessorExtension[];
+    /**
+     * Alias for {@link registeredForInlineMacro}.
+     *
+     * @param {string} name
+     */
+    getInlineMacroFor(name: string): false | ProcessorExtension;
+    /**
+     * Alias for {@link registeredForBlock}.
+     *
+     * @param {string} name
+     * @param {string} context
+     */
+    getBlockFor(name: string, context: string): false | ProcessorExtension;
+    /**
+     * Alias for {@link registeredForBlockMacro}.
+     *
+     * @param {string} name
+     */
+    getBlockMacroFor(name: string): false | ProcessorExtension;
 }
 export namespace Extensions {
     /**
@@ -708,6 +817,12 @@ export namespace Extensions {
      * @returns {object}
      */
     function groups(): object;
+    /**
+     * Alias for {@link groups}.
+     *
+     * @returns {object}
+     */
+    function getGroups(): object;
     /**
      * Create a new Registry, optionally pre-populated with a named block.
      *
@@ -868,6 +983,85 @@ export namespace Extensions {
      */
     function newBlockMacroProcessor(name?: string, functions?: object, ...args: any[]): BlockMacroProcessor;
 }
+export type Document = import("./document.js").Document;
+export type AbstractBlock = import("./abstract_block.js").AbstractBlock;
+/**
+ * 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.
+ */
+export type ProcessorDslInterface = {
+    /**
+     * - Set a config option.
+     */
+    option: (key: string, value: unknown) => void;
+    /**
+     * - Register the process function.
+     */
+    process: (fn: (...args: unknown[]) => unknown) => void;
+    /**
+     * - Returns true if a process function has been registered.
+     */
+    processBlockGiven: () => boolean;
+};
+/**
+ * DSL interface for document processors (Preprocessor, TreeProcessor, Postprocessor, DocinfoProcessor).
+ */
+export type DocumentProcessorDslInterface = ProcessorDslInterface & {
+    prefer(): void;
+    prepend(): void;
+};
+/**
+ * DSL interface for syntax processors (BlockProcessor, BlockMacroProcessor, InlineMacroProcessor).
+ */
+export type SyntaxProcessorDslInterface = 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;
+};
+/**
+ * DSL interface for include processors.
+ */
+export type IncludeProcessorDslInterface = DocumentProcessorDslInterface & {
+    handles(fn: (doc: Document, target: string) => boolean): void;
+};
+/**
+ * DSL interface for docinfo processors.
+ */
+export type DocinfoProcessorDslInterface = DocumentProcessorDslInterface & {
+    atLocation(value: string): void;
+};
+/**
+ * DSL interface for block processors.
+ */
+export type BlockProcessorDslInterface = SyntaxProcessorDslInterface & {
+    contexts(...value: (string | string[])[]): void;
+    onContexts(...value: (string | string[])[]): void;
+    onContext(...value: (string | string[])[]): void;
+    bindTo(...value: (string | string[])[]): void;
+};
+/**
+ * DSL interface for macro processors (block and inline macros).
+ */
+export type MacroProcessorDslInterface = SyntaxProcessorDslInterface;
+/**
+ * DSL interface for inline macro processors.
+ */
+export type InlineMacroProcessorDslInterface = MacroProcessorDslInterface & {
+    format(value: string): void;
+    matchFormat(value: string): void;
+    usingFormat(value: string): void;
+    match(value: RegExp): void;
+};
 import { Section } from './section.js';
 import { Block } from './block.js';
 import { List } from './list.js';

package/types/index.d.cts

@@ -27,6 +27,14 @@ export function load(input: string | string[] | Buffer, options?: any): Promise<
  * @returns {Promise<Document>} - the parsed Document
  */
 export function loadFile(filename: string, options?: any): Promise<Document>;
+export type ProcessorDslInterface = import("./extensions.js").ProcessorDslInterface;
+export type DocumentProcessorDslInterface = import("./extensions.js").DocumentProcessorDslInterface;
+export type SyntaxProcessorDslInterface = import("./extensions.js").SyntaxProcessorDslInterface;
+export type IncludeProcessorDslInterface = import("./extensions.js").IncludeProcessorDslInterface;
+export type DocinfoProcessorDslInterface = import("./extensions.js").DocinfoProcessorDslInterface;
+export type BlockProcessorDslInterface = import("./extensions.js").BlockProcessorDslInterface;
+export type MacroProcessorDslInterface = import("./extensions.js").MacroProcessorDslInterface;
+export type InlineMacroProcessorDslInterface = import("./extensions.js").InlineMacroProcessorDslInterface;
 import { Document } from './document.js';
 import { convert } from './convert.js';
 import { convertFile } from './convert.js';

package/types/index.d.ts

@@ -26,6 +26,14 @@ export function load(input: string | string[] | Buffer, options?: any): Promise<
  * @returns {Promise<Document>} - the parsed Document
  */
 export function loadFile(filename: string, options?: any): Promise<Document>;
+export type ProcessorDslInterface = import("./extensions.js").ProcessorDslInterface;
+export type DocumentProcessorDslInterface = import("./extensions.js").DocumentProcessorDslInterface;
+export type SyntaxProcessorDslInterface = import("./extensions.js").SyntaxProcessorDslInterface;
+export type IncludeProcessorDslInterface = import("./extensions.js").IncludeProcessorDslInterface;
+export type DocinfoProcessorDslInterface = import("./extensions.js").DocinfoProcessorDslInterface;
+export type BlockProcessorDslInterface = import("./extensions.js").BlockProcessorDslInterface;
+export type MacroProcessorDslInterface = import("./extensions.js").MacroProcessorDslInterface;
+export type InlineMacroProcessorDslInterface = import("./extensions.js").InlineMacroProcessorDslInterface;
 import { Document } from './document.js';
 import { convert } from './convert.js';
 import { convertFile } from './convert.js';

package/types/logging.d.ts

@@ -1,3 +1,16 @@
+
+/**
+ * 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>}
+ */
+export function withLogger(logger: Logger | MemoryLogger | NullLogger, fn: () => any): Promise<any>;
 /**
  * Apply the Logging mixin to a class prototype.
  *
@@ -120,12 +133,10 @@ export class MemoryLogger {
     empty(): boolean;
 }
 /** Logger that discards all messages but still tracks the maximum severity. */
-export class NullLogger {
+export class NullLogger extends Logger {
     static create(): NullLogger;
+    constructor();
     level: number;
-    _maxSeverity: number;
-    get maxSeverity(): number;
-    getMaxSeverity(): number;
     add(severity: any): boolean;
     log(severity: any): boolean;
     debug(): boolean;