@redpanda-data/docs-extensions-and-macros 5.13.4 → 5.14.0

package/bin/doc-tools.js

@@ -529,6 +529,103 @@ programCli
     }
   })
 
+/**
+ * @description Copy this package's docs-data/*.schema.json files into a
+ * content repo's own docs-data/ (the file that documents docs-data/x.json
+ * lives alongside x.json itself, so a writer can change both in one PR
+ * without waiting on a package release first). Run this after bumping
+ * @redpanda-data/docs-extensions-and-macros so the local copy picks up
+ * whatever changed upstream.
+ * @why Nothing keeps a content repo's schema copy in sync with this
+ * package's copy today, in either direction. A content repo's copy can
+ * legitimately be ahead of this package's (confirmed happening in
+ * practice: the docs repo's rpk-overrides.schema.json documents a real,
+ * working `asPartial` override field that this package's own copy is
+ * missing) — overwriting it in that case would delete real, correct
+ * documentation, not fix drift. This only overwrites when this package's
+ * copy is a strict superset of the destination; otherwise it reports which
+ * keys only the destination has and leaves the file alone (status
+ * 'diverged') unless --force is passed. --check never writes, for a CI
+ * gate.
+ * @example
+ * # Sync into ./docs-data (writes any missing or out-of-date schema)
+ * npx doc-tools sync-schemas
+ *
+ * # Report drift without writing -- exits 1 if anything is out of sync
+ * npx doc-tools sync-schemas --check
+ *
+ * # Sync into a non-default location
+ * npx doc-tools sync-schemas --dest path/to/docs-data
+ *
+ * # Overwrite even a destination that has diverged (rarely correct --
+ * # read the 'diverged' output first; it names what would be lost)
+ * npx doc-tools sync-schemas --force
+ * @requirements None.
+ */
+programCli
+  .command('sync-schemas')
+  .description("Sync this package's docs-data/*.schema.json into a content repo's docs-data/")
+  .option('--dest <path>', 'Destination docs-data directory', 'docs-data')
+  .option('--check', 'Report drift without writing; exit 1 if any schema is missing, out of date, or diverged')
+  .option('--force', 'Overwrite even a destination that has diverged (has content this package lacks)')
+  .action((options) => {
+    const { syncSchemas } = require('../cli-utils/sync-schemas')
+
+    try {
+      const { destDir, results, drift } = syncSchemas({
+        destDir: options.dest,
+        check: Boolean(options.check),
+        force: Boolean(options.force),
+      })
+
+      if (results.length === 0) {
+        console.log('No *.schema.json files found in this package to sync.')
+        process.exit(0)
+      }
+
+      console.log(`${options.check ? 'Checking' : 'Syncing'} against: ${destDir}`)
+      console.log('')
+      let hasUnresolvedDivergence = false
+      for (const { name, status, destOnlyPaths } of results) {
+        const label = {
+          unchanged: '✓ up to date',
+          created: '+ created',
+          updated: '↻ updated',
+          diverged: options.force ? '↻ updated (forced)' : '⚠ diverged, left alone',
+        }[status]
+        console.log(`  ${label}  ${name}`)
+        if (status === 'diverged' && !options.force) {
+          hasUnresolvedDivergence = true
+          for (const p of destOnlyPaths) console.log(`      only in the destination: ${p}`)
+        }
+      }
+      console.log('')
+
+      if (options.check) {
+        if (drift) {
+          const hint = hasUnresolvedDivergence
+            ? 'A diverged file needs a human decision (see paths above), not just a re-run.'
+            : 'Run `npx doc-tools sync-schemas` to fix.'
+          console.log(`✗ One or more schemas are out of date. ${hint}`)
+          process.exit(1)
+        }
+        console.log('✓ All schemas are in sync.')
+        process.exit(0)
+      }
+
+      if (hasUnresolvedDivergence) {
+        console.log('⚠ Synced what was safe to sync. One or more files diverged and were left alone -- see paths above. Re-run with --force only after confirming the destination-only content should be lost.')
+        process.exit(1)
+      }
+
+      console.log(drift ? '✓ Synced.' : '✓ Already in sync -- nothing to do.')
+      process.exit(0)
+    } catch (err) {
+      console.error(`Error: ${err.message}`)
+      process.exit(1)
+    }
+  })
+
 /**
  * @description Show MCP server version information including available tools
  * and optionally usage statistics from previous sessions.

package/cli-utils/sync-schemas.js

@@ -0,0 +1,144 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const { isDeepStrictEqual } = require('util')
+
+/**
+ * Schemas that document docs-data/*.json files (rpk-overrides.schema.json,
+ * property-overrides.schema.json, ...) are meant to live inside each content
+ * repo's own docs-data/, alongside the file they document — a writer can
+ * change both the override data and its schema in one PR, without waiting on
+ * a new @redpanda-data/docs-extensions-and-macros release first.
+ *
+ * That's exactly why this package's copy is not automatically authoritative:
+ * a content repo's copy can legitimately be AHEAD of this package's, when a
+ * writer documented a real override field here before anyone remembered to
+ * update the schema in this package. Confirmed happening in practice —
+ * docs-data/rpk-overrides.schema.json in this package is missing `asPartial`,
+ * a real field the generator (tools/rpk-docs/generate-rpk-docs.js) already
+ * reads, that the docs repo's copy documents correctly. A naive "package
+ * always wins" sync would have silently deleted that the first time someone
+ * ran it. So syncSchemas() only ever overwrites a destination file when this
+ * package's copy is a superset of it (every object key the destination has,
+ * the source also has) — otherwise it reports the destination-only keys and
+ * refuses, same as `check` mode, unless the caller passes `force: true`.
+ */
+
+const PACKAGE_SCHEMA_DIR = path.resolve(__dirname, '..', 'docs-data')
+
+/**
+ * List the *.schema.json files this package ships.
+ * @returns {Array<{name: string, sourcePath: string}>}
+ */
+function listPackageSchemas () {
+  if (!fs.existsSync(PACKAGE_SCHEMA_DIR)) return []
+  return fs.readdirSync(PACKAGE_SCHEMA_DIR)
+    .filter((name) => name.endsWith('.schema.json'))
+    .sort()
+    .map((name) => ({ name, sourcePath: path.join(PACKAGE_SCHEMA_DIR, name) }))
+}
+
+/**
+ * Find object keys present in `dest` but absent from the same path in
+ * `source` — the shape of "the destination knows something the source
+ * doesn't". Arrays are compared as opaque leaves (JSON Schema's own
+ * structure keeps named, distinguishable content in objects — `properties`,
+ * `$defs` — not in arrays like `required`/`enum`, so this is where a
+ * destination-only capability would actually show up).
+ *
+ * @param {*} source
+ * @param {*} dest
+ * @param {string} [pathPrefix]
+ * @returns {string[]} Dotted paths that exist in dest but not source.
+ */
+function findDestOnlyPaths (source, dest, pathPrefix = '') {
+  if (
+    dest === null || typeof dest !== 'object' || Array.isArray(dest) ||
+    source === null || typeof source !== 'object' || Array.isArray(source)
+  ) {
+    return []
+  }
+
+  const onlyInDest = []
+  for (const [key, destValue] of Object.entries(dest)) {
+    const keyPath = pathPrefix ? `${pathPrefix}.${key}` : key
+    if (!Object.hasOwn(source, key)) {
+      onlyInDest.push(keyPath)
+      continue
+    }
+    onlyInDest.push(...findDestOnlyPaths(source[key], destValue, keyPath))
+  }
+  return onlyInDest
+}
+
+/**
+ * Compare this package's schemas against the copies in a destination
+ * directory (a content repo's docs-data/), and optionally write updates.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.destDir] - Directory to sync into. Defaults to
+ *   docs-data/ under the current repo root.
+ * @param {boolean} [opts.check=false] - When true, never writes — only
+ *   reports what's missing or out of date. Use this in CI.
+ * @param {boolean} [opts.force=false] - Overwrite a destination file even
+ *   when it has content this package's copy lacks. Rarely correct — see the
+ *   module doc comment. Ignored when `check` is true.
+ * @returns {{
+ *   destDir: string,
+ *   results: Array<{
+ *     name: string,
+ *     status: ('created'|'updated'|'unchanged'|'diverged'),
+ *     sourcePath: string,
+ *     destPath: string,
+ *     destOnlyPaths?: string[]
+ *   }>,
+ *   drift: boolean
+ * }} drift is true when any schema is missing, differs, or has diverged.
+ *   status 'diverged' means the destination has content this package's copy
+ *   doesn't — nothing was written for that file unless `force` was set.
+ */
+function syncSchemas ({ destDir, check = false, force = false } = {}) {
+  const resolvedDest = path.resolve(destDir || 'docs-data')
+  const schemas = listPackageSchemas()
+
+  const results = schemas.map(({ name, sourcePath }) => {
+    const destPath = path.join(resolvedDest, name)
+    const sourceContent = fs.readFileSync(sourcePath, 'utf8')
+    const destExists = fs.existsSync(destPath)
+    const destContent = destExists ? fs.readFileSync(destPath, 'utf8') : null
+
+    let status
+    let destOnlyPaths
+    if (!destExists) {
+      status = 'created'
+    } else {
+      // Compare parsed content, not raw text — a destination reformatted by a
+      // content repo's own prettier/editorconfig (different indent, key
+      // order, trailing newline) with no real data change must not read as
+      // drift.
+      const sourceParsed = JSON.parse(sourceContent)
+      const destParsed = JSON.parse(destContent)
+      if (isDeepStrictEqual(sourceParsed, destParsed)) {
+        status = 'unchanged'
+      } else {
+        destOnlyPaths = findDestOnlyPaths(sourceParsed, destParsed)
+        status = destOnlyPaths.length > 0 ? 'diverged' : 'updated'
+      }
+    }
+
+    const shouldWrite = !check && (status === 'created' || status === 'updated' || (status === 'diverged' && force))
+    if (shouldWrite) {
+      fs.mkdirSync(resolvedDest, { recursive: true })
+      fs.writeFileSync(destPath, sourceContent)
+    }
+
+    return { name, status, sourcePath, destPath, ...(destOnlyPaths ? { destOnlyPaths } : {}) }
+  })
+
+  const drift = results.some((r) => r.status !== 'unchanged')
+
+  return { destDir: resolvedDest, results, drift }
+}
+
+module.exports = { listPackageSchemas, syncSchemas, findDestOnlyPaths, PACKAGE_SCHEMA_DIR }

