@antora/playbook-builder 3.0.0-alpha.6 → 3.0.0-beta.1

package/README.md

@@ -4,7 +4,7 @@ The Playbook Builder is the configuration component for Antora.
 It's responsible for building a playbook object from user input that's then used for configuring components in an Antora generator pipeline.
 
 [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/build-playbook.js

@@ -1,10 +1,9 @@
 'use strict'
 
 const camelCaseKeys = require('camelcase-keys')
-const { configureLogger } = require('@antora/logger')
 const convict = require('./solitary-convict')
+const defaultSchema = require('./config/schema')
 const fs = require('fs')
-const { hasOwnProperty } = Object.prototype
 const ospath = require('path')
 
 /**
@@ -22,14 +21,15 @@ const ospath = require('path')
  *   option flags and switches. Should begin with the first flag or switch.
  * @param {Object} [env={}] - A map of environment variables.
  * @param {Object} [schema=undefined] - A convict configuration schema.
+ * @param {Function} [beforeValidate=undefined] - A function to invoke on the
+ *   config before validating it.
  *
  * @returns {Object} A playbook object containing a hierarchical structure that
  *   mirrors the configuration schema. With the exception of the top-level asciidoc
  *   key and its descendants, all keys in the playbook are camelCased.
  */
-function buildPlaybook (args = [], env = {}, schema = undefined) {
+function buildPlaybook (args = [], env = {}, schema = undefined, beforeValidate = undefined) {
   const config = loadConvictConfig(args, env, schema)
-
   const relSpecFilePath = config.get('playbook')
   if (relSpecFilePath) {
     let absSpecFilePath = ospath.resolve(relSpecFilePath)
@@ -57,40 +57,50 @@ function buildPlaybook (args = [], env = {}, schema = undefined) {
     config.loadFile(absSpecFilePath)
     if (relSpecFilePath !== absSpecFilePath) config.set('playbook', absSpecFilePath)
   }
-
-  config.validate({ allowed: 'strict' })
-
-  return exportModel(config)
+  const beforeValidateFromSchema = config._def[Symbol.for('convict.beforeValidate')]
+  if (beforeValidateFromSchema) beforeValidateFromSchema(config)
+  if (beforeValidate) beforeValidate(config)
+  return config.getModel()
 }
 
 function loadConvictConfig (args, env, customSchema) {
-  return convict(customSchema || require('./config/schema'), { args, env })
+  return Object.assign(convict(customSchema || defaultSchema, { args, env }), { getModel })
 }
 
-function freeze (o) {
-  let v
-  for (const k in o) hasOwnProperty.call(o, k) && (Object.isFrozen((v = o[k])) || freeze(v))
-  return Object.freeze(o)
+function getModel (name = '') {
+  let config = this
+  const data = config.get(name)
+  let schema = config._schema
+  if (name) {
+    schema = name.split('.').reduce((accum, key) => accum._cvtProperties[key], schema)
+    config = Object.assign(convict(name.split('.').reduce((def, key) => def[key], config._def)), { _instance: data })
+  }
+  config.validate({ allowed: 'strict' })
+  const model = camelCaseKeys(data, { deep: true, stopPaths: getStopPaths(schema._cvtProperties) })
+  if (!name) {
+    Object.defineProperty(model, 'env', { value: config.getEnv() })
+    model.dir = model.playbook ? ospath.dirname((model.file = model.playbook)) : process.cwd()
+    delete model.playbook
+  }
+  return deepFreeze(model)
 }
 
-function exportModel (config) {
-  const schemaProperties = config._schema._cvtProperties
-  const data = config.getProperties()
-  if (
-    'site' in schemaProperties &&
-    'keys' in schemaProperties.site._cvtProperties &&
-    '__private__google_analytics_key' in schemaProperties.site._cvtProperties
-  ) {
-    const site = data.site
-    if (site.__private__google_analytics_key != null) site.keys.google_analytics = site.__private__google_analytics_key
-    delete site.__private__google_analytics_key
+function getStopPaths (schemaProperties, schemaPath = [], stopPaths = []) {
+  for (const [key, { preserve, _cvtProperties }] of Object.entries(schemaProperties)) {
+    if (preserve) {
+      Array.isArray(preserve)
+        ? preserve.forEach((it) => stopPaths.push(schemaPath.concat(key, it).join('.')))
+        : stopPaths.push(schemaPath.concat(key).join('.'))
+    } else if (_cvtProperties) {
+      stopPaths.push(...getStopPaths(_cvtProperties, schemaPath.concat(key)))
+    }
   }
-  const playbook = camelCaseKeys(data, { deep: true, stopPaths: ['asciidoc'] })
-  playbook.dir = playbook.playbook ? ospath.dirname((playbook.file = playbook.playbook)) : process.cwd()
-  delete playbook.playbook
-  const log = (playbook.runtime || {}).log
-  if (log) configureLogger(playbook.runtime.silent ? (log.level = 'silent') && log : log)
-  return freeze(playbook)
+  return stopPaths
+}
+
+function deepFreeze (o) {
+  for (const v of Object.values(o)) Object.isFrozen(v) || deepFreeze(v)
+  return Object.freeze(o)
 }
 
-module.exports = buildPlaybook
+module.exports = Object.assign(buildPlaybook, { defaultSchema })

package/lib/config/schema.js

@@ -7,6 +7,23 @@ module.exports = {
     default: undefined,
     arg: 'playbook',
   },
+  antora: {
+    generator: {
+      doc: 'A require request for the generator package name or script to use.',
+      format: String,
+      default: '@antora/site-generator-default',
+      arg: 'generator',
+    },
+    extensions: {
+      doc:
+        'A list of extensions that listen for lifecycle events. ' +
+        'Each extension is specified as a require request string or an object with a require key.',
+      format: 'require-array',
+      default: [],
+      arg: 'extension',
+      preserve: ['data'],
+    },
+  },
   site: {
     start_page: {
       doc: 'The start page for the site, redirected from the site index.',
@@ -54,7 +71,7 @@ module.exports = {
     branches: {
       doc: 'The default branch pattern to use when no specific pattern is provided.',
       format: Array,
-      default: ['HEAD', 'v*'],
+      default: ['HEAD', 'v{0..9}*'],
     },
     edit_url: {
       doc: 'The default edit URL setting when no specific setting is provided.',
@@ -62,9 +79,10 @@ module.exports = {
       default: true,
     },
     sources: {
-      doc: 'The list of git repositories + branch patterns to use.',
+      doc: 'The list of git repository urls, references, and start paths to use as content sources.',
       format: Array,
       default: [],
+      preserve: ['version'],
     },
     tags: {
       doc: 'The default tag pattern to use when no specific pattern is provided.',
@@ -113,12 +131,21 @@ module.exports = {
       format: 'map',
       default: {},
       arg: 'attribute',
+      preserve: true,
     },
     extensions: {
-      doc: 'A list of require paths for registering extensions per instance of the AsciiDoc processor.',
+      doc:
+        'A list of extensions to register either globally or per instance of the AsciiDoc processor. ' +
+        'Each extension is specified as a require request string.',
       format: Array,
       default: [],
     },
+    sourcemap: {
+      doc: 'Enables the sourcemap option on the AsciiDoc processor, which adds file and line information to blocks.',
+      format: Boolean,
+      default: false,
+      arg: 'asciidoc-sourcemap',
+    },
   },
   git: {
     credentials: {
@@ -141,6 +168,23 @@ module.exports = {
       format: Boolean,
       default: true,
     },
+    fetch_concurrency: {
+      doc: 'The maximum number of fetch or clone operations that are permitted to run at once. Use 0 for unlimited.',
+      format: 'int',
+      default: 0,
+    },
+    plugins: {
+      credential_manager: {
+        doc: 'A require request for a plugin to replace the built-in credential manager used by the git client.',
+        format: String,
+        default: undefined,
+      },
+      http: {
+        doc: 'A require request for a plugin to replace the built-in HTTP client used by the git client.',
+        format: String,
+        default: undefined,
+      },
+    },
   },
   network: {
     http_proxy: {
@@ -199,31 +243,59 @@ module.exports = {
         arg: 'log-level',
         env: 'ANTORA_LOG_LEVEL',
       },
+      level_format: {
+        doc: 'Set the format to use for the log level in structured log messages.',
+        format: ['number', 'label'],
+        default: 'label',
+        arg: 'log-level-format',
+        env: 'ANTORA_LOG_LEVEL_FORMAT',
+      },
       failure_level: {
         doc: 'Set the log level tolerance that, when exceeded, will cause the application to fail on exit.',
-        format: ['all', 'debug', 'info', 'warn', 'error', 'fatal', 'silent'],
-        default: undefined,
-        arg: 'failure-level',
+        format: ['warn', 'error', 'fatal', 'none'],
+        default: 'fatal',
+        arg: 'log-failure-level',
         env: 'ANTORA_LOG_FAILURE_LEVEL',
       },
       format: new Proxy(
         {
-          doc: 'Set the format of log messages. (default: structured if CI=true, pretty otherwise)',
-          format: ['pretty', 'structured', 'json'],
+          doc: 'Set the format of log messages. Defaults to json if CI=true, pretty otherwise.',
+          format: ['json', 'pretty'],
           default: undefined,
           arg: 'log-format',
           env: 'ANTORA_LOG_FORMAT',
         },
         {
           get (target, property) {
-            return property === 'default'
-              ? process.env.CI === 'true' || process.env.NODE_ENV === 'test'
-                ? 'structured'
-                : 'pretty'
-              : target[property]
+            if (property !== 'default') return target[property]
+            return process.env.CI === 'true' || process.env.NODE_ENV === 'test' ? 'json' : 'pretty'
           },
         }
       ),
+      destination: {
+        file: {
+          doc: 'Write log messages to this file or stream. Defaults to stderr if format is pretty, stdout otherwise.',
+          format: String,
+          default: undefined,
+          arg: 'log-file',
+          env: 'ANTORA_LOG_FILE',
+        },
+        append: {
+          doc: 'Whether to append messages to the log file if it already exists.',
+          format: Boolean,
+          default: true,
+        },
+        buffer_size: {
+          doc: 'The size of the log buffer that must be exceeded before writing a chunk to the destination.',
+          format: 'int',
+          default: 0,
+        },
+        sync: {
+          doc: 'Whether to immediately flush messages to the destination when the buffer size is exceeded.',
+          format: Boolean,
+          default: true,
+        },
+      },
     },
   },
   urls: {
@@ -250,7 +322,7 @@ module.exports = {
     },
     redirect_facility: {
       doc: 'The facility for handling page alias and start page redirections.',
-      format: ['disabled', 'httpd', 'netlify', 'nginx', 'static'],
+      format: ['disabled', 'gitlab', 'httpd', 'netlify', 'nginx', 'static'],
       default: 'static',
       arg: 'redirect-facility',
     },
@@ -274,4 +346,15 @@ module.exports = {
       default: undefined,
     },
   },
+  [Symbol.for('convict.beforeValidate')]: ({ _schema: schema, _instance: data }) => {
+    const runtime = data.runtime
+    if (runtime.silent) {
+      if (runtime.quiet === false) runtime.quiet = true
+      if (runtime.log.level !== 'silent') runtime.log.level = 'silent'
+    }
+    const site = data.site
+    if (site.__private__google_analytics_key != null) site.keys.google_analytics = site.__private__google_analytics_key
+    delete site.__private__google_analytics_key
+    delete schema._cvtProperties.site._cvtProperties.__private__google_analytics_key
+  },
 }

package/lib/solitary-convict.js

@@ -85,6 +85,25 @@ function registerFormats (convict) {
       return accum
     },
   })
+  convict.addFormat({
+    name: 'require-array',
+    validate: (val) => {
+      if (!Array.isArray(val)) throw new Error('must be of type Array')
+    },
+    coerce: (val, config, name) => {
+      const accum = config && config.has(name) ? config.get(name) : []
+      val.split(',').forEach((v) => {
+        if (~accum.indexOf(v)) return
+        const match = accum.find((it) => it.constructor === Object && it.id === v)
+        if (match) {
+          if (match.enabled === false) match.enabled = true
+        } else {
+          accum.push(v)
+        }
+      })
+      return accum
+    },
+  })
   convict.addFormat({
     name: 'boolean-or-string',
     validate: (val) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antora/playbook-builder",
-  "version": "3.0.0-alpha.6",
+  "version": "3.0.0-beta.1",
   "description": "Builds a playbook object from user input for configuring successive documentation components in an Antora pipeline.",
   "license": "MPL-2.0",
   "author": "OpenDevise Inc. (https://opendevise.com)",
@@ -16,15 +16,14 @@
   },
   "main": "lib/index.js",
   "dependencies": {
-    "@antora/logger": "3.0.0-alpha.6",
     "@iarna/toml": "~2.2",
-    "camelcase-keys": "~6.2",
-    "convict": "~6.1",
+    "camelcase-keys": "~7.0",
+    "convict": "~6.2",
     "js-yaml": "~4.1",
     "json5": "~2.2"
   },
   "engines": {
-    "node": ">=10.17.0"
+    "node": ">=12.21.0"
   },
   "files": [
     "lib/"
@@ -37,5 +36,5 @@
     "static site",
     "web publishing"
   ],
-  "gitHead": "38ec002e88eede3ce5c401a6e226d1a0356945c5"
+  "gitHead": "7c5ef1ea93dd489af533c80a936c736013c41769"
 }