asciidoctor 4.0.0-alpha.4 → 4.0.0-alpha.6

package/index.js

@@ -1,2 +1 @@
-export { default } from '@asciidoctor/core'
 export * from '@asciidoctor/core'

package/lib/cli.js

@@ -25,120 +25,127 @@ const FAILURE_LEVELS = {
 
 const DOT_RELATIVE_RX = new RegExp(`^\\.{1,2}[/${sep.replace('\\', '\\\\')}]`)
 
-const HELP_TEXT = `asciidoctor [options...] files...
+const HELP_PREAMBLE = `asciidoctor [options...] files...
 Translate the AsciiDoc source file or file(s) into the backend output format (e.g., HTML 5, DocBook 5, etc.)
 By default, the output is written to a file with the basename of the source file and the appropriate extension
 
-Options:
-  -b, --backend <backend>           set output format backend
-  -d, --doctype <doctype>           document type [article, book, manpage, inline]
-  -o, --out-file <file>             output file; use '' or '-' for STDOUT
-  -S, --safe-mode <mode>            safe mode level [unsafe, safe, server, secure]
-  -e, --embedded                    suppress enclosing document structure
-  -s, --no-header-footer            suppress enclosing document structure
-  -n, --section-numbers             auto-number section titles in the HTML backend
-  -B, --base-dir <dir>              base directory containing the document and resources
-  -D, --destination-dir <dir>       destination output directory
-      --failure-level <level>       minimum logging level that triggers non-zero exit code [INFO, WARN, ERROR, FATAL]
-  -q, --quiet                       suppress warnings
-      --trace                       include backtrace information on errors
-  -v, --verbose                     enable verbose mode
-  -t, --timings                     enable timings mode
-  -T, --template-dir <dir>          directory with custom converter templates (repeatable)
-  -E, --template-engine <engine>    template engine to use for custom converter templates
-  -a, --attribute <key[=value]>     document attribute to set (repeatable)
-  -r, --require <library>           require the specified library before executing the processor (repeatable)
-  -V, --version                     display the version and runtime environment
-      --help [syntax]               show this help; show AsciiDoc syntax overview if topic is 'syntax'`
-
-function parseCliArgs(argv) {
-  const args = argv.slice(2)
-  const { values, positionals } = parseArgs({
-    args,
-    allowPositionals: true,
-    strict: false,
-    options: {
-      backend: { type: 'string', short: 'b' },
-      doctype: { type: 'string', short: 'd' },
-      'out-file': { type: 'string', short: 'o' },
-      'safe-mode': { type: 'string', short: 'S' },
-      embedded: { type: 'boolean', short: 'e' },
-      'no-header-footer': { type: 'boolean', short: 's' },
-      'section-numbers': { type: 'boolean', short: 'n' },
-      'base-dir': { type: 'string', short: 'B' },
-      'destination-dir': { type: 'string', short: 'D' },
-      'failure-level': { type: 'string' },
-      quiet: { type: 'boolean', short: 'q' },
-      trace: { type: 'boolean' },
-      verbose: { type: 'boolean', short: 'v' },
-      timings: { type: 'boolean', short: 't' },
-      'template-dir': { type: 'string', short: 'T', multiple: true },
-      'template-engine': { type: 'string', short: 'E' },
-      attribute: { type: 'string', short: 'a', multiple: true },
-      require: { type: 'string', short: 'r', multiple: true },
-      version: { type: 'boolean', short: 'V' },
-      help: { type: 'boolean' },
-    },
-  })
-  return { values, positionals, args }
-}
+Options:`
 
-function buildOptions(values, extraAttrs = []) {
-  const {
-    backend,
-    doctype,
-    'safe-mode': safeMode,
-    embedded,
-    'no-header-footer': noHeaderFooter,
-    'section-numbers': sectionNumbers,
-    'base-dir': baseDir,
-    'destination-dir': destinationDir,
-    'out-file': outFile,
-    'template-dir': templateDir,
-    'template-engine': templateEngine,
-    quiet,
-    verbose,
-    timings,
-    trace,
-    'failure-level': failureLevelStr = 'FATAL',
-    attribute: cliAttributes,
-  } = values
-
-  const level = failureLevelStr.toUpperCase()
-  const failureLevel = FAILURE_LEVELS[level] ?? FAILURE_LEVELS.FATAL
-
-  const attributes = [...extraAttrs]
-  if (sectionNumbers) attributes.push('sectnums')
-  if (cliAttributes) attributes.push(...cliAttributes)
-
-  const standalone = !(embedded || noHeaderFooter)
-  const verboseMode = quiet ? 0 : verbose ? 2 : 1
-
-  const options = {
-    standalone,
-    safe: safeMode ?? 'unsafe',
-    verbose: verboseMode,
-    timings: timings ?? false,
-    trace: trace ?? false,
-    attributes,
-    mkdirs: true,
-  }
+const HELP_COLUMN = 36
 
-  if (backend) options.backend = backend
-  if (doctype) options.doctype = doctype
-  if (baseDir != null) options.base_dir = baseDir
-  if (destinationDir != null) options.to_dir = destinationDir
-  if (templateDir) options.template_dirs = templateDir
-  if (templateEngine) options.template_engine = templateEngine
-
-  const toStdout = outFile === '' || outFile === "''" || outFile === '-'
-  if (toStdout) {
-    options.to_file = false
-  } else if (outFile !== undefined) {
-    options.to_file = outFile
-  }
+const BASE_OPTION_DEFINITIONS = {
+  backend: {
+    type: 'string',
+    short: 'b',
+    describe: 'set output format backend',
+    metavar: '<backend>',
+  },
+  doctype: {
+    type: 'string',
+    short: 'd',
+    describe: 'document type [article, book, manpage, inline]',
+    metavar: '<doctype>',
+  },
+  'out-file': {
+    type: 'string',
+    short: 'o',
+    describe: "output file; use '' or '-' for STDOUT",
+    metavar: '<file>',
+  },
+  'safe-mode': {
+    type: 'string',
+    short: 'S',
+    describe: 'safe mode level [unsafe, safe, server, secure]',
+    metavar: '<mode>',
+  },
+  embedded: {
+    type: 'boolean',
+    short: 'e',
+    describe: 'suppress enclosing document structure',
+  },
+  'no-header-footer': {
+    type: 'boolean',
+    short: 's',
+    describe: 'suppress enclosing document structure',
+  },
+  'section-numbers': {
+    type: 'boolean',
+    short: 'n',
+    describe: 'auto-number section titles in the HTML backend',
+  },
+  'base-dir': {
+    type: 'string',
+    short: 'B',
+    describe: 'base directory containing the document and resources',
+    metavar: '<dir>',
+  },
+  'destination-dir': {
+    type: 'string',
+    short: 'D',
+    describe: 'destination output directory',
+    metavar: '<dir>',
+  },
+  'failure-level': {
+    type: 'string',
+    describe:
+      'minimum logging level that triggers non-zero exit code [INFO, WARN, ERROR, FATAL]',
+    metavar: '<level>',
+  },
+  quiet: { type: 'boolean', short: 'q', describe: 'suppress warnings' },
+  trace: {
+    type: 'boolean',
+    describe: 'include backtrace information on errors',
+  },
+  verbose: { type: 'boolean', short: 'v', describe: 'enable verbose mode' },
+  timings: { type: 'boolean', short: 't', describe: 'enable timings mode' },
+  'template-dir': {
+    type: 'string',
+    short: 'T',
+    multiple: true,
+    describe: 'directory with custom converter templates (repeatable)',
+    metavar: '<dir>',
+  },
+  'template-engine': {
+    type: 'string',
+    short: 'E',
+    describe: 'template engine to use for custom converter templates',
+    metavar: '<engine>',
+  },
+  attribute: {
+    type: 'string',
+    short: 'a',
+    multiple: true,
+    describe: 'document attribute to set (repeatable)',
+    metavar: '<key[=value]>',
+  },
+  require: {
+    type: 'string',
+    short: 'r',
+    multiple: true,
+    describe:
+      'require the specified library before executing the processor (repeatable)',
+    metavar: '<library>',
+  },
+  version: {
+    type: 'boolean',
+    short: 'V',
+    describe: 'display the version and runtime environment',
+  },
+  help: {
+    type: 'boolean',
+    describe:
+      "show this help; show AsciiDoc syntax overview if topic is 'syntax'",
+    metavar: '[syntax]',
+  },
+}
 
-  return { options, failureLevel, toStdout }
+function buildHelpLine(key, def) {
+  const shortPart = def.short ? `-${def.short}, ` : '    '
+  const metavar = def.type === 'boolean' ? '' : ` ${def.metavar ?? `<${key}>`}`
+  const keyPart = `--${key}${metavar}`
+  const left = `  ${shortPart}${keyPart}`
+  const padding = Math.max(2, HELP_COLUMN - left.length)
+  return `${left}${' '.repeat(padding)}${def.describe ?? ''}`
 }
 
 function requireLibrary(requirePath, cwd = process.cwd()) {
@@ -153,56 +160,246 @@ function requireLibrary(requirePath, cwd = process.cwd()) {
   return require(requirePath)
 }
 
-function prepareProcessor(values) {
-  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)
-    }
+/**
+ * Definition of a CLI option used by {@link Options#addOption}.
+ *
+ * @typedef {Object} OptionDefinition
+ * @property {'string'|'boolean'} type - the value type of the option
+ * @property {string} [short] - single character short alias (without -)
+ * @property {boolean} [multiple] - whether the option can be repeated
+ * @property {string|boolean} [default] - default value when the option is absent
+ * @property {string} [describe] - description shown in --help output
+ * @property {string} [metavar] - value placeholder shown in --help for string options (e.g. `<theme>`)
+ */
+
+/**
+ * Parses command-line arguments and builds Asciidoctor convert options.
+ * Extend this class to add custom options via {@link Options#addOption}.
+ */
+export class Options {
+  constructor() {
+    /** @internal */
+    this._definitions = { ...BASE_OPTION_DEFINITIONS }
+    /** @type {string[]|null} */
+    this.argv = null
+    /** @type {Record<string, unknown>} */
+    this.values = {}
+    /** @type {string[]} */
+    this.positionals = []
+    /** @type {boolean} */
+    this.stdin = false
+    /** @type {Object} */
+    this.options = {}
+    /** @type {number} */
+    this.failureLevel = FAILURE_LEVELS.FATAL
   }
-}
 
-function getVersion() {
-  const pkg = JSON.parse(
-    readFileSync(join(import.meta.dirname, '..', 'package.json'), 'utf8')
-  )
-  return `Asciidoctor.js ${_getVersion()} (Asciidoctor ${getCoreVersion()}) [https://asciidoctor.org]
-Runtime Environment (node ${process.version} on ${process.platform})
-CLI version ${pkg.version}`
-}
+  /**
+   * Register a custom CLI option.
+   * Call this in your subclass constructor before invoking {@link Options#parse}.
+   *
+   * @param {string} key - the long option name (without --)
+   * @param {OptionDefinition} opt - the option definition
+   * @returns {this}
+   */
+  addOption(key, opt) {
+    this._definitions[key] = opt
+    return this
+  }
 
-function readFromStdin() {
-  return new Promise((resolve, reject) => {
-    let data = ''
-    process.stdin.setEncoding('utf8')
-    process.stdin.on('readable', () => {
-      const chunk = process.stdin.read()
-      if (chunk !== null) data += chunk
+  /**
+   * Parse the command-line arguments.
+   * Populates {@link Options#values}, {@link Options#positionals}, {@link Options#stdin},
+   * {@link Options#options}, and {@link Options#failureLevel}.
+   *
+   * @param {string[]} argv - the process arguments (typically `process.argv`)
+   * @returns {this}
+   */
+  parse(argv) {
+    this.argv = argv
+    const args = argv.slice(2)
+    const parseArgsOptions = {}
+    for (const [key, def] of Object.entries(this._definitions)) {
+      const entry = { type: def.type }
+      if (def.short) entry.short = def.short
+      if (def.multiple) entry.multiple = def.multiple
+      if (def.default !== undefined) entry.default = def.default
+      parseArgsOptions[key] = entry
+    }
+    const { values, positionals } = parseArgs({
+      args,
+      allowPositionals: true,
+      strict: false,
+      options: parseArgsOptions,
     })
-    process.stdin.on('error', reject)
-    process.stdin.on('end', () => resolve(data.replace(/\n$/, '')))
-  })
-}
+    this.values = values
+    this.positionals = positionals
+    this.stdin =
+      positionals.includes('-') ||
+      (positionals.length === 0 && args[args.length - 1] === '-')
+    if (this.stdin) {
+      this.values['out-file'] = this.values['out-file'] ?? '-'
+    }
+    const built = this._buildConvertOptions()
+    this.options = built.options
+    this.failureLevel = built.failureLevel
+    return this
+  }
+
+  /** @internal */
+  _buildConvertOptions(extraAttrs = []) {
+    const {
+      backend,
+      doctype,
+      'safe-mode': safeMode,
+      embedded,
+      'no-header-footer': noHeaderFooter,
+      'section-numbers': sectionNumbers,
+      'base-dir': baseDir,
+      'destination-dir': destinationDir,
+      'out-file': outFile,
+      'template-dir': templateDir,
+      'template-engine': templateEngine,
+      quiet,
+      verbose,
+      timings,
+      trace,
+      'failure-level': failureLevelStr = 'FATAL',
+      attribute: cliAttributes,
+    } = this.values
+
+    const level = failureLevelStr.toUpperCase()
+    const failureLevel = FAILURE_LEVELS[level] ?? FAILURE_LEVELS.FATAL
+
+    const attributes = [...extraAttrs]
+    if (sectionNumbers) attributes.push('sectnums')
+    if (cliAttributes) attributes.push(...cliAttributes)
+
+    const standalone = !(embedded || noHeaderFooter)
+    const verboseMode = quiet ? 0 : verbose ? 2 : 1
+
+    const options = {
+      standalone,
+      safe: safeMode ?? 'unsafe',
+      verbose: verboseMode,
+      timings: timings ?? false,
+      trace: trace ?? false,
+      attributes,
+      mkdirs: true,
+    }
+
+    if (backend) options.backend = backend
+    if (doctype) options.doctype = doctype
+    if (baseDir != null) options.base_dir = baseDir
+    if (destinationDir != null) options.to_dir = destinationDir
+    if (templateDir) options.template_dirs = templateDir
+    if (templateEngine) options.template_engine = templateEngine
+
+    const toStdout = outFile === '' || outFile === "''" || outFile === '-'
+    if (toStdout) {
+      options.to_file = false
+    } else if (outFile !== undefined) {
+      options.to_file = outFile
+    }
+
+    return { options, failureLevel }
+  }
 
-async function exit(failureLevel) {
-  const logger = LoggerManager.getLogger()
-  const maxSeverity = logger.getMaxSeverity()
-  const code = maxSeverity !== null && maxSeverity >= failureLevel ? 1 : 0
-  process.exit(code)
+  /**
+   * Build the help text from all registered option definitions.
+   *
+   * @returns {string}
+   */
+  buildHelpText() {
+    const lines = [HELP_PREAMBLE]
+    for (const [key, def] of Object.entries(this._definitions)) {
+      lines.push(buildHelpLine(key, def))
+    }
+    return lines.join('\n')
+  }
 }
 
-export async function run(argv = process.argv) {
-  const { values, positionals, args } = parseCliArgs(argv)
+/**
+ * Executes the CLI after options have been parsed.
+ * Extend this class to customize the conversion workflow.
+ */
+export class Invoker {
+  /**
+   * @param {Options} options - the parsed options instance
+   */
+  constructor(options) {
+    this.options = options
+  }
+
+  /**
+   * Run the CLI: handle `--version`, `--help`, stdin, and file conversion.
+   *
+   * @returns {Promise<void>}
+   */
+  async invoke() {
+    const { values, positionals, argv, stdin } = this.options
+    const args = argv.slice(2)
 
-  if (values.version || (values.verbose && args.length === 1)) {
-    console.log(getVersion())
-    process.exit(0)
+    if (values.version || (values.verbose && args.length === 1)) {
+      this.showVersion()
+      process.exit(0)
+    }
+
+    if (values.help) {
+      this.showHelp(positionals[0])
+      process.exit(0)
+    }
+
+    this._prepareProcessor(values)
+    const { options, failureLevel } = this.options
+
+    const logger = LoggerManager.getLogger()
+    if (values.quiet) logger.setLevel(3)
+    else if (values.verbose) logger.setLevel(0)
+
+    const files = positionals.filter((f) => f !== '-')
+
+    if (stdin) {
+      await this._convertFromStdin(options)
+    } else if (files.length > 0) {
+      await this.convertFiles(files, options, values)
+    } else {
+      this.showHelp()
+      process.exit(0)
+    }
+
+    await this._exit(failureLevel)
+  }
+
+  /**
+   * Return the version string printed by `--version`.
+   * Override to prepend your tool's own version.
+   *
+   * @returns {string}
+   */
+  version() {
+    const pkg = JSON.parse(
+      readFileSync(join(import.meta.dirname, '..', 'package.json'), 'utf8')
+    )
+    return `Asciidoctor.js ${_getVersion()} (Asciidoctor ${getCoreVersion()}) [https://asciidoctor.org]
+Runtime Environment (node ${process.version} on ${process.platform})
+CLI version ${pkg.version}`
+  }
+
+  /**
+   * Print the version string to stdout.
+   */
+  showVersion() {
+    console.log(this.version())
   }
 
-  if (values.help) {
-    if (positionals[0] === 'syntax') {
+  /**
+   * Print help to stderr, or the AsciiDoc syntax reference if `topic` is `'syntax'`.
+   *
+   * @param {string} [topic]
+   */
+  showHelp(topic) {
+    if (topic === 'syntax') {
       console.log(
         readFileSync(
           join(import.meta.dirname, '..', 'data', 'reference', 'syntax.adoc'),
@@ -210,48 +407,85 @@ export async function run(argv = process.argv) {
         )
       )
     } else {
-      console.error(HELP_TEXT)
+      console.error(this.options.buildHelpText())
     }
-    process.exit(0)
   }
 
-  prepareProcessor(values)
-  const { options, failureLevel, toStdout } = buildOptions(values)
-
-  // Configure logger verbosity
-  const logger = LoggerManager.getLogger()
-  if (values.quiet)
-    logger.setLevel(3) // ERROR
-  else if (values.verbose) logger.setLevel(0) // DEBUG
-
-  const files = positionals.filter((f) => f !== '-')
-  const isStdin =
-    positionals.includes('-') ||
-    (files.length === 0 && args[args.length - 1] === '-')
-
-  if (isStdin) {
-    const data = await readFromStdin()
-    const output = await convert(data, { ...options, to_file: false })
-    process.stdout.write(output)
-  } else if (files.length > 0) {
+  /**
+   * Convert the given files.
+   * Override this method to implement custom conversion logic (e.g. PDF generation).
+   *
+   * @param {string[]} files - input files to convert
+   * @param {Object} options - Asciidoctor convert options built from the CLI flags
+   * @param {Record<string, unknown>} values - all parsed CLI values, including custom options
+   * @returns {Promise<void>}
+   */
+  async convertFiles(files, options, values) {
     for (const file of files) {
       if (values.verbose) console.log(`converting file ${file}`)
       if (values.timings) {
         const timings = Timings.create()
         const fileOptions = { ...options, timings }
-        if (toStdout) fileOptions.to_file = false
         const result = await convertFile(file, fileOptions)
-        if (toStdout && typeof result === 'string') process.stdout.write(result)
+        if (options.to_file === false && typeof result === 'string')
+          process.stdout.write(result)
         timings.printReport(process.stderr, file)
       } else {
         const result = await convertFile(file, options)
-        if (toStdout && typeof result === 'string') process.stdout.write(result)
+        if (options.to_file === false && typeof result === 'string')
+          process.stdout.write(result)
       }
     }
-  } else {
-    console.error(HELP_TEXT)
-    process.exit(0)
   }
 
-  await exit(failureLevel)
+  /** @internal */
+  _prepareProcessor(values) {
+    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)
+      }
+    }
+  }
+
+  /** @internal */
+  async _convertFromStdin(options) {
+    const data = await _readFromStdin()
+    const output = await convert(data, { ...options, to_file: false })
+    process.stdout.write(output)
+  }
+
+  /** @internal */
+  async _exit(failureLevel) {
+    const logger = LoggerManager.getLogger()
+    const maxSeverity = logger.getMaxSeverity()
+    const code = maxSeverity !== null && maxSeverity >= failureLevel ? 1 : 0
+    process.exit(code)
+  }
+}
+
+function _readFromStdin() {
+  return new Promise((resolve, reject) => {
+    let data = ''
+    process.stdin.setEncoding('utf8')
+    process.stdin.on('readable', () => {
+      const chunk = process.stdin.read()
+      if (chunk !== null) data += chunk
+    })
+    process.stdin.on('error', reject)
+    process.stdin.on('end', () => resolve(data.replace(/\n$/, '')))
+  })
+}
+
+/**
+ * Run the CLI.
+ * Equivalent to `new Invoker(new Options().parse(argv)).invoke()`.
+ *
+ * @param {string[]} [argv=process.argv]
+ * @returns {Promise<void>}
+ */
+export async function run(argv = process.argv) {
+  return new Invoker(new Options().parse(argv)).invoke()
 }

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "asciidoctor",
-  "version": "4.0.0-alpha.4",
+  "version": "4.0.0-alpha.6",
   "description": "A JavaScript AsciiDoc processor powered by Asciidoctor",
   "type": "module",
   "main": "index.js",
   "types": "types",
   "exports": {
-    ".": "./index.js"
+    ".": "./index.js",
+    "./cli": {
+      "types": "./types/cli.d.ts",
+      "default": "./lib/cli.js"
+    }
   },
   "bin": {
     "asciidoctor": "bin/asciidoctor",
@@ -14,6 +18,8 @@
   },
   "scripts": {
     "test": "node --test test/cli.test.js",
+    "build:types": "tsc",
+    "docs": "typedoc --tsconfig tsconfig.docs.json",
     "test:deno": "deno test --allow-env --no-check --allow-read --allow-sys --allow-write --allow-run --allow-net test/cli.test.js",
     "lint": "biome lint bin lib tasks index.js rollup.config.js",
     "format": "biome format --write bin lib tasks index.js rollup.config.js",
@@ -21,7 +27,7 @@
     "build:binary": "node tasks/build-sea.js"
   },
   "engines": {
-    "node": ">=24"
+    "node": ">=20"
   },
   "files": [
     "bin",
@@ -54,7 +60,7 @@
   },
   "homepage": "https://github.com/asciidoctor/asciidoctor.js",
   "dependencies": {
-    "@asciidoctor/core": "4.0.0-alpha.4"
+    "@asciidoctor/core": "4.0.0-alpha.6"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.13",
@@ -67,6 +73,6 @@
     "pug": "^3.0.3"
   },
   "volta": {
-    "node": "24.15.0"
+    "node": "24.16.0"
   }
 }

package/types/cli.d.ts

@@ -0,0 +1,268 @@
+/**
+ * Run the CLI.
+ * Equivalent to `new Invoker(new Options().parse(argv)).invoke()`.
+ *
+ * @param {string[]} [argv=process.argv]
+ * @returns {Promise<void>}
+ */
+export function run(argv?: string[]): Promise<void>;
+/**
+ * Definition of a CLI option used by {@link Options#addOption}.
+ *
+ * @typedef {Object} OptionDefinition
+ * @property {'string'|'boolean'} type - the value type of the option
+ * @property {string} [short] - single character short alias (without -)
+ * @property {boolean} [multiple] - whether the option can be repeated
+ * @property {string|boolean} [default] - default value when the option is absent
+ * @property {string} [describe] - description shown in --help output
+ * @property {string} [metavar] - value placeholder shown in --help for string options (e.g. `<theme>`)
+ */
+/**
+ * Parses command-line arguments and builds Asciidoctor convert options.
+ * Extend this class to add custom options via {@link Options#addOption}.
+ */
+export class Options {
+    /** @internal */
+    _definitions: {
+        backend: {
+            type: string;
+            short: string;
+            describe: string;
+            metavar: string;
+        };
+        doctype: {
+            type: string;
+            short: string;
+            describe: string;
+            metavar: string;
+        };
+        'out-file': {
+            type: string;
+            short: string;
+            describe: string;
+            metavar: string;
+        };
+        'safe-mode': {
+            type: string;
+            short: string;
+            describe: string;
+            metavar: string;
+        };
+        embedded: {
+            type: string;
+            short: string;
+            describe: string;
+        };
+        'no-header-footer': {
+            type: string;
+            short: string;
+            describe: string;
+        };
+        'section-numbers': {
+            type: string;
+            short: string;
+            describe: string;
+        };
+        'base-dir': {
+            type: string;
+            short: string;
+            describe: string;
+            metavar: string;
+        };
+        'destination-dir': {
+            type: string;
+            short: string;
+            describe: string;
+            metavar: string;
+        };
+        'failure-level': {
+            type: string;
+            describe: string;
+            metavar: string;
+        };
+        quiet: {
+            type: string;
+            short: string;
+            describe: string;
+        };
+        trace: {
+            type: string;
+            describe: string;
+        };
+        verbose: {
+            type: string;
+            short: string;
+            describe: string;
+        };
+        timings: {
+            type: string;
+            short: string;
+            describe: string;
+        };
+        'template-dir': {
+            type: string;
+            short: string;
+            multiple: boolean;
+            describe: string;
+            metavar: string;
+        };
+        'template-engine': {
+            type: string;
+            short: string;
+            describe: string;
+            metavar: string;
+        };
+        attribute: {
+            type: string;
+            short: string;
+            multiple: boolean;
+            describe: string;
+            metavar: string;
+        };
+        require: {
+            type: string;
+            short: string;
+            multiple: boolean;
+            describe: string;
+            metavar: string;
+        };
+        version: {
+            type: string;
+            short: string;
+            describe: string;
+        };
+        help: {
+            type: string;
+            describe: string;
+            metavar: string;
+        };
+    };
+    /** @type {string[]|null} */
+    argv: string[] | null;
+    /** @type {Record<string, unknown>} */
+    values: Record<string, unknown>;
+    /** @type {string[]} */
+    positionals: string[];
+    /** @type {boolean} */
+    stdin: boolean;
+    /** @type {Object} */
+    options: any;
+    /** @type {number} */
+    failureLevel: number;
+    /**
+     * Register a custom CLI option.
+     * Call this in your subclass constructor before invoking {@link Options#parse}.
+     *
+     * @param {string} key - the long option name (without --)
+     * @param {OptionDefinition} opt - the option definition
+     * @returns {this}
+     */
+    addOption(key: string, opt: OptionDefinition): this;
+    /**
+     * Parse the command-line arguments.
+     * Populates {@link Options#values}, {@link Options#positionals}, {@link Options#stdin},
+     * {@link Options#options}, and {@link Options#failureLevel}.
+     *
+     * @param {string[]} argv - the process arguments (typically `process.argv`)
+     * @returns {this}
+     */
+    parse(argv: string[]): this;
+    /** @internal */
+    _buildConvertOptions(extraAttrs?: any[]): {
+        options: {
+            standalone: boolean;
+            safe: unknown;
+            verbose: number;
+            timings: unknown;
+            trace: unknown;
+            attributes: any[];
+            mkdirs: boolean;
+        };
+        failureLevel: any;
+    };
+    /**
+     * Build the help text from all registered option definitions.
+     *
+     * @returns {string}
+     */
+    buildHelpText(): string;
+}
+/**
+ * Executes the CLI after options have been parsed.
+ * Extend this class to customize the conversion workflow.
+ */
+export class Invoker {
+    /**
+     * @param {Options} options - the parsed options instance
+     */
+    constructor(options: Options);
+    options: Options;
+    /**
+     * Run the CLI: handle `--version`, `--help`, stdin, and file conversion.
+     *
+     * @returns {Promise<void>}
+     */
+    invoke(): Promise<void>;
+    /**
+     * Return the version string printed by `--version`.
+     * Override to prepend your tool's own version.
+     *
+     * @returns {string}
+     */
+    version(): string;
+    /**
+     * Print the version string to stdout.
+     */
+    showVersion(): void;
+    /**
+     * Print help to stderr, or the AsciiDoc syntax reference if `topic` is `'syntax'`.
+     *
+     * @param {string} [topic]
+     */
+    showHelp(topic?: string): void;
+    /**
+     * Convert the given files.
+     * Override this method to implement custom conversion logic (e.g. PDF generation).
+     *
+     * @param {string[]} files - input files to convert
+     * @param {Object} options - Asciidoctor convert options built from the CLI flags
+     * @param {Record<string, unknown>} values - all parsed CLI values, including custom options
+     * @returns {Promise<void>}
+     */
+    convertFiles(files: string[], options: any, values: Record<string, unknown>): Promise<void>;
+    /** @internal */
+    _prepareProcessor(values: any): void;
+    /** @internal */
+    _convertFromStdin(options: any): Promise<void>;
+    /** @internal */
+    _exit(failureLevel: any): Promise<void>;
+}
+/**
+ * Definition of a CLI option used by {@link Options#addOption}.
+ */
+export type OptionDefinition = {
+    /**
+     * - the value type of the option
+     */
+    type: "string" | "boolean";
+    /**
+     * - single character short alias (without -)
+     */
+    short?: string;
+    /**
+     * - whether the option can be repeated
+     */
+    multiple?: boolean;
+    /**
+     * - default value when the option is absent
+     */
+    default?: string | boolean;
+    /**
+     * - description shown in --help output
+     */
+    describe?: string;
+    /**
+     * - value placeholder shown in --help for string options (e.g. `<theme>`)
+     */
+    metavar?: string;
+};

package/types/document.d.ts

@@ -489,7 +489,7 @@ export namespace Document {
 import { Footnote } from './footnote.js';
 import { AttributeEntry } from './attribute_entry.js';
 import { AbstractBlock } from './abstract_block.js';
-import type { Reader } from './reader.js';
+import { Reader } from './reader.js';
 import { Section } from './section.js';
 import { Inline } from './inline.js';
 export { Footnote, AttributeEntry };

package/types/index.d.cts

@@ -27,14 +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;
+export type { ProcessorDslInterface } from './extensions.js';
+export type { DocumentProcessorDslInterface } from './extensions.js';
+export type { SyntaxProcessorDslInterface } from './extensions.js';
+export type { IncludeProcessorDslInterface } from './extensions.js';
+export type { DocinfoProcessorDslInterface } from './extensions.js';
+export type { BlockProcessorDslInterface } from './extensions.js';
+export type { MacroProcessorDslInterface } from './extensions.js';
+export type { InlineMacroProcessorDslInterface } from './extensions.js';
 import { Document } from './document.js';
 import { convert } from './convert.js';
 import { convertFile } from './convert.js';

package/types/index.d.ts

@@ -26,14 +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;
+export type { ProcessorDslInterface } from './extensions.js';
+export type { DocumentProcessorDslInterface } from './extensions.js';
+export type { SyntaxProcessorDslInterface } from './extensions.js';
+export type { IncludeProcessorDslInterface } from './extensions.js';
+export type { DocinfoProcessorDslInterface } from './extensions.js';
+export type { BlockProcessorDslInterface } from './extensions.js';
+export type { MacroProcessorDslInterface } from './extensions.js';
+export type { InlineMacroProcessorDslInterface } from './extensions.js';
 import { Document } from './document.js';
 import { convert } from './convert.js';
 import { convertFile } from './convert.js';