@redpanda-data/docs-extensions-and-macros 5.11.1 → 5.12.1

package/macros/enterprise.js

@@ -55,16 +55,127 @@
 
 const yaml = require('js-yaml')
 const chalk = require('chalk')
-const { buildBadgeHtml } = require('./badge')
+const { buildBadgeHtml, DEFAULT_TOOLTIPS } = require('./badge')
 
 const $enterpriseRegistry = Symbol('$enterpriseRegistry')
+const $enterpriseRegistryUnreadable = Symbol('$enterpriseRegistryUnreadable')
+const $warned = Symbol('$warned')
+
+/**
+ * Report a message once per build. Keyed off the content catalog, which Antora
+ * rebuilds per build, so watch mode keeps reporting instead of going quiet.
+ */
+function warnOnce (contentCatalog, key, message) {
+  const seen = contentCatalog[$warned] || (contentCatalog[$warned] = new Set())
+  if (seen.has(key)) return false
+  seen.add(key)
+  console.warn(chalk.yellow(message))
+  return true
+}
 
 const DEFAULT_LICENSING_PAGE = 'get-started:licensing/overview.adoc'
 const DEFAULT_ROLE = 'enterprise-feature'
 const BETA_LABEL = 'beta'
+const UNRELEASED_LABEL = 'unreleased'
+// The badge macro supplies the default hover text for these labels, so the same
+// wording appears whether a badge comes from the registry or from a
+// badge::[label=beta] call in a page.
+const UNRELEASED_TOOLTIP = DEFAULT_TOOLTIPS.unreleased
+
+// Release status of a feature, which decides where it may be referenced.
+//
+//   ga          Shipped. Referenced anywhere. The default.
+//   beta        Publicly available as a beta. Referenced anywhere, badged, so
+//               readers know the feature is not yet stable.
+//   unreleased  In a release candidate only, not yet public. Referenced ONLY
+//               from prerelease docs (a beta branch). A mention on a released
+//               page describes something readers cannot get, so it is reported
+//               and rendered as plain text.
+const STATUS_GA = 'ga'
+const STATUS_BETA = 'beta'
+const STATUS_UNRELEASED = 'unreleased'
+const VALID_STATUSES = [STATUS_GA, STATUS_BETA, STATUS_UNRELEASED]
+
+/**
+ * The release status of a registry entry.
+ *
+ * `beta: true` predates the status field and still means beta, so old entries
+ * keep working. An explicit status wins. An unrecognized status is reported AND
+ * treated as unreleased: a typo must not be the thing that publishes an
+ * unreleased feature. The two failure directions are not symmetric -- gating a
+ * shipped feature shows a writer a warning and an unstyled mention they will
+ * notice, while publishing an unreleased one promises readers a feature they
+ * cannot get, and nothing on the page looks wrong.
+ *
+ * @param {object} entry - Registry entry.
+ * @param {object} [report] - {mode, filePath} to report an invalid status.
+ * @returns {string} One of VALID_STATUSES.
+ */
+function entryStatus (entry, report) {
+  if (!entry) return STATUS_GA
+  // Any present key goes through validation, including a blank value. An absent
+  // key means no status was intended, so GA is the right default; `status:` with
+  // nothing after it means the writer meant to say something and did not, which
+  // is the same mistake as a typo and must fail the same way. Treating blank as
+  // absent reopened the hole this function exists to close: a forgotten value
+  // published an unreleased feature with no warning at all.
+  if (entry.status !== undefined) {
+    const raw = entry.status === null ? '' : String(entry.status).trim()
+    const status = raw.toLowerCase()
+    if (VALID_STATUSES.includes(status)) return status
+    if (report && report.mode !== 'off') {
+      const where = report.filePath ? ` in ${report.filePath}` : ''
+      const what = raw === '' ? 'an empty status' : `status '${entry.status}'`
+      const message =
+        `enterprise:${entry.name}[]${where}: registry has ${what}, which is not one of ${VALID_STATUSES.join(', ')}, so the feature is treated as unreleased and is left unpublished on released pages. ` +
+        'Fix the status in enterprise-features.yml, or remove the key entirely if the feature has shipped.'
+      // Honour error mode like every other registry diagnostic. A typo here is
+      // exactly what publishes an unreleased feature, so the strictest setting
+      // has to stop it.
+      if (report.mode === 'error') throw new Error(message)
+      // One registry typo needs one fix, so report it once per build rather
+      // than once per mention of the feature.
+      if (report.contentCatalog) warnOnce(report.contentCatalog, `status:${entry.name}`, message)
+      else console.warn(chalk.yellow(message))
+    }
+    return STATUS_UNRELEASED
+  }
+  return entry.beta === true ? STATUS_BETA : STATUS_GA
+}
+
+/**
+ * Whether the page being converted belongs to a prerelease component version,
+ * which is where an unreleased feature may be referenced.
+ *
+ * Read from the component version's own prerelease flag (antora.yml) rather
+ * than inferred, with a document attribute as an escape hatch for playbooks
+ * that surface it themselves.
+ */
+function isPrereleasePage (config, document) {
+  const attribute = document && document.getAttribute('page-component-version-is-prerelease')
+  if (attribute !== undefined) {
+    const value = String(attribute).trim().toLowerCase()
+    if (value === 'true' || value === '') return true
+    if (value === 'false') return false
+    // Anything else is a typo. Falling through to the catalog is safer than
+    // guessing, and silently treating it as "released" produced a warning that
+    // told the writer their prerelease page belonged to a released version.
+    console.warn(chalk.yellow(
+      `enterprise macro: page-component-version-is-prerelease is '${attribute}', which is neither true nor false, so it is ignored and the component version's own prerelease flag is used instead.`
+    ))
+  }
+  const contentCatalog = config && config.contentCatalog
+  const src = config && config.file && config.file.src
+  if (!contentCatalog || !src || typeof contentCatalog.getComponent !== 'function') return false
+  const component = contentCatalog.getComponent(src.component)
+  if (!component) return false
+  const versions = Array.isArray(component.versions) ? component.versions : []
+  const componentVersion = versions.find((entry) => entry.version === src.version)
+  return Boolean(componentVersion && componentVersion.prerelease)
+}
 
 /**
- * Render the beta badge for a registry entry marked `beta: true`.
+ * Render the release-status badge for a registry entry.
  *
  * The badge HTML is built directly rather than emitted as `badge:[...]`
  * AsciiDoc, so it renders whether or not the consuming playbook registers the
@@ -73,14 +184,31 @@ const BETA_LABEL = 'beta'
  * `badge::[label=beta]` in any build without that macro registered.
  *
  * @param {object} entry - Registry entry.
- * @returns {string} Badge HTML, or an empty string when the entry is not beta.
+ * @returns {string} Badge HTML, or an empty string for a shipped feature.
  */
 function buildBetaBadge (entry) {
-  if (!entry || entry.beta !== true) return ''
-  return buildBadgeHtml({
-    label: BETA_LABEL,
-    tooltip: entry['beta-tooltip'] || undefined,
-  })
+  const status = entryStatus(entry)
+  if (status === STATUS_BETA) {
+    return buildBadgeHtml({ label: BETA_LABEL, tooltip: entry['beta-tooltip'] || undefined })
+  }
+  if (status === STATUS_UNRELEASED) {
+    return buildBadgeHtml({ label: UNRELEASED_LABEL, tooltip: entry['status-tooltip'] || UNRELEASED_TOOLTIP })
+  }
+  return ''
+}
+
+/**
+ * Report an unreleased feature referenced from released documentation.
+ */
+function reportUnreleasedFeature ({ feature, mode, filePath }) {
+  if (mode === 'off') return
+  const where = filePath ? ` in ${filePath}` : ''
+  const message =
+    `enterprise:${feature}[]${where}: '${feature}' is marked status: unreleased in the enterprise features registry, so it is only documented for an upcoming release. ` +
+    'This page belongs to a released version, so the mention renders as plain text with no enterprise styling, tooltip, or link. ' +
+    'Move the mention to the prerelease (beta) branch, or change the status once the feature ships.'
+  if (mode === 'error') throw new Error(message)
+  console.warn(chalk.yellow(message))
 }
 
 /**
@@ -125,7 +253,14 @@ let warnedNoRegistry = false
  * @returns {{features: object[], lookup: Map<string, object>}}
  */
 function parseRegistry (source, origin = REGISTRY_FILENAME) {
-  const data = yaml.load(source)
+  let data
+  try {
+    data = yaml.load(source)
+  } catch (error) {
+    // Every other throw below names the file, so this one does too: the caller
+    // then reports whatever it catches verbatim, and the path appears once.
+    throw new Error(`Enterprise features registry ${origin} is not valid YAML (${error.message}).`)
+  }
   if (!data || !Array.isArray(data.features)) {
     throw new Error(`Enterprise features registry ${origin} has no 'features' list.`)
   }
@@ -164,17 +299,44 @@ function loadRegistry (config) {
   const partials = contentCatalog.findBy({ component: 'shared', module: 'ROOT', family: 'partial' }) || []
   const registryFile = partials.find((file) => file.path && file.path.endsWith(REGISTRY_FILENAME))
   if (registryFile) {
-    registry = parseRegistry(registryFile.contents.toString(), registryFile.path)
+    try {
+      registry = parseRegistry(registryFile.contents.toString(), registryFile.path)
+    } catch (error) {
+      // A malformed registry must not take the whole build down. Unvalidated
+      // enterprise mentions are the same graceful degradation as no registry at
+      // all, and this matches how prop.js treats a corrupt properties JSON.
+      // Caching the failure also stops the error being re-raised per macro call
+      // and attributed to whichever page happened to convert first.
+      registry = null
+      // Remember that the file was found and unreadable, so the caller does not
+      // then also report it missing. Saying "not found" about a file we just
+      // read and failed to parse sends the writer looking for the wrong problem.
+      contentCatalog[$enterpriseRegistryUnreadable] = true
+      // Report the error as thrown. It already names the file and says exactly
+      // what is wrong -- invalid YAML, a missing features list, an entry with no
+      // name, an unknown scope, or a duplicate name or alias. Wrapping it in
+      // "could not be read" was inaccurate for all but the first (the file read
+      // fine; its contents are invalid) and printed the path twice.
+      warnOnce(contentCatalog, 'badregistry',
+        `${error.message} No enterprise: target is validated, no feature is gated by release status, and the licensing tables are empty until this is fixed.`)
+    }
   }
   // Cache null too, so a missing registry is only searched for once per build.
   contentCatalog[$enterpriseRegistry] = registry
   return registry || undefined
 }
 
-function warnNoRegistry () {
+function warnNoRegistry (contentCatalog) {
+  // Already reported as unreadable: one problem, one diagnostic.
+  if (contentCatalog && contentCatalog[$enterpriseRegistryUnreadable]) return
+  const message = "Enterprise features registry (enterprise-features.yml in the 'shared' component) not found; enterprise: targets are not validated."
+  // Deduplicate per build, not per process: Antora's watch mode reuses one
+  // process across builds, and a module-level guard reported this only on a
+  // session's first build -- exactly when a writer is iterating.
+  if (contentCatalog) return warnOnce(contentCatalog, 'noregistry', message)
   if (warnedNoRegistry) return
   warnedNoRegistry = true
-  console.warn(chalk.yellow(`Enterprise features registry (${REGISTRY_FILENAME} in the shared component) not found; enterprise: targets are not validated.`))
+  console.warn(chalk.yellow(message))
 }
 
 /**
@@ -247,7 +409,16 @@ function resolveTooltipAttribute (raw) {
 function buildEnterpriseContent ({ feature, text, xref, url, tooltip, licensingPage, role, tooltipAttr, links }) {
   const display = text || feature
   const tooltipText = tooltip || `${feature} requires an Enterprise Edition license.`
-  const escapedTooltip = tooltipText.replace(/"/g, '&quot;')
+  // All four, matching badge.js. Escaping only the quote kept the attribute
+  // intact but let < and > through from a registry tooltip field, which any
+  // consumer that re-parses the page then reads as markup -- the docs UI
+  // promotes this attribute into a tooltip, the Markdown converter and the
+  // search indexer both re-read it.
+  const escapedTooltip = tooltipText
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
   const tooltipHtml = tooltipAttr ? ` ${tooltipAttr}="${escapedTooltip}"` : ''
   let inner = display
   if (links) {
@@ -268,8 +439,25 @@ function buildEnterpriseContent ({ feature, text, xref, url, tooltip, licensingP
  * @returns {string}
  */
 function buildFeatureTable (features, scope, opts = {}) {
+  // On released docs an unreleased feature is omitted entirely: the licensing
+  // table is a list of what a licence covers today, and listing something
+  // unavailable makes it wrong. Prerelease docs list it with its badge.
+  const includeUnreleased = opts.includeUnreleased === true
+  // Report a bad status from here too. Without a reporter a typo'd status was
+  // silently downgraded to released, so an unreleased feature that no page
+  // happens to reference inline was published in the table with no diagnostic.
+  const report = opts.report
   const rows = features
     .filter((feature) => feature.scope === scope)
+    // Evaluate the status first: `includeUnreleased || entryStatus(...)` skipped
+    // the call entirely on a prerelease page, so a typo'd status went unreported
+    // on the beta branch -- the one branch where unreleased features are
+    // actually authored and the table renders them -- and enterprise-validate=error
+    // did not fail there either.
+    .filter((feature) => {
+      const status = entryStatus(feature, report)
+      return includeUnreleased || status !== STATUS_UNRELEASED
+    })
     .sort((a, b) => a.name.localeCompare(b.name, 'en', { sensitivity: 'base' }))
   const title = opts.title || TABLE_TITLES[scope]
   const heading = opts.heading || THIRD_COLUMN_HEADINGS[scope] || THIRD_COLUMN_HEADINGS.default
@@ -302,7 +490,7 @@ function enterpriseInlineMacro (config) {
       let registry
       if (config && config.contentCatalog) {
         registry = loadRegistry(config)
-        if (!registry) warnNoRegistry()
+        if (!registry) warnNoRegistry(config && config.contentCatalog)
       }
       let feature = target
       let entry
@@ -319,6 +507,16 @@ function enterpriseInlineMacro (config) {
           })
         }
       }
+      const mode = document.getAttribute('enterprise-validate', 'warn')
+      const filePath = config && config.file && config.file.src && config.file.src.path
+      const status = entryStatus(entry, { mode, filePath, contentCatalog: config && config.contentCatalog })
+      if (status === STATUS_UNRELEASED && !isPrereleasePage(config, document)) {
+        // Documented for an upcoming release, referenced from released docs.
+        // Styling it as an available enterprise feature would promise readers
+        // something they cannot get, so render the name and say so.
+        reportUnreleasedFeature({ feature, mode, filePath })
+        return self.createInline(parent, 'quoted', attributes.text || feature)
+      }
       let content = buildEnterpriseContent({
         feature,
         text: attributes.text,
@@ -330,12 +528,13 @@ function enterpriseInlineMacro (config) {
         tooltipAttr: resolveTooltipAttribute(document.getAttribute('enterprise-tooltip')),
         links: document.getAttribute('enterprise-links', 'true') === 'true',
       })
-      // A feature marked beta in the registry is beta wherever it is
-      // referenced, so prose gets the same badge as the generated tables.
-      // Set enterprise-beta-badge to false to suppress it in prose only.
-      if (document.getAttribute('enterprise-beta-badge', 'true') === 'true') {
-        const betaBadge = buildBetaBadge(entry)
-        if (betaBadge) content += ` ${betaBadge}`
+      // A feature's status holds wherever it is referenced, so prose gets the
+      // same badge as the generated tables. enterprise-beta-badge=false
+      // suppresses the beta badge in prose; the unreleased badge is not
+      // suppressible, because "not in a release yet" is not decoration.
+      if (status === STATUS_UNRELEASED || document.getAttribute('enterprise-beta-badge', 'true') === 'true') {
+        const badge = buildBetaBadge(entry)
+        if (badge) content += ` ${badge}`
       }
       // The xref inside the span is resolved by the 'macros' substitution,
       // the same mechanism the config_ref macro relies on.
@@ -355,10 +554,21 @@ function enterpriseFeaturesBlockMacro (config) {
       }
       const registry = config && config.contentCatalog ? loadRegistry(config) : undefined
       if (!registry) {
-        warnNoRegistry()
+        warnNoRegistry(config && config.contentCatalog)
         return self.parseContent(parent, `WARNING: The enterprise features registry is unavailable, so the ${scope} feature table cannot be rendered.`)
       }
-      const table = buildFeatureTable(registry.features, scope, { title: attributes.title, heading: attributes.heading })
+      const table = buildFeatureTable(registry.features, scope, {
+        title: attributes.title,
+        heading: attributes.heading,
+        report: {
+          mode: parent.getDocument().getAttribute('enterprise-validate', 'warn'),
+          filePath: config && config.file && config.file.src && config.file.src.path,
+          contentCatalog: config && config.contentCatalog,
+        },
+        // Prerelease docs describe the upcoming release, so they list features
+        // that are still only in a release candidate.
+        includeUnreleased: isPrereleasePage(config, parent.getDocument()),
+      })
       // A block anchor before the macro call ([[my-id]]) is consumed into the
       // macro's id attribute. Re-emit it so crossrefs to the table keep working.
       const source = attributes.id ? `[[${attributes.id}]]\n${table}` : table