@antora/playbook-builder 3.2.0-alpha.1 → 3.2.0-alpha.10

package/README.md

@@ -1,7 +1,7 @@
 # Antora Playbook Builder
 
 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.
+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 aggregates documents from versioned content repositories and processes them using [Asciidoctor](https://asciidoctor.org).

package/lib/build-playbook.js

@@ -2,8 +2,10 @@
 
 const convict = require('./solitary-convict')
 const defaultSchema = require('./config/schema')
-const fs = require('fs')
-const ospath = require('path')
+const fs = require('node:fs')
+const ospath = require('node:path')
+const parseArgs = require('yargs-parser')
+const yaml = require('js-yaml')
 
 /**
  * Builds a playbook object according to the provided schema from the specified
@@ -11,7 +13,7 @@ const ospath = require('path')
  *
  * Accepts an array of command line arguments (in the form of option flags and
  * switches) and a map of environment variables and translates this data into a
- * playbook object according the the specified schema. If no schema is
+ * playbook object according the specified schema. If no schema is
  * specified, the default schema provided by this package is used.
  *
  * @memberof playbook-builder
@@ -28,8 +30,22 @@ const ospath = require('path')
  *   marked in the schema as preserve, all keys in the playbook are camelCased.
  */
 function buildPlaybook (args = [], env = process.env, schema = defaultSchema, beforeValidate = undefined) {
-  const config = Object.assign(convict(schema, { args, env }), { getModel })
-  const playbook = config.has('playbook') && config.get('playbook')
+  const parsedArgs = parseArgs(args, { configuration: { 'dot-notation': false } })
+  const opts = { args: [], env: {} }
+  const config = Object.assign(convict(schema, opts), { getModel, getSchema })
+  Object.assign(opts, { args, env })
+  let playbook
+  if ('playbook' in schema) {
+    const playbookEnv = schema.playbook.env
+    if (playbookEnv != null) playbook = env[playbookEnv]
+    const playbookArg = schema.playbook.arg
+    if (playbookArg != null) playbook = parsedArgs[playbookArg] ?? playbook
+    if (playbook === undefined) {
+      if (config.has('playbook')) playbook = config.get('playbook')
+    } else {
+      config.set('playbook', playbook)
+    }
+  }
   let absPlaybookPath
   if (playbook) {
     if (ospath.extname((absPlaybookPath = ospath.resolve(playbook)))) {
@@ -50,10 +66,11 @@ function buildPlaybook (args = [], env = process.env, schema = defaultSchema, be
     }
   }
   try {
-    if (playbook) {
-      config.loadFile(absPlaybookPath)
-      if (playbook !== absPlaybookPath) config.set('playbook', absPlaybookPath)
-    }
+    Object.assign(opts, { args: [] })
+    playbook ? config.loadFile(absPlaybookPath) : config.load({})
+    importArguments(config, parsedArgs)
+    Object.assign(opts, { args })
+    if (playbook && playbook !== absPlaybookPath) config.set('playbook', absPlaybookPath)
     const beforeValidateFromSchema = config._def[Symbol.for('convict.beforeValidate')]
     if (beforeValidateFromSchema) beforeValidateFromSchema(config)
     if (beforeValidate) beforeValidate(config)
@@ -82,9 +99,8 @@ function camelCaseKeys (o, stopPaths = [], p = '') {
 function getModel (name) {
   let config = this
   const data = config.get(name)
-  let schema = config._schema
+  const schema = config.getSchema(name)
   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' })
@@ -97,6 +113,10 @@ function getModel (name) {
   return model
 }
 
+function getSchema (name) {
+  return name ? name.split('.').reduce((accum, key) => accum._cvtProperties[key], this._schema) : this._schema
+}
+
 function getStopPaths (schemaProperties, schemaPath = [], stopPaths = []) {
   for (const [key, { preserve, _cvtProperties }] of Object.entries(schemaProperties)) {
     if (preserve) {
@@ -110,6 +130,22 @@ function getStopPaths (schemaProperties, schemaPath = [], stopPaths = []) {
   return stopPaths
 }
 
+function importArguments (config, args) {
+  for (const [argName, configKey] of Object.entries(config._argv)) {
+    const argVal = args[argName]
+    if (argVal === undefined) continue
+    const argFormat = config.getSchema(configKey).format
+    let argValStr = argVal
+    if (argFormat === 'map' || argFormat === 'primitive-map') {
+      const dumpOpts = { condenseFlow: true, flowLevel: 0, noCompatMode: true, quotingType: '"' }
+      argValStr = yaml.dump(Array.isArray(argVal) ? argVal : [argVal], dumpOpts)
+    } else if (Array.isArray(argVal)) {
+      argValStr = argVal.join(',')
+    }
+    config.set(configKey, argValStr)
+  }
+}
+
 function getDetails (playbook, absPlaybookPath) {
   if (playbook === absPlaybookPath) return ''
   return ` (${ospath.isAbsolute(playbook) ? '' : 'cwd: ' + process.cwd() + ', '}playbook: ${playbook})`

package/lib/config/schema.js

@@ -17,7 +17,8 @@ module.exports = {
     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.',
+        'Each extension is specified as a require request string or an object with a require key. ' +
+        'May be specified multiple times.',
       format: 'require-array',
       default: [],
       arg: 'extension',
@@ -66,7 +67,7 @@ module.exports = {
   content: {
     branches: {
       doc: 'The default branch pattern to use when no specific pattern is provided.',
-      format: Array,
+      format: 'array-or-string',
       default: ['HEAD', 'v{0..9}*'],
     },
     edit_url: {
@@ -82,9 +83,14 @@ module.exports = {
     },
     tags: {
       doc: 'The default tag pattern to use when no specific pattern is provided.',
-      format: Array,
+      format: 'array-or-string',
       default: undefined,
     },
+    worktrees: {
+      doc: 'The default worktrees pattern to use when no specific pattern is provided.',
+      format: 'boolean-or-array-or-string',
+      default: '.',
+    },
   },
   ui: {
     bundle: {
@@ -167,7 +173,12 @@ module.exports = {
     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,
+      default: 1,
+    },
+    fetch_depth: {
+      doc: 'Preferred number of commits to fetch from remote repository. 0 indicates full history.',
+      format: 'int',
+      default: 1,
     },
     plugins: {
       credential_manager: {
@@ -181,6 +192,11 @@ module.exports = {
         default: undefined,
       },
     },
+    read_concurrency: {
+      doc: 'The maximum number of git indexes that are read into memory at once. Use 0 for unlimited.',
+      format: 'int',
+      default: 0,
+    },
   },
   network: {
     http_proxy: {
@@ -253,23 +269,13 @@ module.exports = {
         arg: 'log-failure-level',
         env: 'ANTORA_LOG_FAILURE_LEVEL',
       },
-      format: new Proxy(
-        {
-          doc: 'Set the format of log messages. Defaults to pretty if CI=true or stdout is a TTY, json otherwise.',
-          format: ['json', 'pretty'],
-          default: undefined,
-          arg: 'log-format',
-          env: 'ANTORA_LOG_FORMAT',
-        },
-        {
-          get (target, property) {
-            if (property !== 'default') return target[property]
-            return process.env.CI === 'true' || (process.env.IS_TTY || String(process.stdout.isTTY)) === 'true'
-              ? 'pretty'
-              : 'json'
-          },
-        }
-      ),
+      format: {
+        doc: 'Set the format of log messages. Defaults to pretty if CI=true or stdout is a TTY, json otherwise.',
+        format: ['json', 'pretty'],
+        default: 'auto',
+        arg: 'log-format',
+        env: 'ANTORA_LOG_FORMAT',
+      },
       destination: {
         file: {
           doc: 'Write log messages to this file or stream. Defaults to stderr if format is pretty, stdout otherwise.',
@@ -344,8 +350,13 @@ module.exports = {
       default: undefined,
     },
   },
-  [Symbol.for('convict.beforeValidate')]: ({ _schema: schema, _instance: data }) => {
+  [Symbol.for('convict.beforeValidate')]: ({ getEnv, _instance: data, _schema: schema }) => {
     const runtime = data.runtime
+    const log = runtime.log
+    if (log.format === 'auto') {
+      const env = getEnv()
+      log.format = env.CI === 'true' || (env.IS_TTY || String(process.stdout.isTTY)) === 'true' ? 'pretty' : 'json'
+    }
     if (runtime.silent) {
       if (runtime.quiet === false) runtime.quiet = true
       if (runtime.log.level !== 'silent') runtime.log.level = 'silent'

package/lib/solitary-convict.js

@@ -5,9 +5,10 @@ const json = require('json5')
 const toml = require('@iarna/toml')
 const yaml = require('js-yaml')
 
-const ARGS_SCANNER_RX = /(?:([^=,]+)|(?==))(?:,|$|=(|("|').*?\3|[^,]+)(?:,|$))/g
 const PRIMITIVE_TYPES = [Boolean, Number, String]
+const COERCE_SCHEMA = yaml.FAILSAFE_SCHEMA
 const YAML_SCHEMA = yaml.CORE_SCHEMA.extend({ implicit: [yaml.types.merge] })
+const YAML_PREFIX_RX = new RegExp('!!((?:auto|str|bool|int|float|seq|map)(?= )|null(?=$))(?: |$)')
 
 /**
  * A convict function wrapper that registers custom formats and parsers and
@@ -35,6 +36,22 @@ function registerParsers (convict) {
 }
 
 function registerFormats (convict) {
+  convict.addFormat({
+    name: 'array-or-string',
+    validate: (val) => {
+      if (!(val == null || val.constructor === String || Array.isArray(val))) {
+        throw new Error('must be an array, string, or null')
+      }
+    },
+  })
+  convict.addFormat({
+    name: 'boolean-or-array-or-string',
+    validate: (val) => {
+      if (!(val == null || typeof val === 'boolean' || val.constructor === String || Array.isArray(val))) {
+        throw new Error('must be a boolean, array, string, or null')
+      }
+    },
+  })
   convict.addFormat({
     name: 'map',
     validate: (val) => {
@@ -43,11 +60,25 @@ function registerFormats (convict) {
     coerce: (val, config, name) => {
       if (config == null) return val
       const accum = config.has(name) ? config.get(name) : {}
-      let match
-      ARGS_SCANNER_RX.lastIndex = 0
-      while ((match = ARGS_SCANNER_RX.exec(val))) {
-        const [, k, v] = match
-        if (k) accum[k] = v ? (v === '-' ? '-' : yaml.load(v, { schema: yaml.CORE_SCHEMA })) : ''
+      const entries = yaml.load(val, { schema: COERCE_SCHEMA })
+      for (const entry of Array.isArray(entries) ? entries : [entries]) {
+        let k = entry
+        let v = ''
+        const equalsIdx = entry.indexOf('=')
+        if (~equalsIdx) {
+          if (!(k = entry.slice(0, equalsIdx))) continue
+          v = entry.slice(equalsIdx + 1)
+        }
+        let parsed = v
+        if (v) {
+          const match = v.match(YAML_PREFIX_RX)
+          if (match) {
+            try {
+              parsed = yaml.load(match[1] === 'auto' ? v.slice(7) : v, { schema: yaml.CORE_SCHEMA })
+            } catch {}
+          }
+        }
+        accum[k] = parsed
       }
       return accum
     },
@@ -68,20 +99,26 @@ function registerFormats (convict) {
     coerce: (val, config, name) => {
       if (config == null) return val
       const accum = config.has(name) ? config.get(name) : {}
-      let match
-      ARGS_SCANNER_RX.lastIndex = 0
-      while ((match = ARGS_SCANNER_RX.exec(val))) {
-        const [, k, v] = match
-        if (k) {
-          let parsed
-          if (v && v !== '-') {
-            parsed = yaml.load(v, { schema: yaml.CORE_SCHEMA })
-            if (parsed && PRIMITIVE_TYPES.indexOf(parsed.constructor) < 0) parsed = v
-          } else {
-            parsed = v || ''
+      const entries = yaml.load(val, { schema: COERCE_SCHEMA })
+      for (const entry of Array.isArray(entries) ? entries : [entries]) {
+        let k = entry
+        let v = ''
+        const equalsIdx = entry.indexOf('=')
+        if (~equalsIdx) {
+          if (!(k = entry.slice(0, equalsIdx))) continue
+          v = entry.slice(equalsIdx + 1)
+        }
+        let parsed = v
+        if (v) {
+          const match = v.match(YAML_PREFIX_RX)
+          if (match) {
+            try {
+              parsed = yaml.load(match[1] === 'auto' ? v.slice(7) : v, { schema: yaml.CORE_SCHEMA })
+              if (parsed && !~PRIMITIVE_TYPES.indexOf(parsed.constructor)) parsed = v
+            } catch {}
           }
-          accum[~k.indexOf('-') ? k.replace(/-/g, '_') : k] = parsed
         }
+        accum[~k.indexOf('-') ? k.replace(/-/g, '_') : k] = parsed
       }
       return accum
     },
@@ -89,19 +126,19 @@ function registerFormats (convict) {
   convict.addFormat({
     name: 'require-array',
     validate: (val) => {
-      if (!Array.isArray(val)) throw new Error('must be of type Array')
+      if (!Array.isArray(val)) throw new Error('must be an array')
     },
     coerce: (val, config, name) => {
-      const accum = config && config.has(name) ? config.get(name) : []
-      val.split(',').forEach((v) => {
-        if (~accum.indexOf(v)) return
+      const accum = config?.has(name) ? config.get(name) : []
+      for (const v of val.split(',')) {
+        if (~accum.indexOf(v)) continue
         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
     },
   })
@@ -109,7 +146,7 @@ function registerFormats (convict) {
     name: 'boolean-or-string',
     validate: (val) => {
       if (!(val == null || val.constructor === String || val.constructor === Boolean)) {
-        throw new Error('must be a boolean or string')
+        throw new Error('must be a boolean, string, or null')
       }
     },
   })
@@ -151,7 +188,10 @@ function registerFormats (convict) {
       }
       if (~parsedUrl.pathname.indexOf('%20')) throw new Error('pathname segment must not contain spaces')
     },
-    coerce: (val) => (val.length > 1 && val.charAt(val.length - 1) === '/' ? val.slice(0, -1) : val),
+    coerce: (val) => {
+      if (!val || val === '~') return null
+      return val.length > 1 && val.charAt(val.length - 1) === '/' ? val.slice(0, -1) : val
+    },
   })
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antora/playbook-builder",
-  "version": "3.2.0-alpha.1",
+  "version": "3.2.0-alpha.10",
   "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)",
@@ -10,7 +10,11 @@
     "Hubert SABLONNIÈRE <hubert.sablonniere@gmail.com>"
   ],
   "homepage": "https://antora.org",
-  "repository": "gitlab:antora/antora",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/antora/antora.git",
+    "directory": "packages/playbook-builder"
+  },
   "bugs": {
     "url": "https://gitlab.com/antora/antora/issues"
   },
@@ -26,10 +30,11 @@
     "@iarna/toml": "~2.2",
     "convict": "~6.2",
     "js-yaml": "~4.1",
-    "json5": "~2.2"
+    "json5": "~2.2",
+    "yargs-parser": "~20.2"
   },
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=18.0.0"
   },
   "files": [
     "lib/"
@@ -44,7 +49,7 @@
   ],
   "scripts": {
     "test": "_mocha",
-    "prepublishOnly": "node $npm_config_local_prefix/npm/prepublishOnly.js",
-    "postpublish": "node $npm_config_local_prefix/npm/postpublish.js"
+    "prepublishOnly": "npx -y downdoc@latest --prepublish",
+    "postpublish": "npx -y downdoc@latest --postpublish"
   }
 }