package/docs-data/rpk-overrides.schema.json

@@ -137,6 +137,10 @@
           "type": "boolean",
           "description": "If true, exclude this command from documentation entirely. Use for internal or hidden commands that shouldn't be documented."
         },
+        "asPartial": {
+          "type": "boolean",
+          "description": "If true, write this command's .adoc file to the partials directory instead of the pages directory. Inherited by child commands — set on a parent command (e.g., 'rpk ai') to route the entire subtree to partials."
+        },
         "excludeFlags": {
           "type": "array",
           "description": "List of flag names to exclude from documentation (without dashes)",

package/macros/enterprise.js

@@ -31,6 +31,12 @@
  * registry is available (for example, outside an Antora build), the macros
  * fall back to unvalidated rendering with a single warning.
  *
+ * A registry entry's `since` field, when set, is checked against the page
+ * being converted, not the newest release: a mention or table row for a
+ * feature whose `since` postdates the page's own version renders unstyled,
+ * the same way an unreleased feature renders on released docs, because as
+ * of that page's version the feature had not shipped yet.
+ *
  * Document or site attributes:
  *
  *   enterprise-validate        'warn' (default) to log unknown feature names,
@@ -55,6 +61,7 @@
 
 const yaml = require('js-yaml')
 const chalk = require('chalk')
+const semver = require('semver')
 const { buildBadgeHtml, DEFAULT_TOOLTIPS } = require('./badge')
 
 const $enterpriseRegistry = Symbol('$enterpriseRegistry')
@@ -211,6 +218,81 @@ function reportUnreleasedFeature ({ feature, mode, filePath }) {
   console.warn(chalk.yellow(message))
 }
 
+/**
+ * Parse a version string into a semver for comparison, or undefined when it
+ * cannot be parsed. Lenient the same way `semver.coerce` is: Redpanda docs
+ * versions are "MAJOR.MINOR", not full semver, so an exact-match parse would
+ * reject every one of them.
+ */
+function coerceVersion (raw) {
+  if (raw === undefined || raw === null) return undefined
+  return semver.coerce(String(raw)) || undefined
+}
+
+/**
+ * Whether a registry entry's `since` version has shipped as of the page
+ * being converted.
+ *
+ * enterprise-features.yml lives in the non-versioned 'shared' component, so
+ * every version branch reads the exact same entry -- unlike property data,
+ * which has one JSON file per release and is checked against the page's
+ * own version (see PROPERTY_AND_ENTERPRISE_REFERENCES.adoc). Without this
+ * check, a feature that ships in 26.3 renders as fully available -- linked,
+ * badge-free, no warning -- on a 24.1 page that predates it by two years.
+ *
+ * Returns true (shipped) when `since` is absent, unparsable, or the page's
+ * own version cannot be determined. That default favors data quality over
+ * release-readiness: unlike an unrecognized `status`, which fails closed
+ * because it is the one mistake that could publish an unreleased feature,
+ * a `since` typo or a build with no page-version context has no such
+ * asymmetry to protect against, so it defaults to not gating rather than
+ * hiding a shipped feature over unrelated bad data. An unparsable `since`
+ * is still reported, the same way an unrecognized `status` is: the failure
+ * mode differs (not gated, instead of gated), but a silent typo is exactly
+ * as easy to miss either way.
+ *
+ * @param {object} entry - Registry entry.
+ * @param {object} [config] - Extension config, used to read the page's own
+ *   version.
+ * @param {object} [report] - {mode, filePath, contentCatalog} to report an
+ *   unparsable since value. Omit to check silently.
+ */
+function isFeatureShippedOnPage (entry, config, report) {
+  const since = entry && entry.since
+  if (since === undefined || since === null || String(since).trim() === '') return true
+  const sinceVersion = coerceVersion(since)
+  if (!sinceVersion) {
+    if (report && report.mode !== 'off') {
+      const where = report.filePath ? ` in ${report.filePath}` : ''
+      const message =
+        `enterprise:${entry.name}[]${where}: registry has since: '${since}', which is not a parsable version, so the since-gating check is skipped and the feature renders as already shipped. ` +
+        'Fix the since value in enterprise-features.yml (e.g. "26.3"), or remove the key if the feature has always been available.'
+      if (report.contentCatalog) warnOnce(report.contentCatalog, `since:${entry.name}`, message)
+      else console.warn(chalk.yellow(message))
+    }
+    return true
+  }
+  const src = config && config.file && config.file.src
+  const pageVersion = src && coerceVersion(src.version)
+  if (!pageVersion) return true
+  return semver.gte(pageVersion, sinceVersion)
+}
+
+/**
+ * Report an inline mention of a feature before its `since` version, on a
+ * page whose own version predates it.
+ */
+function reportFeatureNotYetShipped ({ feature, since, pageVersion, mode, filePath }) {
+  if (mode === 'off') return
+  const where = filePath ? ` in ${filePath}` : ''
+  const message =
+    `enterprise:${feature}[]${where}: '${feature}' is marked since: ${since} in the enterprise features registry, but this page is version ${pageVersion}, which predates it. ` +
+    'The mention renders as plain text with no enterprise styling, tooltip, or link. ' +
+    'Move the mention to a page whose version is at or after the since version, or remove since if the feature covers this version too.'
+  if (mode === 'error') throw new Error(message)
+  console.warn(chalk.yellow(message))
+}
+
 /**
  * The badge for a registry entry, wrapped for use in generated AsciiDoc.
  *
@@ -436,6 +518,8 @@ function buildEnterpriseContent ({ feature, text, xref, url, tooltip, licensingP
  * @param {object} [opts]
  * @param {string} [opts.title] - Table title override.
  * @param {string} [opts.heading] - Third column heading override.
+ * @param {object} [opts.config] - Extension config, used to read the page's
+ *   own version for since-gating (see isFeatureShippedOnPage).
  * @returns {string}
  */
 function buildFeatureTable (features, scope, opts = {}) {
@@ -456,7 +540,13 @@ function buildFeatureTable (features, scope, opts = {}) {
     // did not fail there either.
     .filter((feature) => {
       const status = entryStatus(feature, report)
-      return includeUnreleased || status !== STATUS_UNRELEASED
+      if (!includeUnreleased && status === STATUS_UNRELEASED) return false
+      // since only describes a shipped feature's first version, so it does
+      // not apply to one that has not released at all yet. Silent, like the
+      // unreleased filter above: an older version's table naturally does not
+      // list a feature that did not exist yet on that version, which is not
+      // a writer mistake worth warning about.
+      return status === STATUS_UNRELEASED || isFeatureShippedOnPage(feature, opts.config, report)
     })
     .sort((a, b) => a.name.localeCompare(b.name, 'en', { sensitivity: 'base' }))
   const title = opts.title || TABLE_TITLES[scope]
@@ -517,6 +607,18 @@ function enterpriseInlineMacro (config) {
         reportUnreleasedFeature({ feature, mode, filePath })
         return self.createInline(parent, 'quoted', attributes.text || feature)
       }
+      if (!isFeatureShippedOnPage(entry, config, { mode, filePath, contentCatalog: config && config.contentCatalog })) {
+        // isFeatureShippedOnPage only returns false when entry.since parsed,
+        // so entry is defined here.
+        reportFeatureNotYetShipped({
+          feature,
+          since: entry.since,
+          pageVersion: config && config.file && config.file.src && config.file.src.version,
+          mode,
+          filePath,
+        })
+        return self.createInline(parent, 'quoted', attributes.text || feature)
+      }
       let content = buildEnterpriseContent({
         feature,
         text: attributes.text,
@@ -568,6 +670,7 @@ function enterpriseFeaturesBlockMacro (config) {
         // Prerelease docs describe the upcoming release, so they list features
         // that are still only in a release candidate.
         includeUnreleased: isPrereleasePage(config, parent.getDocument()),
+        config,
       })
       // 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.
@@ -598,3 +701,4 @@ module.exports.buildFeatureTable = buildFeatureTable
 module.exports.parseRegistry = parseRegistry
 module.exports.resolveEntryXref = resolveEntryXref
 module.exports.resolveTooltipAttribute = resolveTooltipAttribute
+module.exports.isFeatureShippedOnPage = isFeatureShippedOnPage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "5.13.4",
+  "version": "5.14.0",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",

package/tools/enterprise-features/verify.js

@@ -12,6 +12,7 @@
  */
 
 const yaml = require('js-yaml')
+const semver = require('semver')
 
 const VALID_SCOPES = ['redpanda', 'console', 'connect', 'operator', 'cloud']
 const SOURCE_KINDS = ['core-enum', 'core-property', 'connect-plugin', 'manual']
@@ -58,6 +59,14 @@ function lintRegistry (source) {
     } else if (!feature.source.value || !String(feature.source.value).trim()) {
       findings.push(finding('error', 'registry-lint', `'${name}' has an empty source value; manual entries need a justification.`))
     }
+    if (feature.since !== undefined && feature.since !== null && String(feature.since).trim() !== '') {
+      const since = String(feature.since).trim()
+      // Lenient the same way the enterprise macro's own coerceVersion is:
+      // docs versions are "MAJOR.MINOR", not full semver.
+      if (!semver.coerce(since)) {
+        findings.push(finding('error', 'registry-lint', `'${name}' has since '${since}', which is not a parsable version.`))
+      }
+    }
   }
   return { features: data.features, findings }
 }