asciidoctor 4.0.0-alpha.6 → 4.0.1

package/lib/cli.js

@@ -126,6 +126,13 @@ const BASE_OPTION_DEFINITIONS = {
       'require the specified library before executing the processor (repeatable)',
     metavar: '<library>',
   },
+  extension: {
+    type: 'string',
+    multiple: true,
+    describe:
+      'require the specified extension and register it before executing the processor (repeatable)',
+    metavar: '<extension>',
+  },
   version: {
     type: 'boolean',
     short: 'V',
@@ -351,6 +358,7 @@ export class Invoker {
     }
 
     this._prepareProcessor(values)
+    this._prepareExtensions(values)
     const { options, failureLevel } = this.options
 
     const logger = LoggerManager.getLogger()
@@ -443,9 +451,25 @@ CLI version ${pkg.version}`
     const requirePaths = values.require
     if (!requirePaths) return
     for (const requirePath of requirePaths) {
-      const lib = requireLibrary(requirePath)
-      if (lib && typeof lib.register === 'function') {
-        lib.register(Extensions)
+      requireLibrary(requirePath)
+    }
+  }
+
+  /** @internal */
+  _prepareExtensions(values) {
+    const extensionPaths = values.extension
+    if (!extensionPaths || extensionPaths.length === 0) return
+    const logger = LoggerManager.getLogger()
+    for (const extensionPath of extensionPaths) {
+      const lib = requireLibrary(extensionPath)
+      if (typeof lib?.register === 'function') {
+        Extensions.register(function () {
+          lib.register(this)
+        })
+      } else {
+        logger.warn(
+          `Extension '${extensionPath}' does not export a register function and will be ignored.`
+        )
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "asciidoctor",
-  "version": "4.0.0-alpha.6",
+  "version": "4.0.1",
   "description": "A JavaScript AsciiDoc processor powered by Asciidoctor",
   "type": "module",
   "main": "index.js",
@@ -60,7 +60,7 @@
   },
   "homepage": "https://github.com/asciidoctor/asciidoctor.js",
   "dependencies": {
-    "@asciidoctor/core": "4.0.0-alpha.6"
+    "@asciidoctor/core": "4.0.1"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.13",
@@ -73,6 +73,6 @@
     "pug": "^3.0.3"
   },
   "volta": {
-    "node": "24.16.0"
+    "node": "24.18.0"
   }
 }

package/types/extensions.d.ts

@@ -38,7 +38,25 @@ export namespace SyntaxProcessorDsl {
     function resolvesAttributes(...args: any[]): void;
 }
 export namespace IncludeProcessorDsl {
-    function handles(...args: any[]): any;
+    /**
+     * @overload
+     * @param {(target: string) => boolean} fn - Predicate that receives only the include target.
+     * @returns {void}
+     */
+    function handles(fn: (target: string) => boolean): void;
+    /**
+     * @overload
+     * @param {(doc: Document, target: string) => boolean} fn - Predicate that receives the document and the include target.
+     * @returns {void}
+     */
+    function handles(fn: (doc: Document, target: string) => boolean): void;
+    /**
+     * @overload
+     * @param {Document} doc - The document being parsed.
+     * @param {string} target - The include target.
+     * @returns {boolean}
+     */
+    function handles(doc: Document, target: string): boolean;
 }
 export namespace DocinfoProcessorDsl {
     function atLocation(value: any): void;
@@ -486,14 +504,38 @@ export class ProcessorExtension extends Extension {
     processMethod: any;
 }
 /**
- * A Group registers one or more extensions with a Registry.
+ * A Group bundles one or more extension registrations that are re-executed on
+ * every document conversion, making the registry safe to reuse.
  *
- * Subclass Group and pass the subclass to Extensions.register(), or call
- * the static register() method directly.
+ * Subclass Group, override {@link Group#activate}, and either call
+ * {@link Group.register} to add it globally or pass the subclass to
+ * {@link Extensions.create} / {@link Extensions.register}.
+ *
+ * @example
+ * class MyGroup extends Group {
+ *   activate (registry) {
+ *     registry.preprocessor(MyPreprocessor)
+ *   }
+ * }
+ * MyGroup.register()
  */
 export class Group {
-    static register(name?: any): void;
-    activate(_registry: any): void;
+    /**
+     * Register this Group class globally under the given name.
+     *
+     * Equivalent to calling `Extensions.register(name, this)`.
+     *
+     * @param {string|null} [name] - Optional name for the group.
+     */
+    static register(name?: string | null): void;
+    /**
+     * Called by {@link Registry#activate} on every document conversion.
+     *
+     * Override this method to register extensions with the provided registry.
+     *
+     * @param {Registry} _registry - The registry to register extensions with.
+     */
+    activate(_registry: Registry): void;
 }
 /**
  * The primary entry point into the extension system.
@@ -501,6 +543,18 @@ export class Group {
  * Registry holds the extensions which have been registered and activated, has
  * methods for registering or defining a processor and looks up extensions
  * stored in the registry during parsing.
+ *
+ * A registry can be reused across multiple conversions. Extensions registered
+ * via a group block (passed to {@link Extensions.create} or
+ * {@link Extensions.register}) are re-executed on every activation. Extensions
+ * registered directly on the registry instance (e.g. `registry.preprocessor(fn)`)
+ * are preserved across activations.
+ *
+ * @example
+ * const registry = Extensions.create('my-ext', function () {
+ *   this.preprocessor(function () { ... })
+ * })
+ * // registry can be passed to multiple conversions safely
  */
 export class Registry {
     constructor(groups?: {});
@@ -826,6 +880,13 @@ export namespace Extensions {
     /**
      * Create a new Registry, optionally pre-populated with a named block.
      *
+     * When a `block` is provided it is stored as a group and re-executed on every
+     * activation, making the registry safe to reuse across multiple conversions.
+     * Without a `block`, any extensions registered directly on the returned registry
+     * (e.g. `registry.preprocessor(fn)`) are stored in transient state that is
+     * cleared on every activation — those registrations will be lost from the second
+     * conversion onwards. Prefer the block form when the registry may be reused.
+     *
      * @param {string|null} [name=null] - Optional name for the group; auto-generated if omitted.
      * @param {Function|null} [block=null] - Optional function to register as the group.
      * @returns {Registry}
@@ -1032,6 +1093,7 @@ export type SyntaxProcessorDslInterface = ProcessorDslInterface & {
  * DSL interface for include processors.
  */
 export type IncludeProcessorDslInterface = DocumentProcessorDslInterface & {
+    handles(fn: (target: string) => boolean): void;
     handles(fn: (doc: Document, target: string) => boolean): void;
 };
 /**

package/types/index.d.cts

@@ -54,6 +54,7 @@ import { Section } from './section.js';
 import { Reader } from './reader.js';
 import { SyntaxHighlighterBase } from './syntax_highlighter.js';
 import { LoggerManager } from './logging.js';
+import { LogMessage } from './logging.js';
 import { MemoryLogger } from './logging.js';
 import { NullLogger } from './logging.js';
 import { HttpCache } from './http_cache.js';
@@ -83,4 +84,4 @@ import { deriveBackendTraits } from './converter.js';
 import { DefaultFactory as DefaultSyntaxHighlighterFactory } from './syntax_highlighter.js';
 import Html5Converter from './converter/html5.js';
 import { SyntaxHighlighter } from './syntax_highlighter.js';
-export { convert, convertFile, Document, DocumentTitle, Author, Footnote, ImageReference, RevisionInfo, Logger, AbstractNode, AbstractBlock, Inline, Block, List, ListItem, Section, Reader, SyntaxHighlighterBase, LoggerManager, MemoryLogger, NullLogger, HttpCache, MemoryHttpCache, HttpCacheManager, 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 };
+export { convert, convertFile, Document, DocumentTitle, Author, Footnote, ImageReference, RevisionInfo, Logger, AbstractNode, AbstractBlock, Inline, Block, List, ListItem, Section, Reader, SyntaxHighlighterBase, LoggerManager, LogMessage, MemoryLogger, NullLogger, HttpCache, MemoryHttpCache, HttpCacheManager, 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/types/index.d.ts

@@ -53,6 +53,7 @@ import { Section } from './section.js';
 import { Reader } from './reader.js';
 import { SyntaxHighlighterBase } from './syntax_highlighter.js';
 import { LoggerManager } from './logging.js';
+import { LogMessage } from './logging.js';
 import { MemoryLogger } from './logging.js';
 import { NullLogger } from './logging.js';
 import { HttpCache } from './http_cache.js';
@@ -82,4 +83,4 @@ import { deriveBackendTraits } from './converter.js';
 import { DefaultFactory as DefaultSyntaxHighlighterFactory } from './syntax_highlighter.js';
 import Html5Converter from './converter/html5.js';
 import { SyntaxHighlighter } from './syntax_highlighter.js';
-export { convert, convertFile, Document, DocumentTitle, Author, Footnote, ImageReference, RevisionInfo, Logger, AbstractNode, AbstractBlock, Inline, Block, List, ListItem, Section, Reader, SyntaxHighlighterBase, LoggerManager, MemoryLogger, NullLogger, HttpCache, MemoryHttpCache, HttpCacheManager, 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 };
+export { convert, convertFile, Document, DocumentTitle, Author, Footnote, ImageReference, RevisionInfo, Logger, AbstractNode, AbstractBlock, Inline, Block, List, ListItem, Section, Reader, SyntaxHighlighterBase, LoggerManager, LogMessage, MemoryLogger, NullLogger, HttpCache, MemoryHttpCache, HttpCacheManager, 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/types/logging.d.ts

@@ -95,22 +95,66 @@ export namespace Logger {
     export { BasicFormatter };
     export namespace AutoFormattingMessage {
         /**
-         * Attach auto-formatting to any plain object carrying { text, source_location }.
-         * @param {{text: string, source_location?: string}} obj
+         * Attach auto-formatting to any plain object carrying
+         * { text, source_location, include_location }.
+         *
+         * The location(s) are rendered only by inspect()/toString() (used when a
+         * stderr Logger formats the line); the structured `source_location` /
+         * `include_location` remain on the object so a MemoryLogger can record them
+         * on the resulting LogMessage without duplicating them inside `text`.
+         * @param {{text: string, source_location?: any, include_location?: any}} obj
          * @returns {typeof obj} The same object with inspect() and toString() added.
          */
         function attach(obj: {
             text: string;
-            source_location?: string;
+            source_location?: any;
+            include_location?: any;
         }): typeof obj;
     }
 }
+/** Wrapper stored by MemoryLogger; provides getSeverity/getText/getSourceLocation. */
+export class LogMessage {
+    /**
+     * @param {string} severity - Severity label, e.g. 'ERROR'.
+     * @param {string|{text: string, source_location?: import('./reader.js').Cursor}|null} message
+     */
+    constructor(severity: string, message: string | {
+        text: string;
+        source_location?: import("./reader.js").Cursor;
+    } | null);
+    message: string | {
+        text: string;
+        source_location?: import("./reader.js").Cursor;
+    };
+    /** @type {string} */
+    severity: string;
+    /** @type {string} */
+    text: string;
+    /** @type {import('./reader.js').Cursor|null} */
+    sourceLocation: import("./reader.js").Cursor | null;
+    /**
+     * @returns {string} The severity label, e.g. 'ERROR'.
+     */
+    getSeverity(): string;
+    /**
+     * @returns {string} The message text.
+     */
+    getText(): string;
+    /**
+     * @returns {import('./reader.js').Cursor|undefined} The source location, if any.
+     */
+    getSourceLocation(): import("./reader.js").Cursor | undefined;
+}
 /** In-memory logger that stores all log messages for later inspection. */
 export class MemoryLogger {
     static create(): MemoryLogger;
     level: number;
-    messages: any[];
-    getMessages(): any[];
+    /** @type {LogMessage[]} */
+    messages: LogMessage[];
+    /**
+     * @returns {LogMessage[]} The log messages recorded so far, in order.
+     */
+    getMessages(): LogMessage[];
     getMaxSeverity(): number;
     add(severity: any, message?: any, progname?: any): boolean;
     debug(msg: any, pn: any): boolean;

package/types/reader.d.ts

@@ -123,13 +123,13 @@ export class Reader {
     createLogMessage(text: any, context?: {}): any;
     get logger(): any;
     /** @param {string} msg @param {{ sourceLocation?: any, includeLocation?: any }} [opts] */
-    _logWarn(msg: string, { sourceLocation, includeLocation }?: {
+    _logWarn(msg: string, opts?: {
         sourceLocation?: any;
         includeLocation?: any;
     }): void;
     _logError(msg: any, opts?: {}): void;
     /** @param {string} msg @param {{ sourceLocation?: any }} [opts] */
-    _logInfo(msg: string, { sourceLocation }?: {
+    _logInfo(msg: string, opts?: {
         sourceLocation?: any;
     }): void;
 }

package/types/substitutors.d.ts

@@ -4,9 +4,9 @@ export namespace Substitutors {
      *
      * @param {string|string[]} text - The text to process; must not be null.
      * @param {string[]} [subs=NORMAL_SUBS] - The substitutions to perform.
-     * @returns {string|string[]} Text with substitutions applied.
+     * @returns {Promise<string|string[]>} Text with substitutions applied.
      */
-    function applySubs(text: string | string[], subs?: string[]): string | string[];
+    function applySubs(text: string | string[], subs?: string[]): Promise<string | string[]>;
     /** Apply normal substitutions (alias for applySubs with default args). */
     function applyNormalSubs(text: any): Promise<string | string[]>;
     /** Apply substitutions for header metadata and attribute assignments.
@@ -32,9 +32,9 @@ export namespace Substitutors {
      * Substitute quoted text (emphasis, strong, monospaced, etc.)
      *
      * @param {string} text
-     * @returns {string}
+     * @returns {Promise<string>}
      */
-    function subQuotes(text: string): string;
+    function subQuotes(text: string): Promise<string>;
     /**
      * Substitute attribute references in the specified text.
      *
@@ -54,39 +54,39 @@ export namespace Substitutors {
      * Substitute inline macros (links, images, etc.)
      *
      * @param {string} text
-     * @returns {string}
+     * @returns {Promise<string>}
      */
-    function subMacros(text: string): string;
+    function subMacros(text: string): Promise<string>;
     /**
      * Substitute post replacements (hard line breaks).
      *
      * @param {string} text
-     * @returns {string}
+     * @returns {Promise<string>}
      */
-    function subPostReplacements(text: string): string;
+    function subPostReplacements(text: string): Promise<string>;
     /**
      * Apply verbatim substitutions on source.
      *
      * @param {string} source
      * @param {boolean} processCallouts
-     * @returns {string}
+     * @returns {Promise<string>}
      */
-    function subSource(source: string, processCallouts: boolean): string;
+    function subSource(source: string, processCallouts: boolean): Promise<string>;
     /**
      * Substitute callout source references.
      *
      * @param {string} text
-     * @returns {string}
+     * @returns {Promise<string>}
      */
-    function subCallouts(text: string): string;
+    function subCallouts(text: string): Promise<string>;
     /**
      * Highlight (colorize) the source code using a syntax highlighter.
      *
      * @param {string} source
      * @param {boolean} processCallouts
-     * @returns {string}
+     * @returns {Promise<string>}
      */
-    function highlightSource(source: string, processCallouts: boolean): string;
+    function highlightSource(source: string, processCallouts: boolean): Promise<string>;
     /**
      * Resolve line numbers to highlight from a test string.
      *
@@ -107,9 +107,9 @@ export namespace Substitutors {
      * Restore passthrough text by reinserting into placeholder positions.
      *
      * @param {string} text
-     * @returns {string}
+     * @returns {Promise<string>}
      */
-    function restorePassthroughs(text: string): string;
+    function restorePassthroughs(text: string): Promise<string>;
     /**
      * Resolve the list of comma-delimited subs against the possible options.
      *
@@ -143,9 +143,9 @@ export namespace Substitutors {
      * @param {string} attrlist
      * @param {string[]} [posattrs=[]]
      * @param {Object} [opts={}]
-     * @returns {Object}
+     * @returns {Promise<Object>}
      */
-    function parseAttributes(attrlist: string, posattrs?: string[], opts?: any): any;
+    function parseAttributes(attrlist: string, posattrs?: string[], opts?: any): Promise<any>;
     function extractAttributesFromText(text: any, defaultText?: any): Promise<any[]>;
     function extractCallouts(source: any): any[];
     function restoreCallouts(source: any, calloutMarks: any, sourceOffset?: any): Promise<string>;