@asciidoctor/core 4.0.0 → 4.0.2

package/src/reader.js

@@ -675,22 +675,34 @@ export class Reader {
   }
 
   /** @param {string} msg @param {{ sourceLocation?: any, includeLocation?: any }} [opts] */
-  _logWarn(msg, { sourceLocation, includeLocation } = {}) {
-    let text = sourceLocation ? `${sourceLocation.lineInfo}: ${msg}` : msg
-    if (includeLocation) text += ` (${includeLocation.lineInfo})`
-    this.logger.warn(text)
+  _logWarn(msg, opts = {}) {
+    this.logger.warn(this._messageWithContext(msg, opts))
   }
   _logError(msg, opts = {}) {
-    let text = opts.sourceLocation
-      ? `${opts.sourceLocation.lineInfo}: ${msg}`
-      : msg
-    if (opts.includeLocation) text += ` (${opts.includeLocation.lineInfo})`
-    this.logger.error(text)
+    this.logger.error(this._messageWithContext(msg, opts))
   }
   /** @param {string} msg @param {{ sourceLocation?: any }} [opts] */
-  _logInfo(msg, { sourceLocation } = {}) {
-    const text = sourceLocation ? `${sourceLocation.lineInfo}: ${msg}` : msg
-    this.logger.info(text)
+  _logInfo(msg, opts = {}) {
+    this.logger.info(this._messageWithContext(msg, opts))
+  }
+
+  /**
+   * Build an auto-formatting message that keeps the cursor as a structured
+   * source_location (rather than baking it into the text). When displayed by a
+   * stderr Logger the location is rendered as a "<path>: line <N>: " prefix, but
+   * a MemoryLogger records it separately on the LogMessage so consumers can call
+   * getSourceLocation(). Mirrors Ruby's Logging#message_with_context.
+   * @param {string} msg
+   * @param {{ sourceLocation?: any, includeLocation?: any }} [opts]
+   * @internal
+   */
+  _messageWithContext(msg, { sourceLocation, includeLocation } = {}) {
+    if (!sourceLocation && !includeLocation) return msg
+    return Logger.AutoFormattingMessage.attach({
+      text: msg,
+      source_location: sourceLocation ?? null,
+      include_location: includeLocation ?? null,
+    })
   }
 }
 
@@ -1448,7 +1460,7 @@ export class PreprocessorReader extends Reader {
     }
 
     if (isUriish(target) || typeof this._dir !== 'string') {
-      if (!doc.getAttribute('allow-uri-read')) {
+      if (!doc.hasAttribute('allow-uri-read')) {
         this._logWarn(
           `cannot include contents of URI: ${target} (allow-uri-read attribute not enabled)`,
           { sourceLocation: this.cursor }

package/src/substitutors.js

@@ -176,7 +176,7 @@ export const 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.
    */
   async applySubs(text, subs = NORMAL_SUBS) {
     const isEmpty = Array.isArray(text) ? text.length === 0 : text.length === 0
@@ -290,7 +290,7 @@ export const Substitutors = {
    * Substitute quoted text (emphasis, strong, monospaced, etc.)
    *
    * @param {string} text
-   * @returns {string}
+   * @returns {Promise<string>}
    */
   async subQuotes(text) {
     const compat = this.document.compatMode
@@ -462,7 +462,7 @@ export const Substitutors = {
    * Substitute inline macros (links, images, etc.)
    *
    * @param {string} text
-   * @returns {string}
+   * @returns {Promise<string>}
    */
   async subMacros(text) {
     const foundSquareBracket = text.includes('[')
@@ -1357,7 +1357,7 @@ export const Substitutors = {
    * Substitute post replacements (hard line breaks).
    *
    * @param {string} text
-   * @returns {string}
+   * @returns {Promise<string>}
    */
   async subPostReplacements(text) {
     if (
@@ -1395,7 +1395,7 @@ export const Substitutors = {
    *
    * @param {string} source
    * @param {boolean} processCallouts
-   * @returns {string}
+   * @returns {Promise<string>}
    */
   async subSource(source, processCallouts) {
     return processCallouts
@@ -1407,7 +1407,7 @@ export const Substitutors = {
    * Substitute callout source references.
    *
    * @param {string} text
-   * @returns {string}
+   * @returns {Promise<string>}
    */
   async subCallouts(text) {
     const calloutRx = this.hasAttribute('line-comment')
@@ -1436,7 +1436,7 @@ export const Substitutors = {
    *
    * @param {string} source
    * @param {boolean} processCallouts
-   * @returns {string}
+   * @returns {Promise<string>}
    */
   async highlightSource(source, processCallouts) {
     const syntaxHl = this.document.syntaxHighlighter
@@ -1782,7 +1782,7 @@ export const Substitutors = {
    * Restore passthrough text by reinserting into placeholder positions.
    *
    * @param {string} text
-   * @returns {string}
+   * @returns {Promise<string>}
    */
   async restorePassthroughs(text) {
     if (!text.includes(PASS_START)) return text
@@ -1974,7 +1974,7 @@ export const Substitutors = {
    * @param {string} attrlist
    * @param {string[]} [posattrs=[]]
    * @param {Object} [opts={}]
-   * @returns {Object}
+   * @returns {Promise<Object>}
    */
   async parseAttributes(attrlist, posattrs = [], opts = {}) {
     if (!attrlist || attrlist.length === 0) return {}

package/types/abstract_node.d.ts

@@ -234,9 +234,10 @@ export abstract class AbstractNode {
      * Construct a URI reference or data URI to the target image.
      *
      * If the target image is already a URI it is left untouched (unless data-uri
-     * conversion is requested). The image is resolved relative to the directory
-     * named by assetDirKey. When data-uri is enabled and the safe level permits,
-     * the image is embedded as a Base64 data URI.
+     * conversion is requested). If the target image is a data URI, then it is
+     * already an embedded image, so it is returned as-is. The image is resolved
+     * relative to the directory named by assetDirKey. When data-uri is enabled and
+     * the safe level permits, the image is embedded as a Base64 data URI.
      *
      * NOTE: When the document has both 'data-uri' and 'allow-uri-read' enabled
      * and the resolved image URL is a remote URI, this method returns a Promise

package/types/document.d.ts

@@ -469,10 +469,26 @@ export class Document extends AbstractBlock<string> {
      * @returns {string[]} The list of substitutions to apply.
      */
     private _resolveDocinfoSubs;
+    /**
+     * @private
+     * Restore the document attributes to a previously captured snapshot, discarding any
+     * body-level (re)assignments replayed while pre-computing text. Mirrors Ruby's
+     * restore_attributes-before-convert invariant.
+     * @param {Object} snapshot - The attributes snapshot to restore.
+     */
+    private _restoreAttributeSnapshot;
     /**
      * @private
      * Walk the block tree and pre-compute all async text values.
      * Handles titles (AbstractBlock), list item text, table cell text, and reftexts.
+     *
+     * Runs in two passes (see {@link parse}): with `resolveContent` false only titles and
+     * reftexts are substituted (so the reftext→id map can be built); with `resolveContent`
+     * true the list item / table cell / dlist text is substituted, resolving any natural
+     * cross-references against the now-complete map. Title/reftext pre-computation is
+     * idempotent (results are cached), so running it in both passes is a no-op the second time.
+     * @param {AbstractBlock} block - The block to resolve.
+     * @param {boolean} resolveContent - Whether to substitute list item / cell / dlist text.
      */
     private _resolveAllTexts;
     /**

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>;