@redpanda-data/docs-extensions-and-macros 5.8.0 → 5.10.0

package/macros/prop.js

@@ -0,0 +1,491 @@
+'use strict'
+
+/* Inline macro for referencing Redpanda configuration properties in prose.
+ *
+ * Example use in a page:
+ *
+ *   prop:cloud_storage_enabled[]
+ *   prop:iceberg_enabled[link=true]
+ *   prop:retention_ms[link=true,page=properties/topic-properties]
+ *   prop:write_caching_default[text=write caching]
+ *
+ * The property renders as a marked <code> element that the docs UI decorates
+ * with a hover-documentation tooltip. Marking is opt-in: only properties
+ * referenced through this macro get tooltips, so ambiguous words such as
+ * `admin` or `rack` in unrelated contexts (Helm values, feature settings)
+ * are never decorated by mistake.
+ *
+ * The macro validates its target against the published property reference
+ * (the newest redpanda-properties-<tag>.json attachment in the reference
+ * module, the same data the tooltips fetch at runtime). Unknown names are
+ * reported according to the property-validate attribute. When no property
+ * JSON is available in the build, the macro renders unvalidated with a
+ * single warning.
+ *
+ * With link=true, the property also links to its reference page. The page
+ * is discovered dynamically: the macro indexes which reference-module page
+ * in the current component documents each property, by scanning property
+ * headings in the partials each page includes (respecting include tag
+ * filters such as tags=redpanda-cloud). Links therefore stay correct per
+ * component (streaming, cloud, agentic-data-plane, connect) and keep
+ * working if properties are split across different pages in the future.
+ * When discovery finds nothing, the page falls back deterministically to
+ * the property's config_scope (cluster, broker, or topic). The xref is
+ * component-relative (no component ID). Use page= to override the target
+ * entirely. This supersedes the config_ref macro's linking for most uses,
+ * without requiring writers to know the page.
+ *
+ * With helm-path=auto, pages rendered with the env-kubernetes attribute
+ * display the property as its Helm values path (storage.tiered.config.*
+ * for tiered storage properties, config.node.* for broker properties, and
+ * config.cluster.* for other cluster properties), so single-sourced
+ * content reads correctly for both Linux and Kubernetes audiences. This
+ * replaces the config_ref macro's hardcoded storage.tiered.config prefix,
+ * which mislabeled non-tiered properties.
+ *
+ * Document or site attributes:
+ *
+ *   property-validate     'warn' (default) to log unknown property names,
+ *                         'error' to fail the build, 'off' to disable
+ *                         validation.
+ *   property-ref-role     CSS class applied to the code element
+ *                         (default: property-ref).
+ *
+ * Example use in a playbook:
+ *
+ *   asciidoc:
+ *     extensions:
+ *     - '@redpanda-data/docs-extensions-and-macros/macros/prop'
+ */
+
+const chalk = require('chalk')
+
+const $propertyRegistry = Symbol('$propertyRegistry')
+
+const DEFAULT_ROLE = 'property-ref'
+const PROPERTIES_JSON_RX = /^redpanda-properties-(v\d+\.\d+\.\d+(?:-[\w.]+)?)\.json$/
+
+// Deterministic fallback only. The primary mechanism is dynamic discovery:
+// the macro indexes which reference-module page actually documents each
+// property (by scanning property headings in the partials each page
+// includes, respecting include tag filters), so links keep working if
+// properties are ever split across different pages.
+const SCOPE_PAGES = {
+  cluster: 'properties/cluster-properties',
+  broker: 'properties/broker-properties',
+  topic: 'properties/topic-properties',
+}
+
+const $propertyPageIndex = Symbol('$propertyPageIndex')
+const HEADING_RX = /^=+\s+(\S+)\s*$/
+const TAG_MARKER_RX = /^\/\/\s*(tag|end)::([\w-]+)\[\]\s*$/
+const INCLUDE_RX = /^include::([^[]+)\[([^\]]*)\]/
+
+/**
+ * Extract property-style headings from AsciiDoc source together with the
+ * include tags that enclose them.
+ *
+ * @param {string} source
+ * @returns {{name: string, tags: string[]}[]}
+ */
+function extractHeadingsWithTags (source) {
+  const headings = []
+  const open = []
+  for (const line of source.split('\n')) {
+    const marker = line.match(TAG_MARKER_RX)
+    if (marker) {
+      if (marker[1] === 'tag') open.push(marker[2])
+      else {
+        const at = open.lastIndexOf(marker[2])
+        if (at !== -1) open.splice(at, 1)
+      }
+      continue
+    }
+    const heading = line.match(HEADING_RX)
+    if (heading) headings.push({ name: heading[1], tags: [...open] })
+  }
+  return headings
+}
+
+/**
+ * Evaluate an include tags= expression against the tags enclosing a heading.
+ * Supports the forms used by the property pages: a semicolon-separated list
+ * of tag names, each optionally negated with '!'.
+ *
+ * @param {string[]} headingTags
+ * @param {string|undefined} expression
+ * @returns {boolean} Whether the heading survives the include.
+ */
+function evaluateTagExpression (headingTags, expression) {
+  if (!expression) return true
+  const items = expression.split(/[;,]/).map((item) => item.trim()).filter(Boolean)
+  const positives = items.filter((item) => !item.startsWith('!'))
+  const negatives = items.filter((item) => item.startsWith('!')).map((item) => item.slice(1))
+  if (negatives.some((tag) => headingTags.includes(tag))) return false
+  if (positives.length > 0) return positives.some((tag) => headingTags.includes(tag))
+  return true
+}
+
+/**
+ * Resolve an include target such as
+ * 'streaming:reference:partial$properties/cluster-properties.adoc' into its
+ * component, module, and relative path. Component and module default to the
+ * including page's.
+ */
+function parsePartialTarget (target, pageSrc) {
+  const at = target.indexOf('partial$')
+  if (at === -1) return undefined
+  const prefix = target.slice(0, at).replace(/:$/, '')
+  const relative = target.slice(at + 'partial$'.length)
+  const parts = prefix ? prefix.split(':') : []
+  if (parts.length === 2) return { component: parts[0], module: parts[1], relative }
+  if (parts.length === 1) return { component: pageSrc.component, module: parts[0], relative }
+  return { component: pageSrc.component, module: pageSrc.module, relative }
+}
+
+/**
+ * Build (and cache) the property -> page index for one component by scanning
+ * the reference-module pages and the partials they include.
+ *
+ * @param {object} contentCatalog
+ * @param {string} component
+ * @param {object} properties - Known property names from the published JSON.
+ * @returns {Map<string, string>} property name -> page path without .adoc
+ */
+function buildPageIndex (contentCatalog, component, properties, version) {
+  const cache = contentCatalog[$propertyPageIndex] || (contentCatalog[$propertyPageIndex] = {})
+  const cacheKey = `${component}@${version || ''}`
+  if (cache[cacheKey]) return cache[cacheKey]
+  const index = new Map()
+  const partialHeadings = new Map()
+  const headingsFor = (file) => {
+    if (!partialHeadings.has(file)) partialHeadings.set(file, extractHeadingsWithTags(file.contents.toString()))
+    return partialHeadings.get(file)
+  }
+  // Restrict the index to the page's own component version, so a page on an
+  // older docs branch never links into (or claims pages from) another version.
+  const query = { component, module: 'reference', family: 'page' }
+  if (version !== undefined && version !== '') query.version = version
+  const pages = contentCatalog.findBy(query) || []
+  // Antora replaces each page's contents with converted HTML as it goes, so
+  // an index built lazily mid-conversion can miss includes on pages that
+  // already converted. The property-page-index extension warms this cache
+  // before conversion starts; warn when that safety net is absent.
+  if (pages.some((candidate) => candidate.contents.toString('utf8', 0, 200).trimStart().startsWith('<'))) {
+    console.warn(chalk.yellow(`prop macro: building the property page index for ${component}@${version || 'any'} after conversion started; some pages are already HTML and their properties may not be indexed. Register '@redpanda-data/docs-extensions-and-macros/extensions/property-page-index' under antora.extensions to build the index up front.`))
+  }
+  for (const page of pages) {
+    const source = page.contents.toString()
+    const pagePath = page.src.relative.replace(/\.adoc$/, '')
+    const pageUrl = (page.pub && page.pub.url) || undefined
+    for (const line of source.split('\n')) {
+      const heading = line.match(HEADING_RX)
+      if (heading && Object.prototype.hasOwnProperty.call(properties, heading[1])) {
+        index.set(heading[1], { page: pagePath, url: pageUrl })
+        continue
+      }
+      const include = line.match(INCLUDE_RX)
+      if (!include) continue
+      const partialRef = parsePartialTarget(include[1].trim(), page.src)
+      if (!partialRef) continue
+      const tagsMatch = include[2].match(/tags?=([^,\]]+)/)
+      const expression = tagsMatch && tagsMatch[1]
+      const partials = contentCatalog.findBy({ component: partialRef.component, module: partialRef.module, family: 'partial' }) || []
+      const matching = partials.filter((candidate) => candidate.src.relative === partialRef.relative)
+      // Same-component includes resolve within the page's version; for
+      // cross-component includes take whichever version the catalog has.
+      const partial = matching.find((candidate) => candidate.src.version === page.src.version) || matching[0]
+      if (!partial) continue
+      for (const entry of headingsFor(partial)) {
+        if (!Object.prototype.hasOwnProperty.call(properties, entry.name)) continue
+        if (!evaluateTagExpression(entry.tags, expression)) continue
+        if (!index.has(entry.name)) index.set(entry.name, { page: pagePath, url: pageUrl })
+      }
+    }
+  }
+  cache[cacheKey] = index
+  return index
+}
+
+/**
+ * The anchor Asciidoctor generates for a property heading. With the docs'
+ * idseparator '-', invalid id characters (dots) become hyphens while
+ * underscores are valid and stay: '=== cloud_storage_enabled' gets the id
+ * 'cloud_storage_enabled', '=== redpanda.storage.mode' gets
+ * 'redpanda-storage-mode'.
+ */
+function propertyAnchor (name) {
+  return name.replace(/\./g, '-')
+}
+
+// Helm values paths for setting properties on Kubernetes. Deterministic:
+// tiered storage properties keep the chart's dedicated storage.tiered.config
+// block (which also wires credentials), broker/node properties map to
+// config.node, and every other cluster property maps to config.cluster --
+// the path the docs recommend for all cluster properties.
+function helmValuesPath (name, scope) {
+  if (name.startsWith('cloud_storage_')) return `storage.tiered.config.${name}`
+  if (scope === 'broker') return `config.node.${name}`
+  return `config.cluster.${name}`
+}
+
+let warnedNoRegistry = false
+
+/**
+ * Compare two vX.Y.Z(-pre) tags without a semver dependency. Good enough to
+ * pick the newest properties attachment.
+ */
+function compareTags (a, b) {
+  const parse = (tag) => tag.replace(/^v/, '').split('-')[0].split('.').map(Number)
+  const [a1, a2, a3] = parse(a)
+  const [b1, b2, b3] = parse(b)
+  return a1 - b1 || a2 - b2 || a3 - b3
+}
+
+/**
+ * Load and cache the property map from the newest published properties JSON
+ * attachment in the content catalog. Properties are published per component
+ * (streaming, cloud, sometimes agentic-data-plane and connect), so the JSON
+ * from the page's own component wins, falling back to the streaming (or
+ * ROOT) component, then to the newest JSON anywhere in the catalog. Returns
+ * undefined when unavailable.
+ */
+function loadProperties (config) {
+  const contentCatalog = config && config.contentCatalog
+  if (!contentCatalog) return undefined
+  const pageComponent = (config.file && config.file.src && config.file.src.component) || ''
+  const pageVersion = (config.file && config.file.src && config.file.src.version) || ''
+  return loadPropertiesFor(contentCatalog, pageComponent, pageVersion)
+}
+
+/**
+ * Same as loadProperties, addressable by component and version so the
+ * property-page-index extension can warm the caches before conversion.
+ */
+function loadPropertiesFor (contentCatalog, pageComponent, pageVersion) {
+  const cacheKey = `${pageComponent}@${pageVersion}` || '$any'
+  const cache = contentCatalog[$propertyRegistry] || (contentCatalog[$propertyRegistry] = {})
+  if (cache[cacheKey] !== undefined) return cache[cacheKey] || undefined
+
+  // Versioned components publish one properties JSON per version, so a page
+  // must validate against its OWN version's data (a 25.3 page checked
+  // against 26.x data would produce wrong results in both directions).
+  // Priority: own component and version, own component any version (newest
+  // tag), then the streaming/ROOT fallbacks, then anything.
+  const attachments = contentCatalog.findBy({ family: 'attachment' }) || []
+  const candidates = []
+  for (const attachment of attachments) {
+    if (attachment.src.module !== 'reference') continue
+    const basename = attachment.src.relative.split('/').pop()
+    const match = basename.match(PROPERTIES_JSON_RX)
+    if (!match) continue
+    candidates.push({ tag: match[1], file: attachment, component: attachment.src.component, version: attachment.src.version })
+  }
+  const newest = (list) => list.reduce((best, entry) => (!best || compareTags(entry.tag, best.tag) > 0 ? entry : best), null)
+  const pick =
+    newest(candidates.filter((c) => c.component === pageComponent && c.version === pageVersion)) ||
+    newest(candidates.filter((c) => c.component === pageComponent)) ||
+    newest(candidates.filter((c) => c.component === 'streaming')) ||
+    newest(candidates.filter((c) => c.component === 'ROOT')) ||
+    newest(candidates)
+
+  let registry = null
+  if (pick) {
+    const data = JSON.parse(pick.file.contents.toString())
+    if (data && data.properties) {
+      registry = { tag: pick.tag, properties: data.properties }
+    }
+  }
+  // Cache null too, so a missing JSON is only searched for once per build.
+  cache[cacheKey] = registry
+  return registry || undefined
+}
+
+function warnNoPropertyData () {
+  if (warnedNoRegistry) return
+  warnedNoRegistry = true
+  console.warn(chalk.yellow('Property reference data (redpanda-properties-<tag>.json attachment) not found; prop: targets are not validated.'))
+}
+
+/**
+ * Report an unknown property name according to the property-validate mode.
+ */
+function reportUnknownProperty ({ name, mode, registry, filePath }) {
+  if (mode === 'off') return
+  const fragment = name.trim().toLowerCase()
+  const commonPrefix = (a, b) => {
+    let i = 0
+    while (i < a.length && i < b.length && a[i] === b[i]) i++
+    return i
+  }
+  const candidates = Object.keys(registry.properties)
+    .map((candidate) => ({ candidate, shared: commonPrefix(candidate.toLowerCase(), fragment) }))
+    .filter((scored) => scored.shared >= Math.min(6, fragment.length))
+    .sort((a, b) => b.shared - a.shared)
+    .slice(0, 3)
+    .map((scored) => scored.candidate)
+  const hint = candidates.length ? ` Did you mean: ${candidates.join(', ')}?` : ''
+  const where = filePath ? ` in ${filePath}` : ''
+  const message = `prop:${name}[] does not match any property in the published property reference (${registry.tag})${where}.${hint}`
+  if (mode === 'error') throw new Error(message)
+  console.warn(chalk.yellow(message))
+}
+
+/**
+ * Build the AsciiDoc content emitted for one macro instance. Exported for
+ * unit testing.
+ *
+ * @param {object} opts
+ * @param {string} opts.name - Property name.
+ * @param {string} [opts.text] - Display text override.
+ * @param {boolean} opts.link - Whether to link to the reference page.
+ * @param {string} [opts.page] - Reference page override (module-relative, no .adoc).
+ * @param {string} [opts.scope] - config_scope from the published JSON.
+ * @param {string} opts.role - CSS class for the code element.
+ * @param {string} [opts.componentPrefix] - 'component:' prefix when the link
+ *   must leave the current component (which publishes no property pages).
+ * @returns {string}
+ */
+function buildPropContent ({ name, text, link, page, scope, role, componentPrefix = '', helmPath = false, docUrl }) {
+  const display = text || (helmPath ? helmValuesPath(name, scope) : name)
+  let inner = display
+  if (link) {
+    const targetPage = page || SCOPE_PAGES[scope] || SCOPE_PAGES.cluster
+    inner = `xref:${componentPrefix}reference:${targetPage}.adoc#${propertyAnchor(name)}[${display}]`
+  }
+  // The published URL of the page that documents this property, discovered
+  // at build time. The docs UI prefers it for the tooltip's documentation
+  // link -- the client can't know which scopes a component publishes or
+  // which page a shared property landed on.
+  const docAttr = docUrl ? ` data-doc-url="${docUrl}"` : ''
+  return `<code class="${role}" data-property-name="${name}"${docAttr}>${inner}</code>`
+}
+
+function propInlineMacro (config) {
+  return function () {
+    const self = this
+    self.named('prop')
+    self.process(function (parent, target, attributes) {
+      const document = parent.getDocument()
+      const name = target.trim()
+      let registry
+      let entry
+      if (config && config.contentCatalog) {
+        registry = loadProperties(config)
+        if (!registry) warnNoPropertyData()
+      }
+      if (registry) {
+        entry = registry.properties[name]
+        if (!entry) {
+          reportUnknownProperty({
+            name,
+            mode: document.getAttribute('property-validate', 'warn'),
+            registry,
+            filePath: config && config.file && config.file.src && config.file.src.path,
+          })
+        }
+      }
+      // Discover which page documents the property. The current component
+      // wins. When it doesn't document this property -- either because it
+      // publishes no property pages at all (the connect component, this
+      // repo's preview site) or because it publishes only a subset (the
+      // cloud component has no topic-properties page) -- fall back to the
+      // streaming (or ROOT) component and emit a component-qualified xref.
+      let discoveredPage
+      let discoveredUrl
+      let componentPrefix = ''
+      let suppressLink = false
+      const linkRequested = attributes.link === 'true' || attributes.link === true
+      if (registry && config.contentCatalog && !attributes.page) {
+        const component = (config.file && config.file.src && config.file.src.component) || ''
+        const version = (config.file && config.file.src && config.file.src.version) || ''
+        const ownIndex = buildPageIndex(config.contentCatalog, component, registry.properties, version)
+        const ownEntry = ownIndex.get(name)
+        if (ownEntry) {
+          discoveredPage = ownEntry.page
+          discoveredUrl = ownEntry.url
+        } else {
+          let fallbackWithPages
+          for (const fallbackComponent of ['streaming', 'ROOT']) {
+            if (fallbackComponent === component) continue
+            // A component-qualified xref without a version resolves to the
+            // fallback component's latest version, so consult exactly that
+            // version's index (which the property-page-index extension warms).
+            const latest = typeof config.contentCatalog.getComponent === 'function' &&
+              config.contentCatalog.getComponent(fallbackComponent)
+            const fallbackVersion = (latest && latest.latest && latest.latest.version) || undefined
+            const fallbackIndex = buildPageIndex(config.contentCatalog, fallbackComponent, registry.properties, fallbackVersion)
+            if (fallbackIndex.size === 0) continue
+            if (!fallbackWithPages) fallbackWithPages = fallbackComponent
+            const fallbackEntry = fallbackIndex.get(name)
+            if (fallbackEntry) {
+              discoveredPage = fallbackEntry.page
+              discoveredUrl = fallbackEntry.url
+              componentPrefix = `${fallbackComponent}:`
+              break
+            }
+          }
+          // Nothing documents the property anywhere: point the scope-derived
+          // fallback at a component that at least publishes property pages,
+          // unless the current component does.
+          if (!discoveredPage && ownIndex.size === 0 && fallbackWithPages) {
+            componentPrefix = `${fallbackWithPages}:`
+          }
+          // Property pages exist but none of them documents this property
+          // (for example, a cloud-only topic property when no site publishes
+          // a cloud topic-properties page). Linking would produce a broken
+          // xref, so render the marker without a link and say why. A plain
+          // tooltip marker for an undocumented property is fine -- only an
+          // explicit link request warrants the warning.
+          if (linkRequested && !discoveredPage && (ownIndex.size > 0 || fallbackWithPages)) {
+            const where = (config.file && config.file.src && config.file.src.path) || 'unknown file'
+            console.warn(chalk.yellow(`prop:${name}[link=true] in ${where}: no property reference page documents '${name}' in this build, so it renders without a link. Check the property's include tags on the reference pages.`))
+            suppressLink = true
+          }
+        }
+      }
+      // helm-path=auto displays the property as its Helm values path on
+      // pages rendered with env-kubernetes, so single-sourced content reads
+      // correctly for both Linux and Kubernetes audiences (the successor to
+      // the config_ref macro's hardcoded storage.tiered.config prefixing).
+      const helmPath = attributes['helm-path'] === 'auto' && document.getAttribute('env-kubernetes') !== undefined
+      const content = buildPropContent({
+        name,
+        text: attributes.text,
+        link: linkRequested && !suppressLink,
+        page: attributes.page || discoveredPage,
+        scope: entry && entry.config_scope,
+        role: document.getAttribute('property-ref-role', DEFAULT_ROLE),
+        componentPrefix,
+        helmPath,
+        docUrl: discoveredUrl ? `${discoveredUrl}#${propertyAnchor(name)}` : undefined,
+      })
+      // The xref inside the code element is resolved by the 'macros'
+      // substitution, the same mechanism the enterprise macro relies on.
+      return self.createInline(parent, 'quoted', content, { attributes: { subs: 'macros' } })
+    })
+  }
+}
+
+function register (registry, config = {}) {
+  if (typeof registry.register === 'function') {
+    registry.register(function () {
+      this.inlineMacro(propInlineMacro(config))
+    })
+  } else if (typeof registry.inlineMacro === 'function') {
+    registry.inlineMacro(propInlineMacro(config))
+  } else {
+    console.warn("no 'inlineMacro' method on alleged registry")
+  }
+  return registry
+}
+
+module.exports.register = register
+module.exports.buildPropContent = buildPropContent
+module.exports.propertyAnchor = propertyAnchor
+module.exports.helmValuesPath = helmValuesPath
+module.exports.loadPropertiesFor = loadPropertiesFor
+module.exports.compareTags = compareTags
+module.exports.extractHeadingsWithTags = extractHeadingsWithTags
+module.exports.evaluateTagExpression = evaluateTagExpression
+module.exports.buildPageIndex = buildPageIndex

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "5.8.0",
+  "version": "5.10.0",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
@@ -24,6 +24,7 @@
     "build": "antora --to-dir docs --fetch local-antora-playbook.yml",
     "serve": "wds --node-resolve --open preview/test/ --watch --root-dir docs",
     "test": "jest",
