@asciidoctor/core 3.0.4 → 4.0.0-alpha.1

package/src/browser/reader.js

@@ -0,0 +1,138 @@
+// Browser-specific include path resolution for PreprocessorReader.
+//
+// This module implements the logic described in docs/modules/test/pages/browser-include-test.adoc
+// and mirrors packages/core/lib/asciidoctor/js/asciidoctor_ext/browser/reader.rb.
+//
+// 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.
+//
+// The key behavioural differences from the standard file-system resolver:
+//   - Relative targets are resolved by string concatenation against a URI context dir,
+//     not via OS path normalisation.
+//   - Absolute paths (e.g. /foo/bar) are rewritten to file:///foo/bar.
+//   - All resolved includes are fetched via the Fetch API (targetType 'uri').
+//
+// Public API
+// ----------
+// resolveBrowserIncludePath(reader, target, attrlist)
+//   reader   - a PreprocessorReader instance (provides _document, includeStack, _dir,
+//              replaceNextLine)
+//   target   - the raw include target string
+//   attrlist - the raw attribute list string (used for error-message link construction)
+//
+//   Returns [incPath, relpath] on success, where:
+//     incPath  - the absolute URI to fetch
+//     relpath  - the path relative to the document base dir (used for include tracking)
+//   Returns true/false when the include directive line has already been consumed/replaced
+//   (mirrors the Boolean return convention used by _resolveIncludePath in reader.js).
+
+import { isUriish } from '../helpers.js'
+
+/**
+ * Build the `link:...[...]` replacement text for a disallowed include.
+ * @param {object} reader
+ * @param {string} target
+ * @param {string|null} attrlist
+ * @returns {string}
+ * @internal
+ */
+function _linkReplacement(reader, target, attrlist) {
+  const doc = reader._document
+  const lt = target.includes(' ') ? `pass:c[${target}]` : target
+  const la = doc.hasAttribute('compat-mode')
+    ? (attrlist ?? '')
+    : `role=include${attrlist ? `,${attrlist}` : ''}`
+  return `link:${lt}[${la}]`
+}
+
+/**
+ * Resolve an include path in a browser (URI-based) environment.
+ *
+ * Implements the rules from the browser-include-test, in the same order:
+ *
+ * Top-level include (includeStack is empty):
+ * 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)
+ * 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
+ *
+ * Nested include (includeStack is non-empty):
+ * Rules 1–3 same as top-level.
+ * 4. parentDir == '.' → inc_path = relpath = target
+ * 5. parentDir starts with file:// OR parentDir is not a URI
+ *      → inc_path = parentDir/target
+ *      → relpath = inc_path if baseDir=='.' or inc_path not under baseDir, else path difference
+ * 6. parentDir is an absolute URL
+ *      → must descend from baseDir or allow-uri-read; else → link
+ *      → inc_path = parentDir/target
+ *      → relpath = path difference if parentDir descends from baseDir, else target
+ * @param {object} reader - a PreprocessorReader instance
+ * @param {string} target - the raw include target string
+ * @param {string|null} attrlist - the raw attribute list string
+ * @returns {[string, string]|boolean} [incPath, relpath] on success, or boolean when the line was consumed.
+ */
+export function resolveBrowserIncludePath(reader, target, attrlist) {
+  const doc = reader._document
+  const pathResolver = doc.pathResolver
+  // Normalise backslashes (Ruby: PathResolver.new('\\').posixify target)
+  const pTarget = target.replace(/\\/g, '/')
+  const baseDir = doc.baseDir
+  const topLevel = reader.includeStack.length === 0
+  const ctxDir = topLevel ? baseDir : reader._dir
+
+  let incPath, relpath
+
+  // ── Rule 1: target starts with file:// ────────────────────────────────────
+  if (pTarget.startsWith('file://')) {
+    incPath = relpath = pTarget
+
+    // ── Rule 2: target is an absolute URL (http:// / https:// / …) ───────────
+  } else if (isUriish(pTarget)) {
+    const descends = pathResolver.descendsFrom(pTarget, baseDir)
+    if (descends === false && !doc.getAttribute('allow-uri-read')) {
+      return reader.replaceNextLine(_linkReplacement(reader, target, attrlist))
+    }
+    incPath = relpath = pTarget
+
+    // ── Rule 3: target is an absolute OS path ─────────────────────────────────
+  } else if (pathResolver.absolutePath(pTarget)) {
+    incPath = relpath = `file://${pTarget.startsWith('/') ? '' : '/'}${pTarget}`
+
+    // ── Rule 4: context dir is '.' ────────────────────────────────────────────
+    // Relative path resolved by fetch relative to window.location / request origin.
+  } else if (ctxDir === '.') {
+    incPath = relpath = pTarget
+
+    // ── Rule 5: context dir is file:// OR a non-URI (regular OS path) ─────────
+  } else if (ctxDir.startsWith('file://') || !isUriish(ctxDir)) {
+    incPath = `${ctxDir}/${pTarget}`
+    if (topLevel) {
+      relpath = pTarget
+    } else {
+      const offset = pathResolver.descendsFrom(incPath, baseDir)
+      if (baseDir === '.' || offset === false) {
+        relpath = incPath
+      } else {
+        relpath = incPath.slice(offset)
+      }
+    }
+
+    // ── Rule 6: context dir is an absolute URL ────────────────────────────────
+  } else if (topLevel) {
+    incPath = `${ctxDir}/${(relpath = pTarget)}`
+  } else {
+    // Nested include: context dir is an absolute URL.
+    const ctxDescends = pathResolver.descendsFrom(ctxDir, baseDir)
+    if (ctxDescends !== false || doc.getAttribute('allow-uri-read')) {
+      incPath = `${ctxDir}/${pTarget}`
+      relpath = ctxDescends !== false ? incPath.slice(ctxDescends) : pTarget
+    } else {
+      return reader.replaceNextLine(_linkReplacement(reader, target, attrlist))
+    }
+  }
+
+  return [incPath, relpath]
+}

