@antora/assembler 1.0.0-alpha.5 → 1.0.0-alpha.7

package/lib/asciidoctor/reducer-extension.js

@@ -121,6 +121,7 @@ const IncludeDirectiveTracker = (() => {
     this.$$reducer.includePushed = true
     const directiveLineno = this.lineno - 1 // we're below the include line, which is 1-based
     const prevIncDepth = this.include_stack.length
+    let offset = lineno > 1 ? lineno - 1 : 0
     const result = Opal.send(this, Opal.find_super_dispatcher(this, 'push_include', pushInclude), [
       data,
       file,
@@ -128,12 +129,12 @@ const IncludeDirectiveTracker = (() => {
       lineno,
       attrs,
     ])
-    pushIncludeReplacement.call(
-      this,
-      directiveLineno,
-      this.include_stack.length > prevIncDepth ? this.$lines() : [],
-      lineno > 1 ? lineno - 1 : 0
-    )
+    let incLines = []
+    if (this.include_stack.length > prevIncDepth) {
+      incLines = this.$lines()
+      if (attrs['$key?']('leveloffset') && incLines[0].startsWith(':leveloffset: ') && incLines[1] === '') offset -= 2
+    }
+    pushIncludeReplacement.call(this, directiveLineno, incLines, offset)
     return result
   })
 
@@ -174,8 +175,12 @@ function treeProcessor () {
           let targetLines, idx
           if (into != null) {
             targetLines = incReplacements[into].lines
-            // adds assurance that we're replacing the correct line
-            if (targetLines[(idx = lineno - 1)] !== line) return
+            // adds extra assurance that the program is replacing the correct line
+            if (targetLines[(idx = lineno - 1)] !== line) {
+              const msg = `include directive to reduce not found; expected: "${line}"; got: "${targetLines[idx]}"`
+              doc.getLogger().error(msg)
+              return
+            }
           }
           if ((drop || []).length) {
             drop

package/lib/assemble-content.js

@@ -31,7 +31,7 @@ async function assembleContent (playbook, contentCatalog, converter, { siteCatal
     })
 }
 
-// TODO: if no workspace dir is defined; we shouldn't continue
+// TODO: if no workspace dir is defined, we shouldn't continue
 function prepareWorkspace (publishFiles, aggregateDocuments, contentCatalog, buildConfig) {
   const { dir, clean, keepAggregateSource } = buildConfig
   const files = contentCatalog.findBy({ family: 'image' }).filter(({ out }) => out?.assembled)

package/lib/load-config.js

@@ -1,13 +1,10 @@
 'use strict'
 
-const camelCaseKeys = require('camelcase-keys')
 const expandPath = require('@antora/expand-path-helper')
-const { promises: fsp } = require('fs')
-const os = require('os')
+const fsp = require('node:fs/promises')
+const os = require('node:os')
 const yaml = require('js-yaml')
 
-const CAMEL_CASE_KEYS_OPTS = { deep: true, stopPaths: ['asciidoc'] }
-
 function loadConfig (playbook, configSource = './antora-assembler.yml') {
   return (
     configSource.constructor === Object
@@ -19,9 +16,7 @@ function loadConfig (playbook, configSource = './antora-assembler.yml') {
           () => false
         )
         .then((exists) =>
-          exists
-            ? fsp.readFile(configSource).then((data) => camelCaseKeys(yaml.load(data), CAMEL_CASE_KEYS_OPTS))
-            : {}
+          exists ? fsp.readFile(configSource).then((data) => camelCaseKeys(yaml.load(data), ['asciidoc'])) : {}
         )
   ).then((config) => {
     if (config.enabled === false) return undefined
@@ -32,7 +27,7 @@ function loadConfig (playbook, configSource = './antora-assembler.yml') {
       config.asciidoc.attributes = asciidocAttrs = {}
     }
     if (!('doctype' in asciidocAttrs)) asciidocAttrs.doctype = 'book'
-    asciidocAttrs.revdate = new Date().toISOString().split('T')[0]
+    if (!('revdate' in asciidocAttrs)) asciidocAttrs.revdate = getLocalDate()
     asciidocAttrs['page-partial'] = null
     if (config.componentVersions == null) {
       config.componentVersions = ['*']
@@ -61,4 +56,20 @@ function loadConfig (playbook, configSource = './antora-assembler.yml') {
   })
 }
 
+function camelCaseKeys (o, stopPaths = [], p) {
+  if (Array.isArray(o)) return o.map((it) => camelCaseKeys(it, stopPaths, p))
+  if (o == null || o.constructor !== Object) return o
+  const pathPrefix = p ? p + '.' : ''
+  const accum = {}
+  for (const [k, v] of Object.entries(o)) {
+    const camelKey = k.charAt() + k.substr(1).replace(/_([a-z])/g, (_, l) => l.toUpperCase())
+    accum[camelKey] = ~stopPaths.indexOf(pathPrefix + camelKey) ? v : camelCaseKeys(v, stopPaths, pathPrefix + camelKey)
+  }
+  return accum
+}
+
+function getLocalDate (now = new Date()) {
+  return new Date(now - now.getTimezoneOffset() * 60000).toISOString().split('T')[0]
+}
+
 module.exports = loadConfig

package/lib/produce-aggregate-document.js

@@ -1,22 +1,26 @@
 'use strict'
 
 const File = require('vinyl')
-const { posix: path } = require('path')
+const path = require('node:path/posix')
 
 function produceAggregateDocument (
   loadAsciiDoc,
   contentCatalog,
   componentVersion,
   outline,
+  doctype,
   pages,
   asciidocConfig,
   mutableAttributes,
   sectionMergeStrategy = 'discrete'
 ) {
-  const pagesInOutline = selectPagesInOutline(outline, pages)
+  const pagesInOutline = selectPagesInOutline(
+    outline,
+    pages.filter((it) => it.out)
+  )
   const navtitle = outline.content
   const stem = generateStem(componentVersion, navtitle)
-  const header = buildAsciiDocHeader(componentVersion, navtitle)
+  const header = buildAsciiDocHeader(componentVersion, navtitle, doctype)
   const body = aggregateAsciiDoc(
     loadAsciiDoc,
     contentCatalog,
@@ -44,13 +48,14 @@ function produceAggregateDocument (
   })
 }
 
-function buildAsciiDocHeader (componentVersion, navtitle) {
+function buildAsciiDocHeader (componentVersion, navtitle, doctype = 'book') {
   const doctitle = navtitle === componentVersion.title ? navtitle : `${componentVersion.title}: ${navtitle}`
-  const version = componentVersion.version && componentVersion.version !== 'master' ? componentVersion.version : ''
+  const version = componentVersion.version === 'master' ? '' : componentVersion.version
   return [
     `= ${doctitle}`,
-    ...(version ? [`v${version}`] : []),
-    ':doctype: book', // for debugging only; set via CLI
+    ...(version ? [`:revnumber: ${version}`] : []),
+    ...(doctype === 'article' ? [] : [`:doctype: ${doctype}`]),
+    ':underscore: _',
     // Q: should we pass these via the CLI so they cannot be modified?
     `:page-component-name: ${componentVersion.name}`,
     `:page-component-version:${version ? ' ' + version : ''}`,
@@ -108,9 +113,8 @@ function aggregateAsciiDoc (
     const refs = doc.getCatalog().refs
     // NOTE: in Antora, docname is relative src path from module without file extension
     const docname = doc.getAttribute('docname')
-    //const idprefix = `${module_ === 'ROOT' ? '' : module_ + ':'}${docname}//`
-    const idprefix = `${module_ === 'ROOT' ? '' : module_ + ':'}${docname.replace(/[/]/g, '::')}:::`
-    //const idprefix = `${module_ === 'ROOT' ? '' : module_ + ':'}${docname.replace(/[/]/g, ':-:')}:--:`
+    const docnameForId = docname.replace(/[/]/g, '::').replace(/[.]/g, '-')
+    const idprefix = `${module_ === 'ROOT' ? '' : module_ + ':'}${docnameForId}:::`
     buffer.push('')
     buffer.push(`:docname: ${docname}`)
     buffer.push(`:page-module: ${module_}`)
@@ -205,9 +209,28 @@ function aggregateAsciiDoc (
         for (let i = idx; i < block.lines.length + (delimited ? idx + 2 : idx); i++) ignoreLines.push(i)
       }
     })
+    let skipping
     for (let idx = 0, len = lines.length; idx < len; idx++) {
       if (~ignoreLines.indexOf(idx)) continue
       let line = lines[idx]
+      if (line.startsWith('//')) {
+        if (line[2] !== '/') continue
+        if (line.length > 3 && line === '/'.repeat(line.length)) {
+          if (skipping) {
+            if (line === skipping) skipping = undefined
+          } else {
+            skipping = line
+          }
+          continue
+        }
+      } else if (skipping) {
+        continue
+      }
+      if (line.charAt() === ':' && /^:(?:leveloffset: .*|!leveloffset:|leveloffset!:)$/.test(line)) {
+        if (lines[idx - 1] === '') lines[idx - 1] = undefined
+        lines[idx] = undefined
+        continue
+      }
       if (~line.indexOf('<<')) {
         line = line.replace(/(?<![\\+])<<#?([\p{Alpha}0-9_/.:{][^>,]*?)(?:|, *([^>]+?))?>>/gu, (m, refid, text) => {
           // support natural xref
@@ -223,7 +246,7 @@ function aggregateAsciiDoc (
       }
       if (~line.indexOf('xref:')) {
         // Q: should we allow : as first character of target?
-        line = line.replace(/xref:([\p{Alpha}0-9_/.{#].*?)\[(|.*?[^\\])\]/gu, (m, target, text) => {
+        line = line.replace(/(?<![\\+])xref:([\p{Alpha}0-9_/.{#].*?)\[(|.*?[^\\])\]/gu, (m, target, text) => {
           let pagePart, fragment, targetPage
           const hashIdx = target.indexOf('#')
           if (~hashIdx) {
@@ -245,7 +268,7 @@ function aggregateAsciiDoc (
           }
           if (~pagePart.indexOf('@') || /:.*:/.test(pagePart)) {
             // TODO: handle unresolved page better
-            return siteUrl && (targetPage = contentCatalog.resolvePage(pagePart, page.src))
+            return siteUrl && (targetPage = contentCatalog.resolvePage(pagePart, page.src)) && targetPage.out
               ? `${siteUrl}${targetPage.pub.url}${fragment && '#' + fragment}[${text}]`
               : m
           } else if (pagePart.indexOf(':') < 0) {
@@ -255,11 +278,14 @@ function aggregateAsciiDoc (
           }
           if (!(targetPage = pagesInOutline.get(pagePart))) {
             // TODO: handle unresolved page better
-            return siteUrl && (targetPage = contentCatalog.resolvePage(target, page.src))
+            return siteUrl && (targetPage = contentCatalog.resolvePage(target, page.src)) && targetPage.out
               ? `${siteUrl}${targetPage.pub.url}${fragment && '#' + fragment}[${text}]`
               : m
           }
-          pagePart = pagePart.replace(/[/]/g, '::').replace(/\.adoc$/, '')
+          pagePart = pagePart
+            .replace(/[/]/g, '::')
+            .replace(/\.adoc$/, '')
+            .replace(/[.]/g, '-')
           const refid = `${pagePart}:::${fragment}`
           return `<<${refid}${text && text !== targetPage.title ? ',' + text.replace(/\\]/g, ']') : ''}>>`
         })
@@ -275,7 +301,9 @@ function aggregateAsciiDoc (
               family: 'attachment',
               relative,
             })
-          return attachment ? `${siteUrl}${attachment.pub.url}[${text}]` : m
+          return attachment && attachment.out
+            ? `${siteUrl}${attachment.pub.url.replace(/_/g, '{underscore}')}[${text}]`
+            : m
         })
       }
       if (~line.indexOf('image:') && !line.startsWith('image::')) {
@@ -283,9 +311,9 @@ function aggregateAsciiDoc (
           if (isResourceSpec(target)) {
             const image = contentCatalog.resolveResource(target, page.src, 'image', ['image'])
             // TODO: handle (or report) unresolved image better
-            if (image) {
+            if (image && image.out) {
               image.out.assembled = true
-              return `image:${image.pub.url.substr(1)}[${attrlist}]`
+              return `image:${image.out.path.replace(/_/g, '{underscore}')}[${attrlist}]`
             }
           }
           return m
@@ -305,19 +333,17 @@ function aggregateAsciiDoc (
       let idx = lineno - 1
       if (context === 'section' && !block.getDocument().isNested()) {
         if (block.getSectionName() === 'header') {
-          lines.splice(idx, 1)
+          lines[idx] = undefined
           return
         }
         let blockStyle = sectionMergeStrategy === 'discrete' ? 'discrete' : undefined
-        // FIXME: quick fix; needs more thorough review
-        const leveloffset = Number(doc.getAttribute('leveloffset') || 0)
-        lines[idx] = lines[idx].replace(/^=+( .+)/, (_, rest) => {
-          let targetMarkerLength = block.level + (1 - leveloffset) + level + (enclosed ? 1 : 0)
+        lines[idx] = lines[idx].replace(/^=+ (.+)/, (_, rest) => {
+          let targetMarkerLength = block.level + 1 + level + (enclosed ? 1 : 0)
           if (targetMarkerLength > 6) {
             targetMarkerLength = 6
             blockStyle = 'discrete'
           }
-          return '='.repeat(targetMarkerLength) + rest
+          return '='.repeat(targetMarkerLength) + ' ' + rest
         })
         // NOTE: ID will be undefined if sectids are turned off
         if (block.getId()) rewriteStyleAttribute(block, lines, idx, idprefix, blockStyle)
@@ -327,7 +353,7 @@ function aggregateAsciiDoc (
           let prefix = ''
           // Q: can we use startsWith('image::') in certain cases?
           let imageMacroOffset = (
-            lastImageMacroAt && lastImageMacroAt[0] === idx ? line.substr(0, lastImageMacroAt[1]) : line
+            lastImageMacroAt?.[0] === idx ? line.substr(0, lastImageMacroAt[1]) : line
           ).lastIndexOf('image::')
           if (imageMacroOffset > 0) {
             if (
@@ -344,9 +370,10 @@ function aggregateAsciiDoc (
             if (isResourceSpec(target)) {
               const image = contentCatalog.resolveResource(target, page.src, 'image', ['image'])
               // FIXME: handle (or report) case when image is not resolved
-              if (image) {
-                lines[idx] = `${prefix}image::${image.pub.url.substr(1)}${line.substr(line.indexOf('['))}`
+              if (image && image.out) {
+                const boxedAttrlist = line.substr(line.indexOf('['))
                 image.out.assembled = true
+                lines[idx] = `${prefix}image::${image.out.path}${boxedAttrlist}`
               }
             }
             lastImageMacroAt = [idx, imageMacroOffset]
@@ -358,7 +385,7 @@ function aggregateAsciiDoc (
         if (block.getId()) rewriteStyleAttribute(block, lines, idx, idprefix)
       }
     })
-    buffer.push(...lines)
+    buffer.push(...lines.filter((it) => it !== undefined))
     const attributeEntries = Object.entries(doc.attributes_defined_in_header || {})
     if (attributeEntries.length) {
       const resolvedAttributeEntries = attributeEntries.reduce(
@@ -371,7 +398,7 @@ function aggregateAsciiDoc (
             } else if (val !== initialVal) {
               accum.push(`:${name}:${initialVal ? ' ' + initialVal : ''}`)
             }
-          } else if (val != null && !(doc.isAttributeLocked(name) || name === 'doctype')) {
+          } else if (val != null && !(doc.isAttributeLocked(name) || name === 'doctype' || name === 'leveloffset')) {
             accum.push(`:!${name}:`)
           }
           return accum
@@ -438,7 +465,8 @@ function aggregateAsciiDoc (
 
 function generateStem (componentVersion, title) {
   const { name, version } = componentVersion
-  const segments = [name]
+  const segments = []
+  if (name !== 'ROOT') segments.push(name)
   if (version && version !== 'master') segments.push(version)
   segments.push(
     title
@@ -495,7 +523,7 @@ function rewriteStyleAttribute (block, lines, idx, idprefix, replacementStyle =
         if (replacementStyle) prevLine = prevLine.replace(/^[^#.%,\]]+/, `[${replacementStyle}`)
       } else {
         prevLine = `[${
-          replacementStyle ? rawStyle.replace(/^[^.%]*]/, replacementStyle) : rawStyle
+          replacementStyle ? rawStyle.replace(/^[^.%]*/, replacementStyle) : rawStyle
         }#${idprefix}${block.getId()}${prevLine.substr(rawStyle.length + 1)}`
       }
     } else {

package/lib/produce-aggregate-documents.js

@@ -1,5 +1,6 @@
 'use strict'
 
+const File = require('vinyl')
 const filterComponentVersions = require('./filter-component-versions')
 const produceAggregateDocument = require('./produce-aggregate-document')
 const selectMutableAttributes = require('./select-mutable-attributes')
@@ -7,8 +8,9 @@ const selectMutableAttributes = require('./select-mutable-attributes')
 function produceAggregateDocuments (loadAsciiDoc, contentCatalog, assemblerConfig) {
   const { insertStartPage, rootLevel, sectionMergeStrategy, asciidoc: assemblerAsciiDocConfig } = assemblerConfig
   const assemblerAsciiDocAttributes = Object.assign({}, assemblerAsciiDocConfig.attributes)
-  const { doctype, 'source-highlighter': sourceHighlighter } = assemblerAsciiDocAttributes
+  const { doctype, revdate, 'source-highlighter': sourceHighlighter } = assemblerAsciiDocAttributes
   delete assemblerAsciiDocAttributes.doctype
+  delete assemblerAsciiDocAttributes.revdate
   delete assemblerAsciiDocAttributes['source-highlighter']
   return filterComponentVersions(contentCatalog.getComponents(), assemblerConfig.componentVersions).reduce(
     (accum, componentVersion) => {
@@ -16,7 +18,7 @@ function produceAggregateDocuments (loadAsciiDoc, contentCatalog, assemblerConfi
       if (!navigation) return accum
       const componentVersionAsciiDocConfig = getAsciiDocConfigWithAsciidoctorReducerExtension(componentVersion)
       const mergedAsciiDocConfig = Object.assign({}, componentVersionAsciiDocConfig, {
-        attributes: Object.assign({}, componentVersionAsciiDocConfig.attributes, assemblerAsciiDocAttributes),
+        attributes: Object.assign({ revdate }, componentVersionAsciiDocConfig.attributes, assemblerAsciiDocAttributes),
       })
       const rootEntry = { content: title }
       const startPage = contentCatalog.getComponentVersionStartPage(componentName, version)
@@ -28,10 +30,16 @@ function produceAggregateDocuments (loadAsciiDoc, contentCatalog, assemblerConfi
           Object.assign(rootEntry, { url: startPageUrl, urlType: 'internal' })
         }
       }
-      // Q: should we use an artificial page instead or as fallback?
-      const mutableAttributes = startPage
-        ? selectMutableAttributes(loadAsciiDoc, contentCatalog, startPage, mergedAsciiDocConfig)
-        : {}
+      // Q: should we always use a reference page here?
+      const startPage_ =
+        startPage ??
+        createFile({
+          component: componentVersion.name,
+          version: componentVersion.version,
+          relative: '.reference-page.adoc',
+          origin: (componentVersion.origins || [])[0],
+        })
+      const mutableAttributes = selectMutableAttributes(loadAsciiDoc, contentCatalog, startPage_, mergedAsciiDocConfig)
       delete mutableAttributes.doctype
       accum = accum.concat(
         prepareOutlines(navigation, rootEntry, rootLevel).map((outline) =>
@@ -40,6 +48,7 @@ function produceAggregateDocuments (loadAsciiDoc, contentCatalog, assemblerConfi
             contentCatalog,
             componentVersion,
             outline,
+            doctype,
             contentCatalog.getPages((page) => page.out),
             mergedAsciiDocConfig,
             mutableAttributes,
@@ -57,6 +66,30 @@ function produceAggregateDocuments (loadAsciiDoc, contentCatalog, assemblerConfi
   )
 }
 
+function createFile (src) {
+  const familySegment = (src.family ??= 'page') + 's'
+  const path = `modules/${(src.module ??= 'ROOT')}/${familySegment}/${src.relative}`
+  const moduleRootPath = Array(src.relative.split('/').length - 1)
+    .fill('..')
+    .join('/')
+  const outPath = [
+    src.component === 'ROOT' ? '' : src.component,
+    src.version,
+    src.module === 'ROOT' ? '' : src.module,
+    src.family === 'page' ? '' : '_' + familySegment,
+    src.family === 'page' ? src.relative.replace(/\.adoc$/, '.html') : src.relative,
+  ]
+    .filter((it) => it)
+    .join('/')
+  return new File({
+    path,
+    contents: src.contents ?? Buffer.alloc(0),
+    src,
+    out: { path: outPath },
+    pub: { url: '/' + outPath, moduleRootPath },
+  })
+}
+
 function getAsciiDocConfigWithAsciidoctorReducerExtension (componentVersion) {
   const asciidoctorReducerExtension = require('./asciidoctor/reducer-extension') // NOTE: must be required lazily
   const asciidocConfig = componentVersion.asciidoc
@@ -80,13 +113,16 @@ function includedInNav (items, url) {
   return items.find((it) => it.url === url || includedInNav(it.items || [], url))
 }
 
+// when root level is 0, merge the navigation into the rootEntry
+// when root level is 1, create navigation per navigation menu
+// in this case, if there's only a single navigation menu with no title, promote each top-level item to a menu
 function prepareOutlines (navigation, rootEntry, rootLevel) {
   if (rootLevel === 0 || navigation.length === 1) {
     const navBranch =
       navigation.length === 1
         ? navigation[0]
         : { items: navigation.reduce((navTree, it) => navTree.concat(it.content ? it : it.items), []) }
-    return [Object.assign(rootEntry, navBranch)]
+    return rootLevel === 0 || navBranch.content ? [Object.assign(rootEntry, navBranch)] : navBranch.items
   }
   return navigation.reduce((navTree, it) => navTree.concat(it.content ? it : it.items), [rootEntry])
 }

package/lib/util/lazy-readable.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const { PassThrough } = require('stream')
+const { PassThrough } = require('node:stream')
 
 // adapted from https://github.com/jpommerening/node-lazystream/blob/master/lib/lazystream.js | license: MIT
 class LazyReadable extends PassThrough {

package/lib/util/run-command.js

@@ -1,8 +1,8 @@
 'use strict'
 
-const fs = require('fs')
+const fs = require('node:fs')
 const LazyReadable = require('./lazy-readable')
-const { spawn } = require('child_process')
+const { spawn } = require('node:child_process')
 
 const IS_WIN = process.platform === 'win32'
 const DBL_QUOTE_RX = /"/g

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antora/assembler",
-  "version": "1.0.0-alpha.5",
+  "version": "1.0.0-alpha.7",
   "description": "An extension library for Antora that assembles content from multiple pages into a single AsciiDoc file to converted and publish.",
   "license": "MPL-2.0",
   "author": "OpenDevise Inc. (https://opendevise.com)",
@@ -31,8 +31,7 @@
   "dependencies": {
     "@antora/expand-path-helper": "~2.0",
     "braces": "~3.0",
-    "camelcase-keys": "~7.0",
-    "picomatch": "~2.3",
+    "picomatch": "~3.0",
     "vinyl": "~2.2",
     "js-yaml": "~4.1"
   },