@antora/content-classifier 3.2.0-alpha.1 → 3.2.0-alpha.10

package/lib/classify-content.js

@@ -2,69 +2,110 @@
 
 const ContentCatalog = require('./content-catalog')
 const collateAsciiDocAttributes = require('@antora/asciidoc-loader/config/collate-asciidoc-attributes')
+const logger = require('./logger')
+const summarizeFileLocation = require('./util/summarize-file-location')
+const families = { attachments: true, examples: true, images: true, pages: true, partials: true }
 
 /**
  * Organizes the raw aggregate of virtual files into a {ContentCatalog}.
  *
  * @memberof content-classifier
  *
- * @param {Object} playbook - The configuration object for Antora.
+ * @param {Object} playbook - The configuration object for Antora. See ContentCatalog constructor for relevant keys.
  * @param {Object} playbook.site - Site-related configuration data.
  * @param {String} playbook.site.startPage - The start page for the site; redirects from base URL.
- * @param {Object} playbook.urls - URL settings for the site.
- * @param {String} playbook.urls.htmlExtensionStyle - The style to use when computing page URLs.
  * @param {Object} aggregate - The raw aggregate of virtual file objects to be classified.
  * @param {Object} [siteAsciiDocConfig={}] - Site-wide AsciiDoc processor configuration options.
- * @returns {ContentCatalog} A structured catalog of content components and virtual content files.
+ * @param {Function} [onComponentsRegistered] - A function (optionally async) to invoke after components are
+ *  registered. Must return an instance of ContentCatalog. If async, this function will also return a Promise.
+ *
+ * @returns {ContentCatalog} A structured catalog of content components, versions, and virtual content files.
  */