package/src/browser.js

@@ -0,0 +1,121 @@
+import packageJson from '../package.json' with { type: 'json' }
+import { load as _load } from './load.js'
+import { convert } from './convert.js'
+import {
+  Document,
+  DocumentTitle,
+  Author,
+  Footnote,
+  ImageReference,
+  RevisionInfo,
+} from './document.js'
+import { Logger, LoggerManager, MemoryLogger, NullLogger } from './logging.js'
+import { SafeMode, ContentModel } from './constants.js'
+import { Timings } from './timings.js'
+import { AbstractNode } from './abstract_node.js'
+import { AbstractBlock } from './abstract_block.js'
+import {
+  Registry,
+  Processor,
+  ProcessorExtension,
+  Preprocessor,
+  TreeProcessor,
+  Postprocessor,
+  IncludeProcessor,
+  DocinfoProcessor,
+  BlockProcessor,
+  InlineMacroProcessor,
+  BlockMacroProcessor,
+  Extensions,
+} from './extensions.js'
+import {
+  Converter,
+  DefaultFactory as DefaultConverterFactory,
+} from './converter.js'
+import { Inline } from './inline.js'
+import { Block } from './block.js'
+import { List, ListItem } from './list.js'
+import { Section } from './section.js'
+import { Cursor, Reader } from './reader.js'
+import Html5Converter from './converter/html5.js'
+import {
+  SyntaxHighlighter,
+  SyntaxHighlighterBase,
+  DefaultFactory as DefaultSyntaxHighlighterFactory,
+} from './syntax_highlighter.js'
+
+const ASCIIDOCTOR_CORE_VERSION = '2.0.26'
+
+/**
+ * Get the version of Asciidoctor.js.
+ *
+ * @returns {string} - the version of Asciidoctor.js
+ */
+export function getVersion() {
+  return packageJson.version
+}
+
+/**
+ * Get Asciidoctor core version number.
+ *
+ * @returns {string} - the version of Asciidoctor core (Ruby)
+ */
+export function getCoreVersion() {
+  return ASCIIDOCTOR_CORE_VERSION
+}
+
+/**
+ * Parse the AsciiDoc source input into a Document.
+ *
+ * @param {string|string[]|Buffer} input - the AsciiDoc source as a String, String Array, or Buffer
+ * @param {Object} [options={}] - a plain object of options to control processing
+ * @returns {Promise<Document>} - the parsed Document
+ */
+export async function load(input, options = {}) {
+  return _load(input, options)
+}
+
+export { convert }
+
+export {
+  Document,
+  DocumentTitle,
+  Author,
+  Footnote,
+  ImageReference,
+  RevisionInfo,
+  Logger,
+  AbstractNode,
+  AbstractBlock,
+  Inline,
+  Block,
+  List,
+  ListItem,
+  Section,
+  Reader,
+  SyntaxHighlighterBase,
+  LoggerManager,
+  MemoryLogger,
+  NullLogger,
+  SafeMode,
+  ContentModel,
+  Timings,
+  Registry,
+  Processor,
+  ProcessorExtension,
+  Preprocessor,
+  TreeProcessor,
+  Postprocessor,
+  IncludeProcessor,
+  DocinfoProcessor,
+  BlockProcessor,
+  InlineMacroProcessor,
+  BlockMacroProcessor,
+  Extensions,
+  Cursor,
+  Converter as ConverterFactory,
+  DefaultConverterFactory,
+  DefaultSyntaxHighlighterFactory,
+  Html5Converter,
+  SyntaxHighlighter,
+}

package/src/callouts.js