+    "test:e2e": "jest __tests__/e2e/",
     "test:mcp": "jest __tests__/mcp/",
     "test:mcp:integration": "jest __tests__/mcp/integration.test.js",
     "test:mcp:contract": "jest __tests__/mcp/cli-contract.test.js",
@@ -80,11 +81,16 @@
     "./extensions/resolve-xrefs-in-attachments": "./extensions/resolve-xrefs-in-attachments.js",
     "./extensions/unified-navigation": "./extensions/unified-navigation.js",
     "./extensions/conditional-home-redirect": "./extensions/conditional-home-redirect.js",
+    "./extensions/url-to-xref": "./extensions/url-to-xref.js",
+    "./extensions/external-link-checker": "./extensions/external-link-checker.js",
     "./macros/glossary": "./macros/glossary.js",
     "./macros/rp-connect-components": "./macros/rp-connect-components.js",
     "./macros/config-ref": "./macros/config-ref.js",
     "./macros/helm-ref": "./macros/helm-ref.js",
-    "./macros/badge": "./macros/badge.js"
+    "./macros/badge": "./macros/badge.js",
+    "./macros/enterprise": "./macros/enterprise.js",
+    "./macros/prop": "./macros/prop.js",
+    "./extensions/property-page-index": "./extensions/property-page-index.js"
   },
   "files": [
     "extensions",
@@ -98,6 +104,9 @@
     "mcp"
   ],
   "license": "ISC",
