@antora/content-classifier 3.2.0-alpha.8 → 3.2.0-alpha.9

package/lib/content-catalog.js

@@ -11,7 +11,6 @@ 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')
@@ -61,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) {
@@ -131,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
   }
@@ -156,11 +160,9 @@ class ContentCatalog {
       }
       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)
@@ -183,18 +185,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)
     }
@@ -446,26 +455,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 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.
    *
-   * 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.
+   * 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.
    *
-   * @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.
+   * @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 ID spec refers, or undefined if the
-   * file cannot be resolved.
+   * @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)
   }
@@ -507,29 +538,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) {
@@ -589,7 +616,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
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antora/content-classifier",
-  "version": "3.2.0-alpha.8",
+  "version": "3.2.0-alpha.9",
   "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)",
@@ -31,8 +31,8 @@
     "#constants": "./lib/constants.js"
   },
   "dependencies": {
-    "@antora/asciidoc-loader": "3.2.0-alpha.8",
-    "@antora/logger": "3.2.0-alpha.8",
+    "@antora/asciidoc-loader": "3.2.0-alpha.9",
+    "@antora/logger": "3.2.0-alpha.9",
     "mime-types": "~2.1",
     "vinyl": "~3.0"
   },