@@ -0,0 +1,85 @@
+// ESM conversion of callouts.rb
+
+/** Maintains a catalog of callouts and their associations. */
+export class Callouts {
+  constructor() {
+    /** @internal */
+    this._lists = []
+    /** @internal */
+    this._listIndex = 0
+    this.nextList()
+  }
+
+  /**
+   * Register a new callout for the given list item ordinal.
+   * @param {number} liOrdinal - The 1-based ordinal of the list item.
+   * @returns {string} The unique id of this callout (e.g. 'CO1-1').
+   */
+  register(liOrdinal) {
+    const id = this._generateNextCalloutId()
+    this.getCurrentList().push({ ordinal: parseInt(liOrdinal, 10), id })
+    this._coIndex++
+    return id
+  }
+
+  /**
+   * Get the next callout id in document order (used during conversion).
+   * @returns {string|null} The unique id of the next callout, or null.
+   */
+  readNextId() {
+    const list = this.getCurrentList()
+    const id = this._coIndex <= list.length ? list[this._coIndex - 1].id : null
+    this._coIndex++
+    return id
+  }
+
+  /**
+   * Get a space-separated list of callout ids for the given list item.
+   * @param {number} liOrdinal - The 1-based ordinal of the list item.
+   * @returns {string} Space-separated callout ids.
+   */
+  getCalloutIds(liOrdinal) {
+    const list = this.getCurrentList()
+    return list
+      .filter((item) => item.ordinal === liOrdinal)
+      .map((item) => item.id)
+      .join(' ')
+  }
+
+  /** @returns {Array<{ordinal: number, id: string}>} The callout objects at the current list index. */
+  getCurrentList() {
+    return this._lists[this._listIndex - 1]
+  }
+
+  /** @returns {Array<Array<{ordinal: number, id: string}>>} All callout lists in the document. */
+  getLists() {
+    return this._lists
+  }
+
+  /** @returns {number} The 1-based index of the current callout list. */
+  getListIndex() {
+    return this._listIndex
+  }
+
+  /** Advance to the next callout list in the document. */
+  nextList() {
+    this._listIndex++
+    if (this._lists.length < this._listIndex) this._lists.push([])
+    /** @internal */
+    this._coIndex = 1
+  }
+
+  /** Rewind the list pointer to the beginning (switching parse → convert). */
+  rewind() {
+    this._listIndex = 1
+    this._coIndex = 1
+  }
+
+  /**
+   * @internal
+   * @private
+   */
+  _generateNextCalloutId() {
+    return `CO${this._listIndex}-${this._coIndex}`
+  }
+}

package/src/compliance.js

@@ -0,0 +1,54 @@
+// ESM conversion of the Compliance module (defined inside asciidoctor.rb).
+//
+// Ruby-to-JavaScript notes:
+//   - The Ruby module uses dynamic attr_accessor generation via `define`.
+//     In JS each flag is a plain enumerable property on the exported object.
+//   - The `keys` Set is retained so callers can enumerate all known flags
+//     (used e.g. by the options-merging code in Document).
+//   - All default values match the Asciidoctor defaults (not the "AsciiDoc
+//     compliance values" documented in comments — those differ intentionally).
+
+export const Compliance = {
+  keys: new Set([
+    'blockTerminatesParagraph',
+    'strictVerbatimParagraphs',
+    'underlineStyleSectionTitles',
+    'unwrapStandalonePreamble',
+    'attributeMissing',
+    'attributeUndefined',
+    'shorthandPropertySyntax',
+    'naturalXrefs',
+    'uniqueIdStartIndex',
+    'markdownSyntax',
+  ]),
+
+  /** AsciiDoc terminates paragraphs adjacent to block content (delimiter or block attribute list). Compliance value: true */
+  blockTerminatesParagraph: true,
+
+  /** AsciiDoc does not parse paragraphs with a verbatim style as verbatim content. Compliance value: false (Asciidoctor default: true) */
+  strictVerbatimParagraphs: true,
+
+  /** AsciiDoc supports both atx (single-line) and setext (underlined) section titles. Compliance value: true */
+  underlineStyleSectionTitles: true,
+
+  /** Asciidoctor will unwrap the content in a preamble if the document has a title and no sections. Compliance value: false (Asciidoctor default: true) */
+  unwrapStandalonePreamble: true,
+
+  /** AsciiDoc drops lines that contain references to missing attributes. Possible values: 'skip', 'drop', 'drop-line', 'warn'. Compliance value: 'drop-line' (Asciidoctor default: 'skip') */
+  attributeMissing: 'skip',
+
+  /** AsciiDoc drops lines that contain an attribute unassignment. Compliance value: 'drop-line' */
+  attributeUndefined: 'drop-line',
+
+  /** Shorthand syntax for id, role and options on blocks (e.g. #id.role%opt). Compliance value: false (Asciidoctor default: true) */
+  shorthandPropertySyntax: true,
+
+  /** Resolve cross-reference targets by matching reftext or title. Compliance value: false (Asciidoctor default: true) */
+  naturalXrefs: true,
+
+  /** Starting counter when generating a unique id on conflict. Compliance value: 2 */
+  uniqueIdStartIndex: 2,
+
+  /** Recognize commonly-used Markdown syntax where it does not conflict. Compliance value: false (Asciidoctor default: true) */
+  markdownSyntax: true,
+}