+  "engines": {
+    "node": ">=18"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/redpanda-data/docs-extensions-and-macros"
@@ -141,6 +150,7 @@
   "devDependencies": {
     "@antora/cli": "3.1.4",
     "@antora/site-generator": "3.1.4",
+    "@asciidoctor/core": "2.2.8",
     "@web/dev-server": "^0.2.5",
     "jest": "^29.7.0",
     "jest-junit": "^16.0.0"

package/tools/enterprise-features/parsers.js

@@ -0,0 +1,134 @@
+'use strict'
+
+/* Parsers for the sources of truth compared by `doc-tools validate
+ * enterprise-features`. Each parser is pure (string in, data out) so it can
+ * be unit-tested with trimmed fixtures.
+ */
+
+const Papa = require('papaparse')
+
+/**
+ * Extract the license_required_feature enum values from
+ * src/v/features/enterprise_features.h.
+ *
+ * @param {string} source - Header file contents.
+ * @returns {string[]} Enum value names in declaration order.
+ */
+function parseCoreEnum (source) {
+  const match = source.match(/enum\s+class\s+license_required_feature[^{]*\{([\s\S]*?)\}/)
+  if (!match) {
+    throw new Error('Could not find enum class license_required_feature in enterprise_features.h. The header layout may have changed.')
+  }
+  return match[1]
+    .split(',')
+    .map((entry) => entry.replace(/\/\/.*$/gm, '').trim())
+    .filter((entry) => /^[a-z_][a-z0-9_]*$/.test(entry))
+}
+
+/**
+ * Extract the names of config::enterprise<>-wrapped properties from
+ * src/v/config/configuration.h. Handles multi-line declarations by
+ * balancing angle brackets from each `enterprise<` occurrence.
+ *
+ * @param {string} source - Header file contents.
+ * @returns {string[]} Property member names.
+ */
+function parseEnterpriseProperties (source) {
+  const names = []
+  const re = /\benterprise</g
+  let match
+  while ((match = re.exec(source)) !== null) {
+    let depth = 1
+    let i = match.index + match[0].length
+    while (i < source.length && depth > 0) {
+      if (source[i] === '<') depth++
+      else if (source[i] === '>') depth--
+      i++
+    }
+    const rest = source.slice(i)
+    const nameMatch = rest.match(/^\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*;/)
+    if (nameMatch) names.push(nameMatch[1])
+  }
+  return [...new Set(names)]
+}
+
+/**
+ * Extract the plugins marked enterprise in connect internal/plugins/info.csv.
+ *
+ * @param {string} source - CSV contents.
+ * @returns {string[]} Plugin names with support == enterprise.
+ */
+function parseConnectEnterprisePlugins (source) {
+  // The real info.csv header has spaces after the commas (name, type, ...),
+  // so headers must be trimmed to get usable keys.
+  const parsed = Papa.parse(source.trim(), {
+    header: true,
+    skipEmptyLines: true,
+    transformHeader: (header) => header.trim(),
+  })
+  return parsed.data
+    .filter((row) => (row.support || '').trim().toLowerCase() === 'enterprise')
+    .map((row) => (row.name || '').trim())
+    .filter(Boolean)
+}
+
+/**
+ * Extract feature name and disabling property from the table in
+ * disable-enterprise-features.adoc. Rows look like:
+ *
+ *   | xref:...[Feature Name]
+ *   | Set `property` to ... / rpk cluster config set property value
+ *
+ * @param {string} source - AsciiDoc page contents.
+ * @returns {{feature: string, properties: string[]}[]}
+ */
+function parseDisableTable (source) {
+  const tables = source.match(/\|===([\s\S]*?)\|===/g)
+  if (!tables) return []
+  const rows = []
+  for (const table of tables) {
+    // Split into cells that start a line with '|', keeping cell bodies.
+    const cells = table
+      .split(/\n(?=\|)/)
+      .map((cell) => cell.replace(/^\|/, '').trim())
+      .filter((cell) => cell && !cell.startsWith('==='))
+    // The header row (| Feature | Action ...) is one single-line chunk at
+    // index 0. Data cells follow, one chunk per cell.
+    for (let i = 1; i + 1 < cells.length; i += 2) {
+      const nameCell = cells[i]
+      const actionCell = cells[i + 1]
+      const xrefMatch = nameCell.match(/xref:[^[]+\[([^\]]+)\]/)
+      const feature = (xrefMatch ? xrefMatch[1] : nameCell.split('\n')[0]).trim()
+      // Capture only set-targets ("Set `prop` to ..." and "config set prop"),
+      // not backticked values such as `node_add`.
+      const properties = [...new Set(
+        [...actionCell.matchAll(/[Ss]et\s+`([a-z][a-z0-9_]+)`|config set ([a-z][a-z0-9_]+)/g)]
+          .map((m) => m[1] || m[2])
+          .filter(Boolean)
+      )]
+      if (feature) rows.push({ feature, properties })
+    }
+  }
+  return rows
+}
+
+/**
+ * Extract the enterprise-components attribute list from rp-connect-docs
+ * antora.yml, without a YAML dependency on the full file structure.
+ *
+ * @param {object} antoraConfig - Parsed antora.yml object.
+ * @returns {string[]|undefined} The list, or undefined when absent.
+ */
+function extractAntoraEnterpriseComponents (antoraConfig) {
+  const attributes = antoraConfig && antoraConfig.asciidoc && antoraConfig.asciidoc.attributes
+  const list = attributes && attributes['enterprise-components']
+  return Array.isArray(list) ? list.map(String) : undefined
+}
+
+module.exports = {
+  parseCoreEnum,
+  parseEnterpriseProperties,
+  parseConnectEnterprisePlugins,
+  parseDisableTable,
+  extractAntoraEnterpriseComponents,
+}