@antora/content-classifier 3.0.0-alpha.7 → 3.0.0-beta.2

package/README.md

@@ -3,7 +3,7 @@
 The Content Classifier is a component in Antora responsible for organizing aggregated content into a virtual file catalog for use in an Antora documentation pipeline.
 
 [Antora](https://antora.org) is a modular static site generator designed for creating documentation sites from AsciiDoc documents.
-Its site generator pipeline aggregates documents from versioned content repositories and processes them using [Asciidoctor](https://asciidoctor.org).
+Its site generator aggregates documents from versioned content repositories and processes them using [Asciidoctor](https://asciidoctor.org).
 
 ## Copyright and License
 

package/lib/constants.js

@@ -1,6 +1,6 @@
 'use strict'
 
 module.exports = Object.freeze({
-  START_ALIAS_ID: Object.freeze({ component: '', version: '', module: '', family: 'alias', relative: 'index.adoc' }),
-  START_PAGE_ID: Object.freeze({ component: '', version: '', module: '', family: 'page', relative: 'index.adoc' }),
+  ROOT_INDEX_ALIAS_ID: { component: 'ROOT', version: '', module: 'ROOT', family: 'alias', relative: 'index.adoc' },
+  ROOT_INDEX_PAGE_ID: { component: 'ROOT', version: '', module: 'ROOT', family: 'page', relative: 'index.adoc' },
 })

package/lib/content-catalog.js

@@ -1,6 +1,7 @@
 'use strict'
 
 const File = require('./file')
+const invariably = { void: () => undefined }
 const logger = require('./logger')
 const { lookup: resolveMimeType } = require('./mime-types-with-asciidoc')
 const parseResourceId = require('./util/parse-resource-id')
@@ -8,7 +9,7 @@ const { posix: path } = require('path')
 const resolveResource = require('./util/resolve-resource')
 const versionCompare = require('./util/version-compare-desc')
 
-const { START_ALIAS_ID, START_PAGE_ID } = require('./constants')
+const { ROOT_INDEX_ALIAS_ID, ROOT_INDEX_PAGE_ID } = require('./constants')
 const SPACE_RX = / /g
 
 const $components = Symbol('components')
@@ -72,15 +73,17 @@ class ContentCatalog {
     const component = this[$components].get(name)
     if (component) {
       const componentVersions = component.versions
-      const insertIdx = componentVersions.findIndex(({ version: candidate }) => {
-        if (candidate === version) throw new Error(`Duplicate version detected for component ${name}: ${version}`)
-        return versionCompare(candidate, version) > 0
-      })
-      if (~insertIdx) {
-        componentVersions.splice(insertIdx, 0, componentVersion)
-      } else {
-        componentVersions.push(componentVersion)
+      if (componentVersions.find(({ version: candidate }) => candidate === version)) {
+        throw new Error(`Duplicate version detected for component ${name}: ${version}`)
       }
+      const insertIdx = prerelease
+        ? componentVersions.findIndex(({ version: candidateVersion, prerelease: candidatePrerelease }) =>
+          candidatePrerelease ? versionCompare(candidateVersion, version) > 0 : true
+        )
+        : componentVersions.findIndex(({ version: candidateVersion, prerelease: candidatePrerelease }) =>
+          candidatePrerelease ? false : versionCompare(candidateVersion, version) > 0
+        )
+      ~insertIdx ? componentVersions.splice(insertIdx, 0, componentVersion) : componentVersions.push(componentVersion)
       if ((component.latest = componentVersions.find((candidate) => !candidate.prerelease))) {
         if (componentVersions[0] !== component.latest) component.latestPrerelease = componentVersions[0]
       } else {
@@ -120,12 +123,16 @@ class ContentCatalog {
   addFile (file) {
     const src = file.src
     let family = src.family
+    let filesForFamily = this[$files].get(family)
+    if (!filesForFamily) this[$files].set(family, (filesForFamily = new Map()))
     const key = generateKey(src)
-    if (this[$files].has(key)) {
+    if (filesForFamily.has(key)) {
       if (family === 'alias') {
         throw new Error(`Duplicate alias: ${generateResourceSpec(src)}`)
       } else {
-        const details = [this.getById(src), file].map((it, idx) => `  ${idx + 1}: ${getFileLocation(it)}`).join('\n')
+        const details = [filesForFamily.get(key), file]
+          .map((it, idx) => `  ${idx + 1}: ${getFileLocation(it)}`)
+          .join('\n')
         if (family === 'nav') {
           throw new Error(`Duplicate nav in ${src.version}@${src.component}: ${file.path}\n${details}`)
         } else {
@@ -162,35 +169,42 @@ class ContentCatalog {
       ('/' + src.relative).indexOf('/_') < 0
     ) {
       publishable = true
-      versionSegment = computeVersionSegment.bind(this)(src.component, src.version)
+      versionSegment = computeVersionSegment.call(this, src.component, src.version)
       file.out = computeOut(src, family, versionSegment, this.htmlUrlExtensionStyle)
     }
     if (!file.pub && (publishable || family === 'nav')) {
-      if (versionSegment == null) versionSegment = computeVersionSegment.bind(this)(src.component, src.version)
+      if (versionSegment == null) versionSegment = computeVersionSegment.call(this, src.component, src.version)
       file.pub = computePub(src, file.out, family, versionSegment, this.htmlUrlExtensionStyle)
     }
-    this[$files].set(key, file)
+    filesForFamily.set(key, file)
     return file
   }
 
   findBy (criteria) {
     const criteriaEntries = Object.entries(criteria)
+    const family = criteria.family
+    if (criteriaEntries.length === 1 && family) {
+      const filesForFamily = this[$files].get(family)
+      return filesForFamily ? [...filesForFamily.values()] : []
+    }
     const accum = []
-    for (const candidate of this[$files].values()) {
-      const candidateSrc = candidate.src
-      if (criteriaEntries.every(([key, val]) => candidateSrc[key] === val)) accum.push(candidate)
+    for (const filesForFamily of this[$files].values()) {
+      for (const candidate of filesForFamily.values()) {
+        const candidateSrc = candidate.src
+        if (criteriaEntries.every(([key, val]) => candidateSrc[key] === val)) accum.push(candidate)
+      }
     }
     return accum
   }
 
-  getById ({ component, version, module: module_, family, relative }) {
-    return this[$files].get(generateKey({ component, version, module: module_, family, relative }))
+  getById (id) {
+    return (this[$files].get(id.family) || { get: invariably.void }).get(generateKey(id))
   }
 
   getByPath ({ component, version, path: path_ }) {
-    for (const candidate of this[$files].values()) {
-      if (candidate.path === path_ && candidate.src.component === component && candidate.src.version === version) {
-        return candidate
+    for (const filesForFamily of this[$files].values()) {
+      for (const it of filesForFamily.values()) {
+        if (it.path === path_ && it.src.component === component && it.src.version === version) return it
       }
     }
   }
@@ -214,26 +228,28 @@ class ContentCatalog {
   }
 
   getFiles () {
-    return [...this[$files].values()]
+    const accum = []
+    for (const filesForFamily of this[$files].values()) {
+      for (const file of filesForFamily.values()) accum.push(file)
+    }
+    return accum
   }
 
   getPages (filter) {
-    const accum = []
+    const candidates = this[$files].get('page')
+    if (!candidates) return []
     if (filter) {
-      for (const candidate of this[$files].values()) {
-        if (candidate.src.family === 'page' && filter(candidate)) accum.push(candidate)
-      }
+      const accum = []
+      for (const candidate of candidates.values()) filter(candidate) && accum.push(candidate)
+      return accum
     } else {
-      for (const candidate of this[$files].values()) {
-        if (candidate.src.family === 'page') accum.push(candidate)
-      }
+      return [...candidates.values()]
     }
-    return accum
   }
 
   // TODO add `follow` argument to control whether alias is followed
   getSiteStartPage () {
-    return this.getById(START_PAGE_ID) || (this.getById(START_ALIAS_ID) || {}).rel
+    return this.getById(ROOT_INDEX_PAGE_ID) || (this.getById(ROOT_INDEX_ALIAS_ID) || {}).rel
   }
 
   registerComponentVersionStartPage (name, componentVersion, startPageSpec = undefined) {
@@ -245,7 +261,7 @@ class ContentCatalog {
     }
     let startPage
     let startPageSrc
-    const indexPageId = { component: name, version, module: 'ROOT', family: 'page', relative: 'index.adoc' }
+    const indexPageId = Object.assign({}, ROOT_INDEX_PAGE_ID, { component: name, version })
     if (startPageSpec) {
       if (
         (startPage = this.resolvePage(startPageSpec, indexPageId)) &&
@@ -273,7 +289,7 @@ class ContentCatalog {
       componentVersion.url = startPage.pub.url
     } else {
       // QUESTION: should we warn if the default start page cannot be found?
-      const versionSegment = computeVersionSegment.bind(this)(name, version)
+      const versionSegment = computeVersionSegment.call(this, name, version)
       componentVersion.url = computePub(
         (startPageSrc = prepareSrc(Object.assign({}, indexPageId, { family: 'page' }))),
         computeOut(startPageSrc, startPageSrc.family, versionSegment, this.htmlUrlExtensionStyle),
@@ -286,7 +302,7 @@ class ContentCatalog {
     const symbolicVersionAlias = createSymbolicVersionAlias(
       name,
       version,
-      computeVersionSegment.bind(this)(name, version, 'alias'),
+      computeVersionSegment.call(this, name, version, 'alias'),
       this.latestVersionUrlSegmentStrategy
     )
     if (symbolicVersionAlias) this.addFile(symbolicVersionAlias)
@@ -296,7 +312,8 @@ class ContentCatalog {
     if (!startPageSpec) return
     const rel = this.resolvePage(startPageSpec)
     if (rel) {
-      return this.addFile({ src: Object.assign({}, START_ALIAS_ID), rel })
+      if (!(this.getSiteStartPage() || { synthetic: true }).synthetic) return
+      return this.addFile({ src: Object.assign({}, ROOT_INDEX_ALIAS_ID), rel, synthetic: true })
     } else if (rel === false) {
       logger.warn('Start page specified for site has invalid syntax: %s', startPageSpec)
     } else if (~startPageSpec.indexOf(':')) {
@@ -328,18 +345,17 @@ class ContentCatalog {
               `  existing page: ${getFileLocation(existingPage)}`
         )
       }
-      const existingAlias = this.getById(Object.assign({}, src, { family: 'alias' }))
-      if (existingAlias) {
-        throw new Error(
-          `Duplicate alias: ${generateResourceSpec(src)} (specified as: ${spec})\n` +
-            `  source: ${getFileLocation(target)}`
-        )
-      }
     } else if (src.version == null) {
       // QUESTION should we skip registering alias in this case?
       src.version = ''
     }
     src.family = 'alias'
+    const existingAlias = this.getById(src)
+    if (existingAlias) {
+      throw new Error(
+        `Duplicate alias: ${generateResourceSpec(src)} (specified as: ${spec})\n  source: ${getFileLocation(target)}`
+      )
+    }
     // NOTE the redirect producer will populate contents when the redirect facility is 'static'
     const alias = this.addFile({ src, rel: target })
     // NOTE record the first alias this target claims as the preferred one
@@ -352,9 +368,10 @@ class ContentCatalog {
    *
    * 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 file cannot be resolved,
-   * the function returns undefined. If the spec does not match the page ID syntax, this function
-   * throws an error.
+   * 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.
    *
    * @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.
@@ -394,8 +411,8 @@ class ContentCatalog {
  */
 ContentCatalog.prototype.getAll = ContentCatalog.prototype.getFiles
 
-function generateKey ({ component, version, module: module_, family, relative }) {
-  return `${version}@${component}:${module_}:${family}$${relative}`
+function generateKey ({ component, version, module: module_, relative }) {
+  return `${version}@${component}:${module_}:${relative}`
 }
 
 function generateResourceSpec ({ component, version, module: module_, family, relative }, shorthand = true) {
@@ -435,6 +452,7 @@ function prepareSrc (src) {
 
 function computeOut (src, family, version, htmlUrlExtensionStyle) {
   let { component, module: module_, basename, extname, relative, stem } = src
+  if (component === 'ROOT') component = ''
   if (module_ === 'ROOT') module_ = ''
   let indexifyPathSegment = ''
   let familyPathSegment = ''
@@ -465,8 +483,11 @@ function computePub (src, out, family, version, htmlUrlExtensionStyle) {
   const pub = {}
   let url
   if (family === 'nav') {
-    const urlSegments = version ? [src.component, version] : [src.component]
-    if (src.module && src.module !== 'ROOT') urlSegments.push(src.module)
+    const component = src.component || 'ROOT'
+    const urlSegments = component === 'ROOT' ? [] : [component]
+    if (version) urlSegments.push(version)
+    const module_ = src.module || 'ROOT'
+    if (module_ !== 'ROOT') urlSegments.push(module_)
     // an artificial URL used for resolving page references in navigation model
     url = '/' + urlSegments.join('/') + '/'
     pub.moduleRootPath = '.'

package/lib/util/parse-resource-id.js

@@ -56,9 +56,16 @@ function parseResourceId (spec, ctx = {}, defaultFamily = 'page', permittedFamil
   }
 
   if (~relative.indexOf('/')) {
-    relative = relative
-      .split('/')
-      .filter((it) => it && it !== '.' && it !== '..')
+    const relativeSegments = relative.split('/')
+    let from
+    if (relativeSegments[0] === '.' && (from = ctx.relative)) {
+      relativeSegments[0] = from.substr(0, (from.lastIndexOf('/') + 1 || 1) - 1)
+    }
+    relative = relativeSegments
+      .reduce((accum, segment) => {
+        segment === '..' ? accum.pop() : (segment || '.') !== '.' && accum.push(segment)
+        return accum
+      }, [])
       .join('/')
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antora/content-classifier",
-  "version": "3.0.0-alpha.7",
+  "version": "3.0.0-beta.2",
   "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)",
@@ -16,12 +16,12 @@
   },
   "main": "lib/index.js",
   "dependencies": {
-    "@antora/logger": "3.0.0-alpha.7",
+    "@antora/logger": "3.0.0-beta.2",
     "mime-types": "~2.1",
     "vinyl": "~2.2"
   },
   "engines": {
-    "node": ">=10.17.0"
+    "node": ">=12.21.0"
   },
   "files": [
     "lib/"
@@ -34,5 +34,5 @@
     "static site",
     "web publishing"
   ],
-  "gitHead": "fbd597b3680474f2083cda8a7facf1e2848c08e0"
+  "gitHead": "5cd3f9cc70622e465cb44daf1aa2035ed5a35f54"
 }