-function classifyContent (playbook, aggregate, siteAsciiDocConfig = {}) {
-  const contentCatalog = new ContentCatalog(playbook)
-  aggregate
-    .reduce((accum, componentVersionData) => {
-      // drop files since they aren't needed to register component version
-      // drop startPage to defer registration of start page
-      const { name, version, files, startPage, ...descriptor } = Object.assign({}, componentVersionData, {
-        asciidoc: resolveAsciiDocConfig(siteAsciiDocConfig, componentVersionData),
-      })
-      return new Map(accum).set(
-        contentCatalog.registerComponentVersion(name, version, descriptor),
-        componentVersionData
-      )
-    }, new Map())
-    .forEach((componentVersionData, componentVersion) => {
-      const { name, version } = componentVersion
-      const { files, nav, startPage } = componentVersionData
-      componentVersionData.files = undefined // clean up memory
-      files.forEach((file) => allocateSrc(file, name, version, nav) && contentCatalog.addFile(file, componentVersion))
-      contentCatalog.registerComponentVersionStartPage(name, componentVersion, startPage)
+function classifyContent (playbook, aggregate, siteAsciiDocConfig = {}, onComponentsRegistered = undefined) {
+  const siteStartPage = playbook.site.startPage
+  let contentCatalog = registerComponentVersions(new ContentCatalog(playbook), aggregate, siteAsciiDocConfig)
+  return typeof onComponentsRegistered === 'function' &&
+    (contentCatalog = onComponentsRegistered(contentCatalog)) instanceof Promise
+    ? contentCatalog.then((contentCatalogValue) => addFilesAndRegisterStartPages(contentCatalogValue, siteStartPage))
+    : addFilesAndRegisterStartPages(contentCatalog, siteStartPage)
+}
+
+function registerComponentVersions (contentCatalog, aggregate, siteAsciiDocConfig) {
+  for (const componentVersionBucket of aggregate) {
+    // advance files, nav, and startPage to component version to be used in later phase
+    const { name, version, files, nav, startPage, ...data } = Object.assign(componentVersionBucket, {
+      asciidoc: resolveAsciiDocConfig(siteAsciiDocConfig, componentVersionBucket),
     })
-  contentCatalog.registerSiteStartPage(playbook.site.startPage)
+    Object.assign(contentCatalog.registerComponentVersion(name, version, data), { files, nav, startPage })
+  }
+  return contentCatalog
+}
+
+function addFilesAndRegisterStartPages (contentCatalog, siteStartPage) {
+  for (const { versions: componentVersions } of contentCatalog.getComponents()) {
+    for (const componentVersion of componentVersions) {
+      const { name: component, version, files = [], nav, startPage } = componentVersion
+      const navResolved = nav && (nav.resolved = new Set())
+      const rootFiles = []
+      for (let file, i = 0; (file = files[i]); i++) {
+        files[i] = undefined // free memory
+        const outcome = allocateSrc(file, component, version, nav)
+        if (outcome) {
+          contentCatalog.addFile(file, componentVersion)
+        } else if (outcome == null) {
+          rootFiles.push(file)
+        }
+      }
+      if (rootFiles.length) {
+        for (let file, i = 0; (file = rootFiles[i]); i++) {
+          if (file.src.origin.hasModulesDir) continue
+          allocateSrc(file, component, version, null, true) && contentCatalog.addFile(file, componentVersion)
+        }
+      }
+      if (navResolved && nav.length > navResolved.size && new Set(nav).size > navResolved.size) {
+        const loc = summarizeFileLocation({ path: 'antora.yml', src: { origin: nav.origin } })
+        for (const filepath of nav) {
+          if (navResolved.has(filepath)) continue
+          logger.warn('Could not resolve nav entry for %s@%s defined in %s: %s', version, component, loc, filepath)
+        }
+      }
+      contentCatalog.registerComponentVersionStartPage(component, componentVersion, startPage)
+    }
+  }
+  contentCatalog.registerSiteStartPage(siteStartPage)
   return contentCatalog
 }
 
-function allocateSrc (file, component, version, nav) {
-  const extname = file.src.extname
+function allocateSrc (file, component, version, nav, implicitRoot) {
+  const { extname, family, origin } = file.src
+  if (family && family !== 'nav') {
+    Object.assign(file.src, { component, version })
+    file.src.moduleRootPath ??= calculateRootPath(file.src.relative.split('/').length)
+    return true
+  }
   const filepath = file.path
-  const navInfo = nav && getNavInfo(filepath, nav)
-  const pathSegments = filepath.split('/')
-  if (navInfo) {
-    if (extname !== '.adoc') return // ignore file
+  const pathSegments = implicitRoot ? ['modules', 'ROOT'].concat(filepath.split('/')) : filepath.split('/')
+  const inModules = pathSegments[0] === 'modules'
+  if (!implicitRoot && origin) origin.hasModulesDir ||= inModules
+  let navInfo
+  if (nav && (navInfo = getNavInfo(filepath, nav))) {
+    if (extname !== '.adoc') return false // ignore file
     file.nav = navInfo
     file.src.family = 'nav'
-    if (pathSegments[0] === 'modules' && pathSegments.length > 2) {
+    if (inModules && pathSegments.length > 2) {
       file.src.module = pathSegments[1]
       // relative to modules/<module>
       file.src.relative = pathSegments.slice(2).join('/')
       file.src.moduleRootPath = calculateRootPath(pathSegments.length - 3)
     } else {
-      // relative to root
+      // relative to content source root
       file.src.relative = filepath
     }
-  } else if (pathSegments[0] === 'modules') {
+  } else if (inModules) {
     let familyFolder = pathSegments[2]
     switch (familyFolder) {
       case 'pages':
-        // pages/_partials location for partials is @deprecated; special designation scheduled to be removed in Antora 4
+        // pages/_partials location for partials is @deprecated; special designation scheduled for removal in Antora 4
         if (pathSegments[3] === '_partials') {
           file.src.family = 'partial'
           // relative to modules/<module>/pages/_partials
@@ -74,29 +115,29 @@ function allocateSrc (file, component, version, nav) {
           // relative to modules/<module>/pages
           file.src.relative = pathSegments.slice(3).join('/')
         } else {
-          return // ignore file
+          return false // ignore file
         }
         break
       case 'assets':
         switch ((familyFolder = pathSegments[3])) {
           case 'attachments':
           case 'images':
-            if (!extname) return // ignore file
+            if (!extname && familyFolder === 'images') return false // ignore file
             file.src.family = familyFolder.substr(0, familyFolder.length - 1)
             // relative to modules/<module>/assets/<family>s
             file.src.relative = pathSegments.slice(4).join('/')
             break
           default:
-            return // ignore file
+            return false // ignore file
         }
         break
-      case 'attachments':
       case 'images':
-        if (!extname) return
+        if (!extname) return false
         file.src.family = familyFolder.substr(0, familyFolder.length - 1)
         // relative to modules/<module>/<family>s
         file.src.relative = pathSegments.slice(3).join('/')
         break
+      case 'attachments':
       case 'examples':
       case 'partials':
         file.src.family = familyFolder.substr(0, familyFolder.length - 1)
@@ -104,12 +145,14 @@ function allocateSrc (file, component, version, nav) {
         file.src.relative = pathSegments.slice(3).join('/')
         break
       default:
-        return // ignore file
+        return false // ignore file
     }
     file.src.module = pathSegments[1]
     file.src.moduleRootPath = calculateRootPath(pathSegments.length - 3)
+  } else if (origin && pathSegments[0] in families) {
+    return // defer file
   } else {
-    return // ignore file
+    return false // ignore file
   }
   file.src.component = component
   file.src.version = version
@@ -127,16 +170,22 @@ function allocateSrc (file, component, version, nav) {
  */
 function getNavInfo (filepath, nav) {
   const index = nav.findIndex((candidate) => candidate === filepath)
-  if (~index) return { index }
+  if (~index) return nav.resolved.add(filepath) && { index }
 }
 
-function resolveAsciiDocConfig (siteAsciiDocConfig, { asciidoc, origins = [] }) {
-  const scopedAttributes = (asciidoc || {}).attributes
+function resolveAsciiDocConfig (siteAsciiDocConfig, { name, version, asciidoc, origins = [] }) {
+  const scopedAttributes = asciidoc?.attributes
   if (scopedAttributes) {
-    const initial = siteAsciiDocConfig.attributes
+    const initial = Object.assign({}, siteAsciiDocConfig.attributes)
+    initial['antora-component-name'] = name
+    initial['antora-component-version'] = version
     const mdc = { file: { path: 'antora.yml', origin: origins[origins.length - 1] } }
     const attributes = collateAsciiDocAttributes(scopedAttributes, { initial, mdc, merge: true })
-    if (attributes !== initial) siteAsciiDocConfig = Object.assign({}, siteAsciiDocConfig, { attributes })
+    if (attributes !== initial) {
+      delete attributes['antora-component-name']
+      delete attributes['antora-component-version']
+      return Object.assign({}, siteAsciiDocConfig, { attributes })
+    }
   }
   return siteAsciiDocConfig
 }

package/lib/content-catalog.js

@@ -5,12 +5,12 @@ const invariably = { void: () => undefined }
 const logger = require('./logger')
 const { lookup: resolveMimeType } = require('./mime-types-with-asciidoc')
 const parseResourceId = require('./util/parse-resource-id')
-const { posix: path } = require('path')
+const { posix: path } = require('node:path')
 const resolveResource = require('./util/resolve-resource')
+const summarizeFileLocation = require('./util/summarize-file-location')
 const versionCompare = require('./util/version-compare-desc')
 
 const { ROOT_INDEX_ALIAS_ID, ROOT_INDEX_PAGE_ID } = require('./constants')
-const SPACE_RX = / /g
 const LOG_WRAP = '\n    '
 
 const $components = Symbol('components')
@@ -42,6 +42,8 @@ class ContentCatalog {
   /**
    * Registers a new component version with the content catalog. Also registers the component if it does not yet exist.
    *
+   * Must be followed by a call to registerComponentVersionStartPage to finalize object.
+   *
    * @param {String} name - The name of the component to which this component version belongs.
    * @param {String} version - The version of the component to register.
    * @param {Object} [descriptor={}] - The configuration data for the component version.
@@ -58,8 +60,13 @@ class ContentCatalog {
    * @returns {Object} The constructed component version object.
    */
   registerComponentVersion (name, version, descriptor = {}) {
-    const { asciidoc, displayVersion, prerelease, startPage: startPageSpec, title, versionSegment } = descriptor
-    const componentVersion = { displayVersion: displayVersion || version || 'default', title: title || name, version }
+    const { asciidoc, displayVersion, prerelease, startPage: startPageRef, title, versionSegment, origins } = descriptor
+    const componentVersion = {
+      displayVersion: displayVersion || version || 'default',
+      title: title || name,
+      version,
+      origins: new Set(origins && typeof origins[Symbol.iterator] === 'function' ? origins : []),
+    }
     if (versionSegment != null) componentVersion.versionSegment = versionSegment
     Object.defineProperty(componentVersion, 'name', { value: name, enumerable: true })
     if (prerelease) {
@@ -73,6 +80,7 @@ class ContentCatalog {
         }
       }
     }
+    // NOTE if no AsciiDoc attributes are defined in the component descriptor, asciidoc is the siteAsciiDocConfig object
     if (asciidoc) componentVersion.asciidoc = asciidoc
     const component = this[$components].get(name)
     if (component) {
@@ -83,10 +91,10 @@ class ContentCatalog {
       let lastVerdict
       const insertIdx = version
         ? componentVersions.findIndex(({ version: candidateVersion, prerelease: candidatePrerelease }) => {
-          return (lastVerdict = versionCompare(candidateVersion, version)) > 1
-            ? !!prerelease === !!candidatePrerelease
-            : lastVerdict > 0 || (lastVerdict < -1 && prerelease && !candidatePrerelease)
-        })
+            return (lastVerdict = versionCompare(candidateVersion, version)) > 1
+              ? !!prerelease === !!candidatePrerelease
+              : lastVerdict > 0 || (lastVerdict < -1 && prerelease && !candidatePrerelease)
+          })
         : prerelease
           ? -1
           : ~(~componentVersions.findIndex(({ prerelease: candidatePrerelease }) => !candidatePrerelease) || -1)
@@ -127,9 +135,9 @@ class ContentCatalog {
         )
       )
     }
-    if (startPageSpec) {
+    if (startPageRef) {
       // @deprecated use separate call to register start page for component version
-      this.registerComponentVersionStartPage(name, componentVersion, startPageSpec === true ? undefined : startPageSpec)
+      this.registerComponentVersionStartPage(name, componentVersion, startPageRef === true ? undefined : startPageRef)
     }
     return componentVersion
   }
@@ -143,36 +151,34 @@ class ContentCatalog {
     if (filesForFamily.has(key)) {
       if (family === 'alias') {
         throw new Error(`Duplicate alias: ${generateResourceSpec(src)}`)
-      } else {
-        const details = [filesForFamily.get(key), file]
-          .map((it, idx) => `${idx + 1}: ${getFileLocation(it)}`)
-          .join(LOG_WRAP)
-        if (family === 'nav') {
-          throw new Error(`Duplicate nav in ${version}@${component}: ${file.path}${LOG_WRAP}${details}`)
-        } else {
-          throw new Error(`Duplicate ${family}: ${generateResourceSpec(src)}${LOG_WRAP}${details}`)
-        }
       }
+      const details = [filesForFamily.get(key), file]
+        .map((it, idx) => `${idx + 1}: ${summarizeFileLocation(it)}`)
+        .join(LOG_WRAP)
+      if (family === 'nav') {
+        throw new Error(`Duplicate nav file: ${file.path} in ${version}@${component}${LOG_WRAP}${details}`)
+      }
+      throw new Error(`Duplicate ${family}: ${generateResourceSpec(src)}${LOG_WRAP}${details}`)
     }
-    // NOTE: if the path property is not set, assume the src likely needs to be prepared
-    // another option is to assume that if the file is not a vinyl object, the src likely needs to be prepared
+    // NOTE: assume that if the file is not a vinyl object, the src likely needs to be prepared
     // a vinyl object is one indication the file was created and prepared by the content aggregator
-    //if (!src.path) prepareSrc(src)
-    //if (!File.isVinyl(file)) file = new File(file)
+    // an alternate approach would be to call prepareSrc if the path property is not set
     if (!File.isVinyl(file)) {
       prepareSrc(src)
       file = new File(file)
     }
     if (family === 'alias') {
       file.mediaType = 'text/html'
-      // NOTE: an alias masquerades as the target file
-      family = file.rel.src.family
       // NOTE: short circuit in case of splat alias (alias -> alias)
-      if (family === 'alias' && (file.pub || {}).splat) return filesForFamily.set(key, file) && file
+      if (file.rel.src.family === 'alias' && file.pub?.splat) return filesForFamily.set(key, file) && file
+      // NOTE the effective family of an alias is a page, which redirects to the target file
+      family = 'page'
       src.mediaType = 'text/asciidoc'
     } else if (!(file.mediaType = src.mediaType) && !('mediaType' in src)) {
       // QUESTION: should we preserve the mediaType property on file if already defined?
-      file.mediaType = src.mediaType = resolveMimeType(src.extname) || (family === 'page' ? 'text/asciidoc' : undefined)
+      file.mediaType = src.mediaType = src.extname
+        ? resolveMimeType(src.extname) || (family === 'page' ? 'text/asciidoc' : undefined)
+        : 'text/plain'
     }
     let publishable
     let activeVersionSegment
@@ -181,18 +187,25 @@ class ContentCatalog {
     } else if ('out' in file) {
       delete file.out
     } else if (
+      !file.private &&
       (family === 'page' || family === 'image' || family === 'attachment') &&
-      ('/' + src.relative).indexOf('/_') < 0
+      (file.private === false || ('/' + src.relative).indexOf('/_') < 0)
     ) {
       publishable = true
       if (componentVersion == null) componentVersion = this.getComponentVersion(component, version) || { version }
-      activeVersionSegment = computeVersionSegment.call(this, componentVersion)
+      activeVersionSegment =
+        'activeVersionSegment' in componentVersion
+          ? componentVersion.activeVersionSegment
+          : computeVersionSegment.call(this, componentVersion)
       file.out = computeOut(src, family, activeVersionSegment, this.htmlUrlExtensionStyle)
     }
     if (!file.pub && (publishable || family === 'nav')) {
       if (activeVersionSegment == null) {
         if (componentVersion == null) componentVersion = this.getComponentVersion(component, version) || { version }
-        activeVersionSegment = computeVersionSegment.call(this, componentVersion)
+        activeVersionSegment =
+          'activeVersionSegment' in componentVersion
+            ? componentVersion.activeVersionSegment
+            : computeVersionSegment.call(this, componentVersion)
       }
       file.pub = computePub(src, file.out, family, activeVersionSegment, this.htmlUrlExtensionStyle)
     }
@@ -239,7 +252,7 @@ class ContentCatalog {
   }
 
   getComponentVersion (component, version) {
-    return (component.versions || (this.getComponent(component) || {}).versions || []).find(
+    return (component.versions || this.getComponent(component)?.versions || []).find(
       ({ version: candidate }) => candidate === version
     )
   }
@@ -267,14 +280,21 @@ class ContentCatalog {
       const accum = []
       for (const candidate of candidates.values()) filter(candidate) && accum.push(candidate)
       return accum
-    } else {
-      return [...candidates.values()]
     }
+    return [...candidates.values()]
   }
 
   // TODO add `follow` argument to control whether alias is followed
   getSiteStartPage () {
-    return this.getById(ROOT_INDEX_PAGE_ID) || (this.getById(ROOT_INDEX_ALIAS_ID) || {}).rel
+    let file
+    if ((file = this.getById(ROOT_INDEX_PAGE_ID))) return file
+    if ((file = this.getById(ROOT_INDEX_ALIAS_ID))) return file.rel
+    const rootComponent = this.getComponent('ROOT')
+    if (!rootComponent) return
+    const version = rootComponent.versions.find(({ activeVersionSegment }) => activeVersionSegment === '')?.version
+    if (!version) return
+    if ((file = this.getById(Object.assign({}, ROOT_INDEX_PAGE_ID, { version })))) return file
+    if ((file = this.getById(Object.assign({}, ROOT_INDEX_ALIAS_ID, { version })))) return file.rel
   }
 
   registerComponentVersionStartPage (name, componentVersion, startPageSpec = undefined) {
@@ -318,7 +338,7 @@ class ContentCatalog {
     }
     if (startPage) {
       componentVersion.url = startPage.pub.url
-    } else {
+    } else if (!componentVersion.url) {
       // QUESTION: should we warn if the default start page cannot be found?
       componentVersion.url = computePub(
         (startPageSrc = prepareSrc(Object.assign({}, indexPageId, { family: 'page' }))),
@@ -328,21 +348,24 @@ class ContentCatalog {
         this.htmlUrlExtensionStyle
       ).url
     }
-
-    Object.defineProperty(
-      componentVersion,
-      'activeVersionSegment',
-      activeVersionSegment === version
-        ? {
-            configurable: true,
-            get () {
-              return this.version
-            },
-          }
-        : { configurable: true, value: activeVersionSegment }
-    )
-
+    Object.defineProperties(componentVersion, {
+      activeVersionSegment:
+        activeVersionSegment === version
+          ? { configurable: true, enumerable: false, get: getVersion }
+          : { configurable: true, enumerable: false, value: activeVersionSegment },
+      files: {
+        configurable: true,
+        enumerable: false,
+        get: getComponentVersionFiles.bind(this, { component, version }),
+      },
+      startPage: {
+        configurable: true,
+        enumerable: false,
+        get: getComponentVersionStartPage.bind(this, { component, version }),
+      },
+    })
     addSymbolicVersionAlias.call(this, componentVersion)
+    return startPage
   }
 
   registerSiteStartPage (startPageSpec) {
@@ -350,11 +373,13 @@ class ContentCatalog {
     const rel = this.resolvePage(startPageSpec)
     if (rel) {
       if (this.getById(ROOT_INDEX_PAGE_ID)) return
-      const indexAlias = this.getById(ROOT_INDEX_ALIAS_ID)
-      if (indexAlias) return indexAlias.synthetic ? Object.assign(indexAlias, { rel }) : undefined
+      if (rel.pub.url === (this.htmlUrlExtensionStyle === 'default' ? '/index.html' : '/')) return
+      const rootIndexAlias = this.getById(ROOT_INDEX_ALIAS_ID)
+      if (rootIndexAlias) return rootIndexAlias.synthetic ? Object.assign(rootIndexAlias, { rel }) : undefined
       const src = Object.assign({}, ROOT_INDEX_ALIAS_ID)
       return this.addFile({ src, rel, synthetic: true }, { version: src.version })
-    } else if (rel === false) {
+    }
+    if (rel === false) {
       logger.warn('Start page specified for site has invalid syntax: %s', startPageSpec)
     } else if (startPageSpec.lastIndexOf(':') > startPageSpec.indexOf(':')) {
       logger.warn('Start page specified for site not found: %s', startPageSpec)
@@ -384,10 +409,10 @@ class ContentCatalog {
         throw new Error(
           existingPage === target
             ? `Page cannot define alias that references itself: ${generateResourceSpec(src)}` +
-              ` (specified as: ${spec})${LOG_WRAP}source: ${getFileLocation(existingPage)}`
+                ` (specified as: ${spec})${LOG_WRAP}source: ${summarizeFileLocation(existingPage)}`
             : `Page alias cannot reference an existing page: ${generateResourceSpec(src)} (specified as: ${spec})` +
-              `${LOG_WRAP}source: ${getFileLocation(target)}` +
-              `${LOG_WRAP}existing page: ${getFileLocation(existingPage)}`
+                `${LOG_WRAP}source: ${summarizeFileLocation(target)}` +
+                `${LOG_WRAP}existing page: ${summarizeFileLocation(existingPage)}`
         )
       }
     } else if (src.version == null) {
@@ -399,7 +424,7 @@ class ContentCatalog {
     if (existingAlias) {
       throw new Error(
         `Duplicate alias: ${generateResourceSpec(src)} (specified as: ${spec})` +
-          `${LOG_WRAP}source: ${getFileLocation(target)}`
+          `${LOG_WRAP}source: ${summarizeFileLocation(target)}`
       )
     }
     // NOTE the redirect producer will populate contents when the redirect facility is 'static'
@@ -432,26 +457,48 @@ class ContentCatalog {
   }
 
   /**
-   * Attempts to resolve a string contextual page ID spec to a file in the catalog.
+   * Attempts to resolve a page reference within the given context to a page in the catalog.
    *
-   * Parses the specified contextual page ID spec into a page ID object, then attempts to lookup a
-   * file with this page ID in the catalog. If a component is specified, but not a version, the
-   * latest version of the component stored in the catalog is used. If a page cannot be resolved,
-   * the search is attempted again for an "alias". If neither a page or alias can be resolved, the
-   * function returns undefined. If the spec does not match the page ID syntax, this function throws
-   * an error.
+   * Parses the specified page reference (i.e., page ID spec) into a partial page ID, expands it
+   * using the provided context, then attempts to locate a file in the page family with that page ID
+   * in this catalog. The family segment is optional.
    *
-   * @param {String} spec - The contextual page ID spec (e.g., version@component:module:topic/page.adoc).
-   * @param {ContentCatalog} catalog - The content catalog in which to resolve the page file.
-   * @param {Object} [ctx={}] - The context to use to qualified the contextual page ID.
+   * If a component is specified, but no version, the latest version of the component stored in the
+   * catalog is used. If a page cannot be resolved, the search is attempted again for an "alias". If
+   * neither a page or alias can be resolved, the function returns undefined. If the syntax of the
+   * reference is invalid, this function throws an error.
    *
-   * @returns {File} The virtual file to which the contextual page ID spec refers, or undefined if the
-   * file cannot be resolved.
+   * @param {String} spec - The contextual page reference (e.g., version@component:module:topic/page.adoc).
+   * @param {Object} [context={}] - The context to use to qualify the page reference.
+   *
+   * @returns {File} The virtual file to which the contextual page reference resolves, or undefined
+   * if the file cannot be resolved.
    */
   resolvePage (spec, context = {}) {
     return this.resolveResource(spec, context, 'page', ['page'])
   }
 
+  /**
+   * Attempts to resolve a resource reference within the given context to a file in the catalog.
+   *
+   * Parses the specified resource reference (i.e., resource ID spec) into a partial resource ID,
+   * expands it using the provided context, then attempts to locate a file with that resource ID in
+   * this catalog.
+   *
+   * If a component is specified, but no version, the latest version of the component stored in the
+   * catalog is used. If a defaultFamily is not specified, the family must be specified either by
+   * the reference or the context. If permittedFamilies are stated, the family must resolve to a
+   * family in this list. If a file cannot be resolved, the function returns undefined. If the
+   * syntax of the reference is invalid, this function throws an error.
+   *
+   * @param {String} spec - The contextual resource reference (e.g., version@component:module:image$topic/image.png).
+   * @param {Object} [context={}] - The context to use to qualify the resource reference.
+   * @param {String} [defaultFamily=undefined] - The default family to use if one is not provided.
+   * @param {Array<String>} [permittedFamilies=undefined] - A list of families that are permitted.
+   *
+   * @returns {File} The virtual file to which the contextual resource reference resolves, or
+   * undefined if the file cannot be resolved.
+   */
   resolveResource (spec, context = {}, defaultFamily = undefined, permittedFamilies = undefined) {
     return resolveResource(spec, this, context, defaultFamily, permittedFamilies)
   }
@@ -493,29 +540,25 @@ function generateResourceSpec ({ component, version, module: module_, family, re
 
 function prepareSrc (src) {
   let { basename, extname, stem } = src
-  let update
   if (basename == null) {
-    update = true
-    basename = path.basename(src.relative)
+    basename = src.basename = path.basename(src.relative)
   }
   if (stem == null) {
-    update = true
     if (extname == null) {
       if (~(extname = basename.lastIndexOf('.'))) {
-        stem = basename.substr(0, extname)
-        extname = basename.substr(extname)
+        src.stem = basename.substr(0, extname)
+        src.extname = basename.substr(extname)
       } else {
-        stem = basename
-        extname = ''
+        src.stem = basename
+        src.extname = ''
       }
     } else {
-      stem = basename.substr(0, basename.length - extname.length)
+      src.stem = basename.substr(0, basename.length - extname.length)
     }
   } else if (extname == null) {
-    update = true
-    extname = basename.substr(stem.length)
+    src.extname = basename.substr(stem.length)
   }
-  return update ? Object.assign(src, { basename, extname, stem }) : src
+  return src
 }
 
 function computeOut (src, family, versionSegment, htmlUrlExtensionStyle) {
@@ -575,7 +618,7 @@ function computePub (src, out, family, versionSegment, htmlUrlExtensionStyle) {
   } else if ((url = '/' + out.path) === '/.') {
     url = '/'
   }
-  pub.url = ~url.indexOf(' ') ? url.replace(SPACE_RX, '%20') : url
+  pub.url = ~url.indexOf(' ') ? url.replaceAll(' ', '%20') : url
   return out ? Object.assign(pub, { moduleRootPath: out.moduleRootPath, rootPath: out.rootPath }) : pub
 }
 
@@ -593,7 +636,7 @@ function addSymbolicVersionAlias (componentVersion) {
 
 function computeVersionSegment (componentVersion, mode) {
   const version = componentVersion.version
-  // special designation for master verson is @deprecated; special designation scheduled to be removed in Antora 4
+  // special designation for master version is @deprecated; special designation scheduled to be removed in Antora 4
   const normalizedVersion = version && version !== 'master' ? version : ''
   const { versionSegment = normalizedVersion } = componentVersion
   if (mode === 'original') return versionSegment
@@ -617,13 +660,16 @@ function computeVersionSegment (componentVersion, mode) {
   return versionSegment
 }
 
-function getFileLocation ({ path: path_, src: { abspath, origin } }) {
-  if (!origin) return abspath || path_
-  const { url, gitdir, worktree, refname, tag, reftype = tag ? 'tag' : 'branch', remote, startPath } = origin
-  let details = `${reftype}: ${refname}`
-  if ('worktree' in origin) details += worktree ? ' <worktree>' : remote ? ` <remotes/${remote}>` : ''
-  if (startPath) details += ` | start path: ${startPath}`
-  return `${abspath || path.join(startPath, path_)} in ${'worktree' in origin ? worktree || gitdir : url} (${details})`
+function getComponentVersionFiles (componentVersionId) {
+  return this.findBy(componentVersionId)
+}
+
+function getComponentVersionStartPage (componentVersionId) {
+  return this.resolvePage('index.adoc', componentVersionId)
+}
+
+function getVersion () {
+  return this.version
 }
 
 module.exports = ContentCatalog

package/lib/util/resolve-resource.js

@@ -26,7 +26,6 @@ const parseResourceId = require('./parse-resource-id')
  */
 function resolveResource (spec, catalog, ctx = {}, defaultFamily = undefined, permittedFamilies = undefined) {
   const id = parseResourceId(spec, ctx, defaultFamily, permittedFamilies)
-
   if (!id || !id.family) return false
   if (id.version == null) {
     const component = catalog.getComponent(id.component)
@@ -34,10 +33,9 @@ function resolveResource (spec, catalog, ctx = {}, defaultFamily = undefined, pe
     id.version = component.latest.version
   }
   if (!id.module) id.module = 'ROOT'
-
   return (
     catalog.getById(id) ||
-    (id.family === 'page' ? (catalog.getById(Object.assign({}, id, { family: 'alias' })) || {}).rel : undefined)
+    (id.family === 'page' ? catalog.getById(Object.assign({}, id, { family: 'alias' }))?.rel : undefined)
   )
 }
 

package/lib/util/summarize-file-location.js

@@ -0,0 +1,14 @@
+'use strict'
+
+const { posix: path } = require('node:path')
+
+function summarizeFileLocation ({ path: path_, src: { abspath, origin } }) {
+  if (!origin) return abspath || path_
+  const { url, gitdir, worktree, refname, tag, reftype = tag ? 'tag' : 'branch', remote, startPath } = origin
+  let details = `${reftype}: ${refname}`
+  if ('worktree' in origin) details += worktree ? ' <worktree>' : remote ? ` <remotes/${remote}>` : ''
+  if (startPath) details += ` | start path: ${startPath}`
+  return `${abspath || path.join(startPath, path_)} in ${'worktree' in origin ? worktree || gitdir : url} (${details})`
+}
+
+module.exports = summarizeFileLocation

package/lib/util/version-compare-desc.js

@@ -24,11 +24,8 @@ function versionCompareDesc (a, b) {
   if (a && b) {
     const semverA = resolveSemver(a)
     const semverB = resolveSemver(b)
-    if (semverA) {
-      return semverB ? -semverCompare(semverA, semverB) : 1
-    } else {
-      return semverB ? -1 : -2 * a.localeCompare(b, 'en', { numeric: true })
-    }
+    if (semverA) return semverB ? -semverCompare(semverA, semverB) : 1
+    return semverB ? -1 : -2 * a.localeCompare(b, 'en', { numeric: true })
   }
   return a ? 1 : -1
 }
@@ -64,23 +61,18 @@ function semverCompare (a, b) {
   const numsA = a.split('.')
   const numsB = b.split('.')
   for (let i = 0; i < 3; i++) {
-    const numA = Number(numsA[i] || 0)
-    const numB = Number(numsB[i] || 0)
-    if (numA > numB) {
-      return 1
-    } else if (numB > numA) {
-      return -1
-    } else if (isNaN(numA)) {
-      if (!isNaN(numB)) return -1
-    } else if (isNaN(numB)) {
+    const numA = Number(numsA[i] ?? 0)
+    const numB = Number(numsB[i] ?? 0)
+    if (numA > numB) return 1
+    if (numB > numA) return -1
+    if (Number.isNaN(numA)) {
+      if (!Number.isNaN(numB)) return -1
+    } else if (Number.isNaN(numB)) {
       return 1
     }
   }
-  if (preA == null) {
-    return preB == null ? 0 : 1
-  } else {
-    return preB == null ? -1 : preA.localeCompare(preB, 'en', { numeric: true })
-  }
+  if (preA == null) return preB == null ? 0 : 1
+  return preB == null ? -1 : preA.localeCompare(preB, 'en', { numeric: true })
 }
 
 module.exports = versionCompareDesc

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antora/content-classifier",
-  "version": "3.2.0-alpha.1",
+  "version": "3.2.0-alpha.10",
   "description": "Organizes aggregated content into a virtual file catalog for use in an Antora documentation 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/content-classifier"
+  },
   "bugs": {
     "url": "https://gitlab.com/antora/antora/issues"
   },
@@ -27,13 +31,13 @@
     "#constants": "./lib/constants.js"
   },
   "dependencies": {
-    "@antora/asciidoc-loader": "3.2.0-alpha.1",
-    "@antora/logger": "3.2.0-alpha.1",
+    "@antora/asciidoc-loader": "3.2.0-alpha.10",
+    "@antora/logger": "3.2.0-alpha.10",
     "mime-types": "~2.1",
-    "vinyl": "~2.2"
+    "vinyl": "~3.0"
   },
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=18.0.0"
   },
   "files": [
     "lib/"
@@ -48,7 +52,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"
   }
 }