@antora/assembler 1.0.0-rc.6 → 1.0.0-rc.7

package/lib/produce-assembly-files.js

@@ -1,20 +1,19 @@
 'use strict'
 
+const collateAsciiDocAttributes = require('./util/collate-asciidoc-attributes')
 const filterComponentVersions = require('./filter-component-versions')
 const produceAssemblyFile = require('./produce-assembly-file')
-const selectMutableAttributes = require('./select-mutable-attributes')
-
-const ATTR_REF_RX = /\\?\{(\w[\w-]*)\}/g
+const identifyMutableAttributes = require('./util/identify-mutable-attributes')
 
 function produceAssemblyFiles (
   loadAsciiDoc,
   contentCatalog,
   assemblerConfig,
-  selectAssemblyProfile,
+  selectAssemblerProfile,
   selectComponentVersions
 ) {
   const { assembly: assemblyConfig } = assemblerConfig
-  selectAssemblyProfile ??= (componentVersion) => ({
+  selectAssemblerProfile ??= (componentVersion) => ({
     attributes: assemblyConfig.attributes,
     doctype: assemblyConfig.doctype,
     insertStartPage: assemblyConfig.insertStartPage,
@@ -30,27 +29,28 @@ function produceAssemblyFiles (
   })
   const baseAssemblyAttributes = assemblyConfig.attributes
   const publishableFiles = contentCatalog.getFiles().filter((file) => file.out && file.pub)
+  const reducerExtension = require('@asciidoctor/reducer') // require lazily to wait for Opal to be defined
   let siteRoot
   const configMdc = assemblerConfig.file ? { file: { path: assemblerConfig.file } } : {}
   selectComponentVersions ??= filterComponentVersions.bind(null, assemblerConfig.componentVersionFilter)
   return selectComponentVersions(contentCatalog.getComponents()).reduce((accum, componentVersion) => {
-    const assemblyModel = selectAssemblyProfile(componentVersion)
+    const assemblyModel = selectAssemblerProfile(componentVersion)
     const { attributes: assemblyAttributes, logger, navigation, rootLevel } = assemblyModel
     if (!navigation) return accum
     const contextualLogger = logger ? { warn: logger.warn.bind(logger, configMdc) } : undefined
     const { name: componentName, version, title } = componentVersion
-    const componentVersionAsciiDocConfig = getAsciiDocConfigWithAsciidoctorReducerExtension(componentVersion)
+    const asciidocConfig = getAsciiDocConfigWithAsciidoctorReducerExtension(componentVersion, reducerExtension)
     let sourceHighlighter
     if ('source-highlighter' in assemblyAttributes) {
       sourceHighlighter = assemblyAttributes['source-highlighter']
       delete assemblyAttributes['source-highlighter']
     }
     const mergedAsciiDocAttributes = collateAsciiDocAttributes(
-      Object.assign({}, componentVersionAsciiDocConfig.attributes),
+      Object.assign({}, asciidocConfig.attributes),
       assemblyAttributes,
       contextualLogger
     )
-    const mergedAsciiDocConfig = Object.assign({}, componentVersionAsciiDocConfig, {
+    const mergedAsciiDocConfig = Object.assign({}, asciidocConfig, {
       attributes: mergedAsciiDocAttributes,
     })
     assemblyModel.filetype = baseAssemblyAttributes['assembler-filetype']
@@ -82,33 +82,10 @@ function produceAssemblyFiles (
     } else if (!(assemblyModel.filetype === 'pdf' && assemblyModel.linkReferenceStyle === 'relative')) {
       assemblyModel.linkReferenceStyle = 'absolute'
     }
-    const rootEntry = { content: title }
-    let startPage =
-      'startPage' in componentVersion
-        ? componentVersion.startPage
-        : contentCatalog.resolvePage('index.adoc', { component: componentName, version })
-    if (startPage && startPage.src.component === componentName && startPage.src.version === version) {
-      if (assemblyModel.insertStartPage) {
-        const navtitle = startPage.asciidoc?.navtitle || rootEntry.content
-        Object.assign(rootEntry, { navtitle, url: startPage.pub.url, urlType: 'internal', roles: ['page'] })
-      }
-    } else {
-      // Q: should we always use a reference page as startPage for computing mutableAttributes?
-      startPage = contentCatalog.createFile({
-        src: {
-          component: componentVersion.name,
-          version: componentVersion.version,
-          componentVersion,
-          module: 'ROOT',
-          family: 'page',
-          relative: 'index.adoc',
-          origin: (componentVersion.origins || [])[0],
-        },
-      })
-      startPage.path = ['modules', startPage.src.module, startPage.src.family + 's', startPage.src.relative].join('/')
-    }
-    const mutableAttributes = selectMutableAttributes(loadAsciiDoc, contentCatalog, startPage, mergedAsciiDocConfig)
-    prepareOutlines(navigation, rootEntry, rootLevel).reduce((any, outline) => {
+    const outlineRoot = { content: title }
+    const startPage = resolveStartPage(contentCatalog, componentVersion, assemblyModel.insertStartPage, outlineRoot)
+    const mutableAttributes = identifyMutableAttributes(loadAsciiDoc, contentCatalog, startPage, mergedAsciiDocConfig)
+    prepareOutlines(navigation, outlineRoot, rootLevel).reduce((any, outline) => {
       const assemblyFile = produceAssemblyFile(
         loadAsciiDoc,
         contentCatalog,
@@ -132,25 +109,54 @@ function produceAssemblyFiles (
   }, [])
 }
 
-function getAsciiDocConfigWithAsciidoctorReducerExtension (componentVersion) {
-  const asciidoctorReducerExtension = require('@asciidoctor/reducer') // NOTE: must be required lazily
+function getAsciiDocConfigWithAsciidoctorReducerExtension (componentVersion, reducerExtension) {
   const asciidocConfig = componentVersion.asciidoc
-  const extensions = [asciidoctorReducerExtension]
+  const extensions = [reducerExtension]
   const configuredExtensions = asciidocConfig.extensions || []
-  if (!configuredExtensions.length) return Object.assign({}, asciidocConfig, { extensions, sourcemap: true })
-  return Object.assign({}, asciidocConfig, {
-    extensions: configuredExtensions.reduce((accum, candidate) => {
-      if (candidate !== asciidoctorReducerExtension) accum.push(candidate)
-      return accum
-    }, extensions),
-    sourcemap: true,
-  })
+  return configuredExtensions.length
+    ? Object.assign({}, asciidocConfig, {
+        extensions: configuredExtensions.reduce((accum, candidate) => {
+          if (candidate !== reducerExtension) accum.push(candidate)
+          return accum
+        }, extensions),
+        sourcemap: true,
+      })
+    : Object.assign({}, asciidocConfig, { extensions, sourcemap: true })
 }
 
 function includedInNav (items, url) {
   return items.find((it) => it.url === url || includedInNav(it.items || [], url))
 }
 
+function resolveStartPage (contentCatalog, componentVersion, insertStartPage, outlineRoot) {
+  const { name: componentName, version } = componentVersion
+  let startPage =
+    'startPage' in componentVersion
+      ? componentVersion.startPage
+      : contentCatalog.resolvePage('index.adoc', { component: componentName, version })
+  if (startPage && startPage.src.component === componentName && startPage.src.version === version) {
+    if (insertStartPage) {
+      const navtitle = startPage.asciidoc?.navtitle || outlineRoot.content
+      Object.assign(outlineRoot, { navtitle, url: startPage.pub.url, urlType: 'internal', roles: ['page'] })
+    }
+  } else {
+    startPage = contentCatalog.createFile({
+      src: {
+        component: componentName,
+        version,
+        componentVersion,
+        module: 'ROOT',
+        family: 'page',
+        relative: 'index.adoc',
+        origin: componentVersion.origins?.values().next().value,
+      },
+    })
+    // FIXME remove once upgrading to Antora 3.2.0
+    startPage.path = ['modules', startPage.src.module, startPage.src.family + 's', startPage.src.relative].join('/')
+  }
+  return startPage
+}
+
 function prepareOutlines (navigation, rootEntry, rootLevel) {
   const singleEntry = navigation.length === 1
   const items = navigation.reduce((accum, it) => {
@@ -174,37 +180,9 @@ function prepareOutlines (navigation, rootEntry, rootLevel) {
   return items
 }
 
-function collateAsciiDocAttributes (collated, additional, logger) {
-  Object.entries(additional).forEach(([name, val]) => {
-    if (val && val.constructor === String) {
-      let alias
-      val = val.replace(ATTR_REF_RX, (ref, refname) => {
-        if (ref.charAt() === '\\') return ref.substring(1)
-        const refval = collated[refname]
-        if (refval == null || refval === false) {
-          if (refname in collated && ref === val) {
-            alias = refval
-          } else if (collated['attribute-missing'] === 'warn') {
-            logger?.warn("Skipping reference to missing attribute '%s' in value of '%s' attribute", refname, name)
-          }
-          return ref
-        }
-        if (refval.constructor === String) return refval
-        if (ref !== val) return refval.toString()
-        alias = refval
-        return ref
-      })
-      if (alias !== undefined) val = alias
-    }
-    collated[name] = val
-  })
-  return collated
-}
-
 function extractUrlPath (url) {
-  if (!url) return ''
-  const urlPath = new URL(url).pathname
-  return urlPath === '/' ? '' : urlPath
+  const parsedUrl = url ? URL.parse(url) : null
+  return parsedUrl == null || parsedUrl.pathname === '/' ? '' : parsedUrl.pathname
 }
 
 module.exports = produceAssemblyFiles

package/lib/util/collate-asciidoc-attributes.js

@@ -0,0 +1,32 @@
+'use strict'
+
+const ATTR_REF_RX = /\\?\{(\w[\w-]*)\}/g
+
+function collateAsciiDocAttributes (collated, additional = {}, logger = undefined) {
+  Object.entries(additional).forEach(([name, val]) => {
+    if (val && val.constructor === String) {
+      let alias
+      val = val.replace(ATTR_REF_RX, (ref, refname) => {
+        if (ref.charAt() === '\\') return ref.substring(1)
+        const refval = collated[refname]
+        if (refval == null || refval === false) {
+          if (refname in collated && ref === val) {
+            alias = refval
+          } else if (collated['attribute-missing'] === 'warn') {
+            logger?.warn("Skipping reference to missing attribute '%s' in value of '%s' attribute", refname, name)
+          }
+          return ref
+        }
+        if (refval.constructor === String) return refval
+        if (ref !== val) return refval.toString()
+        alias = refval
+        return ref
+      })
+      if (alias !== undefined) val = alias
+    }
+    collated[name] = val
+  })
+  return collated
+}
+
+module.exports = collateAsciiDocAttributes

package/lib/util/deep-clone.js

@@ -0,0 +1,18 @@
+'use strict'
+
+function deepClone (o) {
+  switch (o.constructor) {
+    case Object:
+      return Object.keys(o).reduce((accum, k) => {
+        const v = o[k]
+        accum[k] = !v || typeof v !== 'object' ? v : deepClone(v)
+        return accum
+      }, {})
+    case Array:
+      return o.map((it) => (!it || typeof it !== 'object' ? it : deepClone(it)))
+    default:
+      return o
+  }
+}
+
+module.exports = deepClone

package/lib/util/identify-mutable-attributes.js

@@ -0,0 +1,25 @@
+'use strict'
+
+/**
+ * Identifies AsciiDoc attributes that can be modified in the body of the page.
+ *
+ * This determination is made by loading a reference page with empty contents, retrieving the list of document attribute
+ * names, then removing any attributes that were passed via the API with some exceptions. The reason for this function
+ * is to be more prudent with which attributes to manage at the boundaries of an assembled page.
+ */
+function identifyMutableAttributes (loadAsciiDoc, contentCatalog, referencePage, asciidocConfig) {
+  const doc = loadAsciiDoc(
+    new referencePage.constructor(
+      Object.assign({}, referencePage, { contents: Buffer.alloc(0), mediaType: 'text/asciidoc' })
+    ),
+    contentCatalog,
+    asciidocConfig
+  )
+  const immutableAttributeNames = doc.attribute_overrides.$keys()['$+'](['doctype'])
+  return Object.entries(doc.getAttributes()).reduce((accum, [name, val]) => {
+    if (!immutableAttributeNames.includes(name)) accum[name] = val
+    return accum
+  }, {})
+}
+
+module.exports = identifyMutableAttributes

package/lib/util/lazy-readable.js

@@ -1,20 +1,23 @@
 'use strict'
 
+const fs = require('node:fs')
 const { PassThrough } = require('node:stream')
 
 // adapted from https://github.com/jpommerening/node-lazystream/blob/master/lib/lazystream.js | license: MIT
 class LazyReadable extends PassThrough {
-  constructor (fn, options) {
-    super(options)
+  constructor (fnOrPath) {
+    super()
+    const fn = typeof fnOrPath === 'function' ? fnOrPath : fs.createReadStream.bind(null, fnOrPath)
     this._read = function () {
       delete this._read // restores original method
-      fn.call(this, options)
-        .on('error', (err) => {
-          let msg = 'Failed to create stream'
-          if (err.syscall === 'open') msg += ` for path '${err.path}'`
-          this.emit('error', new Error(msg, { cause: err }))
-        })
-        .pipe(this)
+      const readable = fn().on('error', (err) => {
+        let msg = 'Failed to create stream'
+        if (err.syscall === 'open') msg += ` for path '${err.path}'`
+        this.emit('error', new Error(msg, { cause: err }))
+      })
+      readable.pipe(this)
+      this.fd = readable.fd
+      this.path = readable.path
       return this._read.apply(this, arguments)
     }
     this.emit('readable')

package/lib/util/rewriter.js

@@ -4,6 +4,7 @@ const createResourceKey = require('./create-resource-key')
 const generateScopedId = require('./generate-scoped-id')
 const parseResourceRef = require('./parse-resource-ref')
 const { resolveEmbedTarget, resolveLinkTarget } = require('./resolver')
+const toHash = require('./to-hash')
 
 const { NAMED_ID_ATTR_RX } = require('./rx')
 
@@ -50,7 +51,9 @@ function rewriteXref (
   sourceLocation
 ) {
   const rawTarget = target
-  if (doc && ~target.indexOf('{')) target = doc.$sub_attributes(target, global.Opal.hash({ attribute_missing: 'skip' }))
+  if (sourceLocation && ~target.indexOf('{')) {
+    target = doc.$sub_attributes(target, toHash({ attribute_missing: 'skip' }))
+  }
   let fragment, resourceRef
   const hashIdx = target.indexOf('#')
   if (~hashIdx) {
@@ -72,21 +75,23 @@ function rewriteXref (
     }
   }
   if (family !== 'page' || !(resource = pagesInOutline?.get(createResourceKey(resourceId)))) {
+    let defaultText
     if ((resource = contentCatalog.getById(resourceId))?.pub) {
       const { linkReferenceStyle, pubRoot, siteRoot } = assemblyModel
-      text ||= resource.asciidoc?.xreftext || rawTarget
+      defaultText = resource.asciidoc?.xreftext || rawTarget
       if (siteRoot || linkReferenceStyle === 'relative') {
         const hash = fragment && !(family === 'page' && fragment === resource.asciidoc.id) ? '#' + fragment : ''
-        return `${resolveLinkTarget(resource, siteRoot, pubRoot, linkReferenceStyle, escapeForInline)}${hash}[${text}]`
+        const linkTarget = resolveLinkTarget(resource, siteRoot, pubRoot, linkReferenceStyle, escapeForInline)
+        return `${linkTarget}${hash}[${updateAttrlist(doc, text, defaultText)}]`
       }
-      if (doc) {
+      if (sourceLocation) {
         const msg = `Cannot create external ${family} reference in assembly because site URL is unknown: ${rawTarget}`
         doc.logger.warn(doc.createLogMessage(msg, { source_location: sourceLocation }))
       }
+    } else if (~target.indexOf(':')) {
+      defaultText = rawTarget // use explicit text so AsciiDoc processor displays it correctly
     }
-    const linkAttrlist = text
-      ? (~text.indexOf(',') ? `"${text}"` : text) + ',role=unresolved'
-      : (~target.indexOf(':') ? `${rawTarget},` : '') + 'role=unresolved'
+    const linkAttrlist = updateAttrlist(doc, text, defaultText, 'unresolved')
     return `link:${rawTarget.charAt() === ':' ? resourceId.module + rawTarget : rawTarget}[${linkAttrlist}]`
   }
   if (fragment === resource.asciidoc.id) fragment = ''
@@ -123,7 +128,7 @@ function rewriteInlineImages (line, contentCatalog, assemblyModel, ctx, assets,
 }
 
 function rewriteImageRef (target, contentCatalog, assemblyModel, ctx, assets, escapeForInline, doc) {
-  if (doc && ~target.indexOf('{')) target = doc.$sub_attributes(target, global.Opal.hash({ attribute_missing: 'skip' }))
+  if (doc && ~target.indexOf('{')) target = doc.$sub_attributes(target, toHash({ attribute_missing: 'skip' }))
   const image = isResourceRef(target) && contentCatalog.resolveResource(target, ctx, 'image', ['image'])
   if (!image?.out) return
   let newTarget
@@ -135,7 +140,6 @@ function rewriteImageRef (target, contentCatalog, assemblyModel, ctx, assets, es
     newTarget = resolveLinkTarget(image, siteRoot, pubRoot, linkReferenceStyle, escapeForInline ?? false, false)
     if (linkReferenceStyle === 'relative') assets.add(image)
   }
-  if (!newTarget) return
   return newTarget
 }
 
@@ -196,6 +200,27 @@ function isResourceRef (str) {
   return !(~str.indexOf(':') && (~str.indexOf('://') || (str.startsWith('data:') && ~str.indexOf(','))))
 }
 
+function updateAttrlist (doc, attrlist, defaultText, role) {
+  const attrs = { named: {}, pos: [] }
+  if (attrlist) {
+    const normalize = ~attrlist.indexOf('\n')
+    if (normalize) attrlist = attrlist.replace(/\n/g, '\x1e')
+    doc
+      .$parse_attributes(attrlist)
+      .$entries()
+      .forEach(([k, v]) => {
+        v = v['$nil?']() ? '' : normalize ? v.replace(/\x1e/g, '\n') : v
+        typeof k === 'number' ? attrs.pos.push(v) : (attrs.named[k] = v)
+      })
+  }
+  if (defaultText) attrs.pos[0] ||= defaultText
+  if (role) attrs.named.role = (attrs.named.role ? attrs.named.role + ' ' : '') + role
+  const entries = []
+  for (const v of attrs.pos) entries.push(~v.indexOf(',') || ~v.indexOf('=') ? `"${v}"` : v)
+  for (const [k, v] of Object.entries(attrs.named)) entries.push(`${k}=` + (~v.indexOf(',') ? `"${v}"` : v))
+  return entries.join(',')
+}
+
 module.exports = {
   rewriteXref,
   rewriteXrefs,

package/lib/util/to-hash.js

@@ -0,0 +1,7 @@
+'use strict'
+
+function toHash (obj = {}) {
+  return global.Opal.hash(obj)
+}
+
+module.exports = toHash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antora/assembler",
-  "version": "1.0.0-rc.6",
+  "version": "1.0.0-rc.7",
   "description": "A JavaScript library that merges AsciiDoc content from multiple pages in an Antora site into assembly files and delegates to an exporter to convert those files to another format, such as PDF.",
   "license": "MPL-2.0",
   "author": "OpenDevise Inc. (https://opendevise.com)",
@@ -27,14 +27,12 @@
     ".": "./lib/index.js",
     "./filter-component-versions": "./lib/filter-component-versions.js",
     "./load-config": "./lib/load-config.js",
-    "./log-command": "./lib/log-command.js",
-    "./produce-assembly-file": "./lib/produce-assembly-file.js",
-    "./produce-assembly-files": "./lib/produce-assembly-files.js",
-    "./select-mutable-attributes": "./lib/select-mutable-attributes.js",
     "./package.json": "./package.json"
   },
   "imports": {
     "#asciidoctor-log-adapter": "./adapters/asciidoctor/jsonl-logger.rb",
+    "#identify-mutable-attributes": "./lib/util/identify-mutable-attributes.js",
+    "#produce-assembly-files": "./lib/produce-assembly-files.js",
     "#unconvert-inline-asciidoc": "./lib/util/unconvert-inline-asciidoc.js"
   },
   "dependencies": {

package/lib/select-mutable-attributes.js

@@ -1,27 +0,0 @@
-'use strict'
-
-function selectMutableAttributes (loadAsciiDoc, contentCatalog, referencePage, asciidocConfig) {
-  const doc = loadAsciiDoc(
-    new referencePage.constructor(
-      Object.assign({}, referencePage, { contents: Buffer.alloc(0), mediaType: 'text/asciidoc' })
-    ),
-    contentCatalog,
-    asciidocConfig
-  )
-  const additionalMutableNames = [
-    'page-component-name',
-    'page-component-version',
-    'page-version',
-    'page-component-display-version',
-    'page-component-title',
-  ]
-  // we could consider using an Asciidoctor extension here to grab attributes passed via the API instead
-  const immutableAttributeNames = doc.attribute_overrides.$keys()['$-'](additionalMutableNames)
-  immutableAttributeNames.push('doctype')
-  return Object.entries(doc.getAttributes()).reduce((accum, [name, val]) => {
-    if (!immutableAttributeNames.includes(name)) accum[name] = val
-    return accum
-  }, {})
-}
-
-module.exports = selectMutableAttributes