@antora/site-generator-default 3.0.0-alpha.8 → 3.0.0-beta.3

package/README.md

@@ -1,10 +1,10 @@
 # Antora Default Site Generator
 
-This is the default site generator pipeline for Antora.
-This pipeline is invoked by the `generate` command of Antora's CLI to produce and publish static documentation sites.
+This is the default site generator for Antora.
+This generator is invoked by the `generate` command of Antora's CLI to produce and publish static documentation sites.
 
 [Antora](https://antora.org) is a modular static site generator designed for creating documentation sites from AsciiDoc documents.
-Its site generator pipeline aggregates documents from versioned content repositories and processes them using [Asciidoctor](https://asciidoctor.org).
+Its site generator aggregates documents from versioned content repositories and processes them using [Asciidoctor](https://asciidoctor.org).
 
 ## Copyright and License
 

package/lib/generate-site.js

@@ -1,74 +1,64 @@
 'use strict'
 
-const Pipeline = require('./pipeline')
+const GeneratorContext = require('./generator-context')
 const SiteCatalog = require('./site-catalog')
 
-const aggregateContent = require('@antora/content-aggregator')
-const buildNavigation = require('@antora/navigation-builder')
-const buildPlaybook = require('@antora/playbook-builder')
-const classifyContent = require('@antora/content-classifier')
-const convertDocuments = require('@antora/document-converter')
-const createPageComposer = require('@antora/page-composer')
-const loadUi = require('@antora/ui-loader')
-const mapSite = require('@antora/site-mapper')
-const produceRedirects = require('@antora/redirect-producer')
-const publishSite = require('@antora/site-publisher')
-const { resolveAsciiDocConfig } = require('@antora/asciidoc-loader')
-
-async function generateSite (args, env) {
-  let playbook = buildPlaybook(args, env)
+async function generateSite (playbook) {
+  const context = new GeneratorContext(module)
   try {
-    const pipeline = new Pipeline(playbook, module)
-    const vars = pipeline.vars
-    await pipeline.notify('playbookBuilt')
+    const { fxns, vars } = await GeneratorContext.start(context, playbook)
+    await context.notify('playbookBuilt')
     playbook = vars.lock('playbook')
-    vars.asciidocConfig = resolveAsciiDocConfig(playbook)
+    vars.siteAsciiDocConfig = fxns.resolveAsciiDocConfig(playbook)
     vars.siteCatalog = new SiteCatalog()
-    await pipeline.notify('beforeProcess')
-    const asciidocConfig = vars.lock('asciidocConfig')
+    await context.notify('beforeProcess')
+    const siteAsciiDocConfig = vars.lock('siteAsciiDocConfig')
     await Promise.all([
-      aggregateContent(playbook).then((contentAggregate) =>
-        pipeline.notify('contentAggregated', Object.assign(vars, { contentAggregate })).then(() => {
-          vars.contentCatalog = classifyContent(playbook, vars.remove('contentAggregate'), asciidocConfig)
+      fxns.aggregateContent(playbook).then((contentAggregate) =>
+        context.notify('contentAggregated', Object.assign(vars, { contentAggregate })).then(() => {
+          vars.contentCatalog = fxns.classifyContent(playbook, vars.remove('contentAggregate'), siteAsciiDocConfig)
         })
       ),
-      loadUi(playbook).then((uiCatalog) => pipeline.notify('uiLoaded', Object.assign(vars, { uiCatalog }))),
+      fxns.loadUi(playbook).then((uiCatalog) => context.notify('uiLoaded', Object.assign(vars, { uiCatalog }))),
     ])
-    await pipeline.notify('contentClassified')
+    await context.notify('contentClassified')
     const contentCatalog = vars.lock('contentCatalog')
     const uiCatalog = vars.lock('uiCatalog')
-    convertDocuments(contentCatalog, asciidocConfig)
-    await pipeline.notify('documentsConverted')
-    vars.navigationCatalog = buildNavigation(contentCatalog, asciidocConfig)
-    await pipeline.notify('navigationBuilt')
+    fxns.convertDocuments(contentCatalog, siteAsciiDocConfig)
+    await context.notify('documentsConverted')
+    vars.navigationCatalog = fxns.buildNavigation(contentCatalog, siteAsciiDocConfig)
+    await context.notify('navigationBuilt')
     ;(() => {
       const navigationCatalog = vars.remove('navigationCatalog')
-      const composePage = createPageComposer(playbook, contentCatalog, uiCatalog, playbook.env)
+      const composePage = fxns.createPageComposer(playbook, contentCatalog, uiCatalog, playbook.env)
       contentCatalog.getPages((page) => page.out && composePage(page, contentCatalog, navigationCatalog))
       if (playbook.site.url) vars.siteCatalog.addFile(composePage(create404Page()))
     })()
-    await pipeline.notify('pagesComposed')
-    vars.siteCatalog.addFiles(produceRedirects(playbook, contentCatalog))
-    await pipeline.notify('redirectsProduced')
+    await context.notify('pagesComposed')
+    vars.siteCatalog.addFiles(fxns.produceRedirects(playbook, contentCatalog))
+    await context.notify('redirectsProduced')
     if (playbook.site.url) {
       const publishablePages = contentCatalog.getPages((page) => page.out)
-      vars.siteCatalog.addFiles(mapSite(playbook, publishablePages))
-      await pipeline.notify('siteMapped')
+      vars.siteCatalog.addFiles(fxns.mapSite(playbook, publishablePages))
+      await context.notify('siteMapped')
     }
-    await pipeline.notify('beforePublish')
-    return publishSite(playbook, [contentCatalog, uiCatalog, vars.lock('siteCatalog')]).then((publications) => {
+    await context.notify('beforePublish')
+    return fxns.publishSite(playbook, [contentCatalog, uiCatalog, vars.lock('siteCatalog')]).then((publications) => {
       if (!playbook.runtime.quiet && process.stdout.isTTY) {
         process.stdout.write('Site generation complete!\n')
         publications.forEach(
           ({ fileUri }) => fileUri && process.stdout.write(`View the site by visiting ${fileUri} in a browser.\n`)
         )
       }
-      return pipeline
+      return context
         .notify('sitePublished', Object.assign(vars, { publications }))
         .then(() => vars.remove('publications'))
     })
   } catch (err) {
-    if (!Pipeline.isHaltSignal(err)) throw err
+    if (!GeneratorContext.isStopSignal(err)) throw err
+    await err.notify()
+  } finally {
+    await GeneratorContext.close(context)
   }
 }
 

package/lib/generator-context.js

@@ -0,0 +1,166 @@
+'use strict'
+
+const EventEmitter = require('events')
+const getLogger = require('@antora/logger')
+const userRequire = require('@antora/user-require-helper')
+
+const FUNCTION_PROVIDERS = {
+  aggregateContent: 'content-aggregator',
+  buildNavigation: 'navigation-builder',
+  classifyContent: 'content-classifier',
+  convertDocument: 'document-converter',
+  convertDocuments: 'document-converter',
+  createPageComposer: 'page-composer',
+  extractAsciiDocMetadata: 'asciidoc-loader',
+  loadAsciiDoc: 'asciidoc-loader',
+  loadUi: 'ui-loader',
+  mapSite: 'site-mapper',
+  produceRedirects: 'redirect-producer',
+  publishSite: 'site-publisher',
+  resolveAsciiDocConfig: 'asciidoc-loader',
+}
+
+const FUNCTION_WITH_POSITIONAL_PARAMETER_RX = /^(?:function *)?(?:\w+ *)?\( *\w|^\w+(?: *, *\w+)* *=>/
+const NEWLINES_RX = /\r?\n/g
+
+class StopSignal extends Error {}
+
+class GeneratorContext extends EventEmitter {
+  #fxns
+  #vars
+
+  constructor (module_) {
+    super()
+    // deprecated method aliases - remove for Antora 3.0.0
+    Object.defineProperties(this, { halt: { value: this.stop }, updateVars: { value: this.updateVariables } })
+    if (!('path' in (this.module = module_))) module_.path = require('path').dirname(module_.filename)
+  }
+
+  getFunctions () {
+    return arguments.length ? this.#fxns : Object.assign({}, this.#fxns)
+  }
+
+  getLogger (name = 'antora') {
+    return getLogger(name)
+  }
+
+  getVariables () {
+    return Object.assign({}, this.#vars)
+  }
+
+  async notify (eventName) {
+    if (!this.listenerCount(eventName)) return
+    for (const listener of this.rawListeners(eventName)) {
+      const outcome = listener.length === 1 ? listener.call(this, this.getVariables()) : listener.call(this)
+      if (outcome instanceof Promise) await outcome
+    }
+  }
+
+  replaceFunctions (updates) {
+    const fxns = this.#fxns
+    Object.entries(updates).forEach(([name, fxn]) => {
+      if (name in fxns) fxns[name] = fxn.bind(this)
+    })
+  }
+
+  require (request) {
+    return this.module.require(request)
+  }
+
+  stop (code) {
+    if (code != null) process.exitCode = code
+    throw Object.assign(new StopSignal(), { notify: this.notify.bind(this, 'contextStopped') })
+  }
+
+  updateVariables (updates) {
+    try {
+      Object.assign(this.#vars, updates)
+    } catch (err) {
+      if (err instanceof TypeError) {
+        err.message = err.message.replace(/ assign to read.only property '(.+)' .*/, " update read-only var '$1'")
+      }
+      throw err
+    }
+  }
+
+  static async close (instance) {
+    await instance.notify('contextClosed').catch(() => undefined)
+  }
+
+  static isStopSignal (err) {
+    return err instanceof StopSignal
+  }
+
+  static async start (instance, playbook) {
+    const returnValue = instance._init(playbook)
+    await instance.notify('contextStarted')
+    return returnValue
+  }
+
+  _init (playbook) {
+    this._registerFunctions()
+    this._registerExtensions(playbook, this._initVariables(playbook))
+    Object.defineProperties(this, { _init: {}, _initVariables: {}, _registerExtensions: {}, _registerFunctions: {} })
+    return { fxns: this.#fxns, vars: this.#vars }
+  }
+
+  _initVariables (playbook) {
+    return (this.#vars = Object.setPrototypeOf(
+      { playbook },
+      {
+        lock (name) {
+          return Object.defineProperty(this, name, { configurable: false, writable: false })[name]
+        },
+        remove (name) {
+          const currentValue = this[name]
+          delete this[name]
+          return currentValue
+        },
+      }
+    ))
+  }
+
+  _registerExtensions (playbook, vars) {
+    const extensions = (playbook.antora || {}).extensions || []
+    if (extensions.length) {
+      const requireContext = { dot: playbook.dir, paths: [playbook.dir || '', this.module.path] }
+      extensions.forEach((ext) => {
+        const { enabled = true, id, require: request, ...config } = ext.constructor === String ? { require: ext } : ext
+        if (!enabled) return
+        const { register } = userRequire(request, requireContext)
+        if (typeof register !== 'function') return
+        if (register.length) {
+          if (FUNCTION_WITH_POSITIONAL_PARAMETER_RX.test(register.toString().replace(NEWLINES_RX, ' '))) {
+            register.length === 1 ? register(this) : register(this, Object.assign({ config }, vars))
+          } else {
+            register.call(this, Object.assign({ config }, vars))
+          }
+        } else {
+          register.call(this)
+        }
+      })
+    }
+    if (this.eventNames().length) return
+    const notify = async () => undefined
+    Object.defineProperty(this, 'notify', { value: notify })
+  }
+
+  _registerFunctions () {
+    this.#fxns = Object.entries(
+      Object.entries(FUNCTION_PROVIDERS).reduce((accum, [fxnName, moduleKey]) => {
+        accum[moduleKey] = (accum[moduleKey] || []).concat(fxnName)
+        return accum
+      }, {})
+    ).reduce((accum, [moduleKey, fxnNames]) => {
+      const defaultExport = this.require('@antora/' + moduleKey)
+      const defaultExportName = defaultExport.name
+      fxnNames.forEach((fxnName) => {
+        const fxn = fxnName === defaultExportName ? defaultExport : defaultExport[fxnName]
+        accum[fxnName] = fxn.bind(this)
+      })
+      return accum
+    }, {})
+  }
+}
+
+module.exports = GeneratorContext

package/lib/index.js

@@ -3,10 +3,9 @@
 /**
  * Default Site Generator component for Antora
  *
- * Runs an Antora pipeline using the default set of components with a focus on
- * producing and publishing a documentation site. This component represents
- * just one way the Antora components can be organized into a site generation
- * pipeline.
+ * Coordinates a default set of software components to produce and publish a
+ * documentation site. This component represents just one way the Antora
+ * components can be organized to make a documentation generator.
  *
  * @namespace site-generator-default
  */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@antora/site-generator-default",
-  "version": "3.0.0-alpha.8",
-  "description": "The default site generator pipeline for producing and publishing static documentation sites with Antora.",
+  "version": "3.0.0-beta.3",
+  "description": "The default site generator for producing and publishing static documentation sites with Antora.",
   "license": "MPL-2.0",
   "author": "OpenDevise Inc. (https://opendevise.com)",
   "contributors": [
@@ -15,21 +15,24 @@
   },
   "main": "lib/index.js",
   "dependencies": {
-    "@antora/asciidoc-loader": "3.0.0-alpha.8",
-    "@antora/content-aggregator": "3.0.0-alpha.8",
-    "@antora/content-classifier": "3.0.0-alpha.8",
-    "@antora/document-converter": "3.0.0-alpha.8",
-    "@antora/navigation-builder": "3.0.0-alpha.8",
-    "@antora/page-composer": "3.0.0-alpha.8",
-    "@antora/playbook-builder": "3.0.0-alpha.8",
-    "@antora/redirect-producer": "3.0.0-alpha.8",
-    "@antora/site-mapper": "3.0.0-alpha.8",
-    "@antora/site-publisher": "3.0.0-alpha.8",
-    "@antora/ui-loader": "3.0.0-alpha.8",
+    "@antora/asciidoc-loader": "3.0.0-beta.3",
+    "@antora/content-aggregator": "3.0.0-beta.3",
+    "@antora/content-classifier": "3.0.0-beta.3",
+    "@antora/document-converter": "3.0.0-beta.3",
+    "@antora/logger": "3.0.0-beta.3",
+    "@antora/navigation-builder": "3.0.0-beta.3",
+    "@antora/page-composer": "3.0.0-beta.3",
+    "@antora/redirect-producer": "3.0.0-beta.3",
+    "@antora/site-mapper": "3.0.0-beta.3",
+    "@antora/site-publisher": "3.0.0-beta.3",
+    "@antora/ui-loader": "3.0.0-beta.3",
     "@antora/user-require-helper": "~2.0"
   },
+  "devDependencies": {
+    "@antora/playbook-builder": "3.0.0-beta.3"
+  },
   "engines": {
-    "node": ">=10.17.0"
+    "node": ">=12.21.0"
   },
   "files": [
     "lib/"
@@ -43,5 +46,5 @@
     "static site",
     "web publishing"
   ],
-  "gitHead": "2e5695bea11fb5719989c329c97e66d36e29659f"
+  "gitHead": "45da95a2e2dea538379d2d9f42013d2208fb86c3"
 }

package/lib/pipeline.js

@@ -1,90 +0,0 @@
-'use strict'
-
-const EventEmitter = require('events')
-const userRequire = require('@antora/user-require-helper')
-
-class HaltPipelineSignal extends Error {}
-
-class Pipeline extends EventEmitter {
-  constructor (playbook, module_) {
-    super()
-    if (!('path' in (this.module = module_))) module_.path = require('path').dirname(module_.filename)
-    _registerExtensions.bind(this)(playbook, module_, _initVars.bind(this)(playbook))
-  }
-
-  halt () {
-    throw new HaltPipelineSignal()
-  }
-
-  async notify (vars, eventName) {
-    if (this.listenerCount(eventName)) {
-      for (const listener of this.rawListeners(eventName)) {
-        const outcome = listener.call(this, Object.assign({}, vars))
-        if (outcome instanceof Promise) await outcome
-      }
-    }
-  }
-
-  require (request) {
-    return this.module.require(request)
-  }
-
-  updateVars (vars, updates) {
-    try {
-      Object.assign(vars, updates)
-    } catch (err) {
-      if (err instanceof TypeError) {
-        err.message = err.message.replace(/ assign to read.only property '(.+)' .*/, " update read-only var '$1'")
-      }
-      throw err
-    }
-  }
-
-  static isHaltSignal (err) {
-    return err instanceof HaltPipelineSignal
-  }
-}
-
-function _initVars (playbook) {
-  const vars = Object.setPrototypeOf(
-    { playbook },
-    {
-      lock (name) {
-        return Object.defineProperty(this, name, { configurable: false, writable: false })[name]
-      },
-      remove (name) {
-        const currentValue = this[name]
-        delete this[name]
-        return currentValue
-      },
-    }
-  )
-  Object.defineProperty(this, 'vars', {
-    configurable: true,
-    get: () => {
-      delete this.vars
-      return vars
-    },
-  })
-  this.updateVars = this.updateVars.bind(this, vars)
-  return vars
-}
-
-function _registerExtensions (playbook, module_, vars) {
-  const extensions = (playbook.pipeline || {}).extensions
-  if (extensions.length) {
-    const requireContext = { dot: playbook.dir, paths: [playbook.dir || '', module_.path] }
-    extensions.forEach((ext) => {
-      const { enabled = true, id, require: request, ...config } = ext.constructor === String ? { require: ext } : ext
-      if (enabled) {
-        const { register } = userRequire(request, requireContext)
-        if (typeof register === 'function') {
-          register.length === 1 ? register(this) : register(this, Object.assign({ config }, vars))
-        }
-      }
-    })
-  }
-  this.notify = this.eventNames().length ? this.notify.bind(this, vars) : async () => undefined
-}
-
-module.exports = Pipeline