@redpanda-data/docs-extensions-and-macros 5.3.0 → 5.3.1

package/package.json

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

package/tools/property-extractor/property_extractor.py

@@ -79,7 +79,7 @@ ENUM_PATTERN = re.compile(r'^[a-zA-Z0-9_:]+::([a-zA-Z0-9_]+)$')  # Match full qu
 CONSTRUCTOR_PATTERN = re.compile(r'([a-zA-Z0-9_:]+)\((.*)\)')
 BRACED_CONSTRUCTOR_PATTERN = re.compile(r'([a-zA-Z0-9_:]+)\{(.*)\}')
 DIGIT_SEPARATOR_PATTERN = re.compile(r"(?<=\d)'(?=\d)")
-FUNCTION_CALL_PATTERN = re.compile(r'([a-zA-Z0-9_:]+)\(\)')
+FUNCTION_CALL_PATTERN = re.compile(r'([a-zA-Z0-9_:.]+)\(\)$')
 CHRONO_PATTERN = re.compile(r'std::chrono::([a-zA-Z]+)\s*\{\s*(\d+)\s*\}')
 CHRONO_PAREN_PATTERN = re.compile(r'(?:std::)?chrono::([a-zA-Z]+)\s*\(\s*([^)]+)\s*\)')
 TIME_UNIT_PATTERN = re.compile(r'(\d+)\s*(min|s|ms|h)')
@@ -159,6 +159,15 @@ class ConstexprCache:
             re.compile(r'const\s+model::ns\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*\(\s*"([^"]+)"\s*\)'),
         ]
 
+        # Member accessors on inline constants used in property defaults,
+        # for example model::schema_registry_internal_tp.topic() -> "_schemas".
+        # Each entry maps a variable declaration to the member name whose call
+        # returns the captured string, cached under "<variable>.<member>".
+        member_accessor_patterns = [
+            # Pattern: inline const model::topic_partition name{model::topic{"value"}, ...}
+            (re.compile(r'inline\s+const\s+(?:model::)?topic_partition\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*\{\s*(?:model::)?topic\{\s*"([^"]+)"\s*\}'), 'topic'),
+        ]
+
         # Legacy specific patterns (kept for compatibility, but general patterns should cover these)
         function_patterns = {}
 
@@ -206,6 +215,17 @@ class ConstexprCache:
                                         qualified_name = f"{namespace}::{func_name}"
                                         self.function_cache[qualified_name] = func_value
 
+                            # Extract member accessors on inline constants
+                            for pattern, member in member_accessor_patterns:
+                                for match in pattern.finditer(content):
+                                    var_name = match.group(1)
+                                    value = match.group(2)
+                                    key = f"{var_name}.{member}"
+                                    namespace = self._extract_namespace_for_function(content, match.start())
+                                    self.function_cache[key] = value
+                                    if namespace:
+                                        self.function_cache[f"{namespace}::{key}"] = value
+
                             # Legacy: Extract function definitions from hardcoded patterns (if any)
                             for func_name, patterns in function_patterns.items():
                                 for pattern in patterns:

package/tools/rpk-docs/detect-platform-commands.js

@@ -0,0 +1,566 @@
+'use strict'
+
+/**
+ * Static (source-based) detection of Linux-only rpk commands.
+ *
+ * Works on any platform (including Linux CI runners, where the dynamic
+ * "build on Linux and Darwin and diff the trees" approach is impossible
+ * because a cross-compiled darwin rpk cannot be executed).
+ *
+ * How it works
+ * ------------
+ * rpk gates platform-specific commands with Go build constraints:
+ *
+ *   1. Whole-package gating: every file in a command's package carries a
+ *      Linux constraint (explicit `//go:build linux` tag or a `_linux.go`
+ *      filename suffix) and no darwin-buildable counterpart exists.
+ *      Example: pkg/cli/iotune, pkg/cli/redpanda/tune.
+ *
+ *   2. Dual registration: a package provides two variants of the same
+ *      command constructor, one per platform, registering different
+ *      subcommand sets. Example: pkg/cli/redpanda/redpanda.go
+ *      (`//go:build linux`, registers start/stop/check/mode/config/tune)
+ *      vs pkg/cli/redpanda/redpanda_darwin.go (`//go:build darwin`,
+ *      registers only the hidden admin command). Same pattern at the root:
+ *      pkg/cli/root_linux.go vs pkg/cli/root_darwin.go.
+ *
+ * This module detects both patterns:
+ *
+ *   - For every scanned package, it computes which files build on linux
+ *     and which build on darwin (from `//go:build` / `// +build` tags AND
+ *     filename-implied constraints like `_linux.go`).
+ *   - Packages whose files all fail to build on darwin (but build on
+ *     linux) and that define a cobra command constructor are Linux-only.
+ *   - Packages containing platform-differential files get a registration
+ *     diff: subcommand constructors referenced from linux-buildable files
+ *     but not from darwin-buildable files are Linux-only. Deprecated and
+ *     hidden constructors are ignored because `rpk --print-tree` (the
+ *     basis of the generated docs) excludes hidden commands.
+ *
+ * Scope: built-in commands only. Plugin commands (rpk connect, rpk ai, ...)
+ * are not part of the rpk source tree, so their platform availability
+ * cannot be derived here. Plugins keep whatever platform behavior the
+ * caller's other detection paths provide (for example, dynamic detection
+ * marks plugin-only commands when plugins are only installed in the Linux
+ * build container).
+ */
+
+const fs = require('fs')
+const path = require('path')
+
+/** GOOS values recognized in filename suffixes and build tags */
+const KNOWN_GOOS = new Set([
+  'aix', 'android', 'darwin', 'dragonfly', 'freebsd', 'hurd', 'illumos',
+  'ios', 'js', 'linux', 'nacl', 'netbsd', 'openbsd', 'plan9', 'solaris',
+  'wasip1', 'windows', 'zos'
+])
+
+/** GOOS values that satisfy the `unix` build tag */
+const UNIX_GOOS = new Set([
+  'aix', 'android', 'darwin', 'dragonfly', 'freebsd', 'hurd', 'illumos',
+  'ios', 'linux', 'netbsd', 'openbsd', 'solaris'
+])
+
+/** GOARCH values recognized in filename suffixes */
+const KNOWN_GOARCH = new Set([
+  '386', 'amd64', 'amd64p32', 'arm', 'arm64', 'arm64be', 'armbe', 'loong64',
+  'mips', 'mips64', 'mips64le', 'mips64p32', 'mips64p32le', 'mipsle',
+  'ppc', 'ppc64', 'ppc64le', 'riscv', 'riscv64', 's390', 's390x',
+  'sparc', 'sparc64', 'wasm'
+])
+
+/**
+ * Directories (relative to the rpk source root) scanned for command
+ * implementations. Modern rpk keeps commands in pkg/cli/<command>/;
+ * the other roots cover older source layouts.
+ */
+const SCAN_ROOTS = ['pkg/cli', 'pkg/cli/cmd', 'cmd/rpk']
+
+/** Directory names that never correspond to a command path segment */
+const NON_COMMAND_SEGMENTS = new Set(['internal', 'common', 'testdata'])
+
+/**
+ * Determine the GOOS constraint implied by a Go filename.
+ * Follows Go's rules: *_GOOS.go, *_GOOS_GOARCH.go constrain the OS;
+ * *_GOARCH.go alone does not.
+ * @param {string} fileName - e.g. 'redpanda_darwin.go', 'bundle_k8s_linux.go'
+ * @returns {string|null} GOOS name or null when unconstrained
+ */
+function goosFromFileName(fileName) {
+  const base = fileName.replace(/\.go$/, '')
+  const parts = base.split('_')
+  if (parts.length < 2) return null
+
+  const last = parts[parts.length - 1]
+  if (KNOWN_GOOS.has(last)) return last
+  if (KNOWN_GOARCH.has(last) && parts.length >= 3) {
+    const secondLast = parts[parts.length - 2]
+    if (KNOWN_GOOS.has(secondLast)) return secondLast
+  }
+  return null
+}
+
+/**
+ * Evaluate a `//go:build` constraint expression for a target GOOS.
+ * Supports identifiers, !, &&, || and parentheses.
+ * Unknown identifiers (custom build tags) evaluate to false, matching a
+ * default `go build` with no -tags flag. GOARCH identifiers evaluate to
+ * true because we only care about OS-level availability.
+ * @param {string} expr - Expression after `//go:build`
+ * @param {string} goos - Target GOOS ('linux' or 'darwin')
+ * @returns {boolean}
+ */
+function evaluateBuildExpr(expr, goos) {
+  const tokens = expr.match(/[A-Za-z0-9_.]+|&&|\|\||!|\(|\)/g) || []
+  let pos = 0
+
+  const peek = () => tokens[pos]
+  const next = () => tokens[pos++]
+
+  function evalIdent(ident) {
+    if (KNOWN_GOOS.has(ident)) return ident === goos
+    if (ident === 'unix') return UNIX_GOOS.has(goos)
+    if (KNOWN_GOARCH.has(ident)) return true
+    if (ident === 'cgo') return true
+    // Custom build tags (e.g. withasan, integration) are unset by default
+    return false
+  }
+
+  function parsePrimary() {
+    const tok = next()
+    if (tok === '(') {
+      const val = parseOr()
+      if (peek() === ')') next()
+      return val
+    }
+    if (tok === '!') return !parsePrimary()
+    if (tok === undefined) return false
+    return evalIdent(tok)
+  }
+
+  function parseAnd() {
+    let val = parsePrimary()
+    while (peek() === '&&') {
+      next()
+      val = parsePrimary() && val
+    }
+    return val
+  }
+
+  function parseOr() {
+    let val = parseAnd()
+    while (peek() === '||') {
+      next()
+      val = parseAnd() || val
+    }
+    return val
+  }
+
+  return parseOr()
+}
+
+/**
+ * Evaluate legacy `// +build` lines for a target GOOS.
+ * Multiple lines AND together; within a line, space-separated options OR
+ * and comma-separated terms AND.
+ * @param {string[]} lines - Contents after `// +build` (one per line)
+ * @param {string} goos - Target GOOS
+ * @returns {boolean}
+ */
+function evaluatePlusBuildLines(lines, goos) {
+  const evalTerm = (term) => {
+    let negate = false
+    while (term.startsWith('!')) {
+      negate = !negate
+      term = term.slice(1)
+    }
+    let val
+    if (KNOWN_GOOS.has(term)) val = term === goos
+    else if (term === 'unix') val = UNIX_GOOS.has(goos)
+    else if (KNOWN_GOARCH.has(term) || term === 'cgo') val = true
+    else val = false
+    return negate ? !val : val
+  }
+
+  return lines.every(line => {
+    const options = line.trim().split(/\s+/).filter(Boolean)
+    if (options.length === 0) return true
+    return options.some(opt => opt.split(',').every(evalTerm))
+  })
+}
+
+/**
+ * Extract the build constraint (if any) from a Go file's header.
+ * Only lines before the `package` declaration are considered.
+ * @param {string} content - Go file content
+ * @returns {{goBuildExpr: string|null, plusBuildLines: string[]}}
+ */
+function extractBuildConstraint(content) {
+  const header = content.split(/^package\s/m)[0]
+  const goBuildMatch = header.match(/^\/\/go:build\s+(.+)$/m)
+  const plusBuildLines = []
+  const plusBuildRe = /^\/\/\s*\+build\s+(.+)$/gm
+  let m
+  while ((m = plusBuildRe.exec(header)) !== null) {
+    plusBuildLines.push(m[1])
+  }
+  return {
+    goBuildExpr: goBuildMatch ? goBuildMatch[1].trim() : null,
+    plusBuildLines
+  }
+}
+
+/**
+ * Determine whether a Go file builds for a target GOOS, taking both the
+ * filename-implied constraint and explicit build tags into account.
+ * @param {string} fileName - Base name of the file
+ * @param {string} content - File content
+ * @param {string} goos - Target GOOS ('linux' or 'darwin')
+ * @returns {boolean}
+ */
+function fileBuildsOn(fileName, content, goos) {
+  const fileGoos = goosFromFileName(fileName)
+  if (fileGoos && fileGoos !== goos) return false
+
+  const { goBuildExpr, plusBuildLines } = extractBuildConstraint(content)
+  if (goBuildExpr) return evaluateBuildExpr(goBuildExpr, goos)
+  if (plusBuildLines.length > 0) return evaluatePlusBuildLines(plusBuildLines, goos)
+  return true
+}
+
+/**
+ * Derive a command name from a cobra constructor function name.
+ * NewStartCommand -> start, newTuneCommand -> tune, NewCommand -> null.
+ * @param {string} funcName
+ * @returns {string|null}
+ */
+function commandNameFromConstructor(funcName) {
+  const m = funcName.match(/^(?:New|new)(\w+?)(?:Command|Cmd)$/)
+  if (m && m[1]) return m[1].toLowerCase()
+  return null
+}
+
+/**
+ * Parse cobra command constructors defined in a Go file.
+ * A constructor is any `func XxxYyy(...) *cobra.Command`. For each one we
+ * record the cobra `Use:` name (first token) and whether the command is
+ * deprecated or hidden (such commands never appear in `rpk --print-tree`).
+ * @param {string} content - Go file content
+ * @returns {Object<string, {useName: string|null, excluded: boolean}>}
+ */
+function parseConstructors(content) {
+  const constructors = {}
+  const funcRe = /^func\s+(\w+)\s*\([^)]*\)\s*\*cobra\.Command\s*\{/gm
+  const matches = []
+  let m
+  while ((m = funcRe.exec(content)) !== null) {
+    matches.push({ name: m[1], start: m.index })
+  }
+
+  for (let i = 0; i < matches.length; i++) {
+    const bodyEnd = i + 1 < matches.length ? matches[i + 1].start : content.length
+    const body = content.slice(matches[i].start, bodyEnd)
+
+    const useMatch = body.match(/\bUse:\s*"([^"]+)"/)
+    const useName = useMatch ? useMatch[1].trim().split(/\s+/)[0] : null
+
+    // Deprecated or hidden commands are excluded from `rpk --print-tree`
+    const excluded = /\bHidden:\s*true\b/.test(body) ||
+                     /\bDeprecated:\s*"/.test(body) ||
+                     /\bDeprecateCmd\s*\(/.test(body)
+
+    constructors[matches[i].name] = { useName, excluded }
+  }
+
+  return constructors
+}
+
+/**
+ * Extract constructor references from all AddCommand(...) calls in a file.
+ * Handles both same-package (`NewStartCommand(...)`) and cross-package
+ * (`tune.NewCommand(...)`) references. Only functions starting with
+ * New/new are considered, which skips wrappers like cobraext.DeprecateCmd.
+ * @param {string} content - Go file content
+ * @returns {Array<{qualifier: string|null, funcName: string}>}
+ */
+function parseAddCommandRefs(content) {
+  const refs = []
+  const addRe = /\bAddCommand\s*\(/g
+  let m
+  while ((m = addRe.exec(content)) !== null) {
+    // Find the span of this AddCommand(...) call by balancing parentheses
+    let depth = 1
+    let i = m.index + m[0].length
+    while (i < content.length && depth > 0) {
+      if (content[i] === '(') depth++
+      else if (content[i] === ')') depth--
+      i++
+    }
+    const span = content.slice(m.index + m[0].length, i - 1)
+
+    const callRe = /(?:(\w+)\.)?((?:New|new)\w*)\s*\(/g
+    let c
+    while ((c = callRe.exec(span)) !== null) {
+      refs.push({ qualifier: c[1] || null, funcName: c[2] })
+    }
+  }
+  return refs
+}
+
+/**
+ * Recursively collect non-test Go files under a directory.
+ * @param {string} dir - Absolute directory path
+ * @param {Array} out - Accumulator of {absPath, dir, name}
+ */
+function collectGoFiles(dir, out) {
+  let entries
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true })
+  } catch (err) {
+    return
+  }
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      if (entry.name === 'testdata' || entry.name === 'vendor') continue
+      collectGoFiles(fullPath, out)
+    } else if (entry.name.endsWith('.go') && !entry.name.endsWith('_test.go')) {
+      out.push({ absPath: fullPath, dir, name: entry.name })
+    }
+  }
+}
+
+/**
+ * Build the command path prefix for a package directory.
+ * pkg/cli -> 'rpk'; pkg/cli/redpanda -> 'rpk redpanda';
+ * pkg/cli/cmd/redpanda (legacy) -> 'rpk redpanda'.
+ * @param {string} scanRoot - Absolute path of the scan root
+ * @param {string} dir - Absolute directory path
+ * @returns {string|null} Command path prefix, or null for non-command dirs
+ */
+function commandPrefixForDir(scanRoot, dir) {
+  const rel = path.relative(scanRoot, dir)
+  let segments = rel === '' ? [] : rel.split(path.sep)
+  // Legacy layouts nested commands under an extra cmd/ level
+  if (segments[0] === 'cmd') segments = segments.slice(1)
+  if (segments.some(s => NON_COMMAND_SEGMENTS.has(s))) return null
+  return ['rpk', ...segments].join(' ')
+}
+
+/**
+ * Analyze one scan root and add detected Linux-only command paths.
+ * @param {string} scanRoot - Absolute path of the scan root
+ * @param {Set<string>} linuxOnlyCommands - Accumulator
+ */
+function scanRootForLinuxOnly(scanRoot, linuxOnlyCommands) {
+  const files = []
+  collectGoFiles(scanRoot, files)
+  if (files.length === 0) return
+
+  // Group files (with parsed metadata) by directory
+  const dirs = new Map()
+  for (const file of files) {
+    let content
+    try {
+      content = fs.readFileSync(file.absPath, 'utf8')
+    } catch (err) {
+      continue
+    }
+    const info = {
+      name: file.name,
+      content,
+      buildsOnLinux: fileBuildsOn(file.name, content, 'linux'),
+      buildsOnDarwin: fileBuildsOn(file.name, content, 'darwin')
+    }
+    if (!dirs.has(file.dir)) dirs.set(file.dir, [])
+    dirs.get(file.dir).push(info)
+  }
+
+  // Per-directory constructor index: dir -> {funcName: {useName, excluded}}
+  const constructorIndex = new Map()
+  for (const [dir, dirFiles] of dirs) {
+    const index = {}
+    for (const f of dirFiles) {
+      Object.assign(index, parseConstructors(f.content))
+    }
+    constructorIndex.set(dir, index)
+  }
+
+  /**
+   * Resolve an AddCommand constructor reference to a visible command name.
+   * Returns null for deprecated/hidden/unresolvable commands.
+   */
+  const resolveRef = (dir, ref) => {
+    let target = null
+    let fallback = commandNameFromConstructor(ref.funcName)
+
+    if (ref.qualifier) {
+      const subDir = path.join(dir, ref.qualifier)
+      target = constructorIndex.get(subDir) || null
+      if (!fallback) fallback = ref.qualifier
+    } else {
+      target = constructorIndex.get(dir) || null
+    }
+
+    if (target && target[ref.funcName]) {
+      const ctor = target[ref.funcName]
+      if (ctor.excluded) return null
+      return ctor.useName || fallback
+    }
+
+    // Unresolvable reference: only trust it if the function name follows
+    // the cobra constructor convention (New[Xxx]Command). This skips
+    // helper arguments captured inside AddCommand spans, such as the
+    // rp.NewLauncher() argument in redpanda.NewCommand(fs, p, rp.NewLauncher()).
+    if (!/^(?:New|new)(?:\w*(?:Command|Cmd))?$/.test(ref.funcName)) return null
+    return fallback
+  }
+
+  for (const [dir, dirFiles] of dirs) {
+    const prefix = commandPrefixForDir(scanRoot, dir)
+    if (!prefix) continue
+
+    const hasDifferentialFile = dirFiles.some(f => f.buildsOnLinux !== f.buildsOnDarwin)
+
+    // Pattern 1: whole package is Linux-gated (and defines a command)
+    if (prefix !== 'rpk') {
+      const anyLinux = dirFiles.some(f => f.buildsOnLinux)
+      const anyDarwin = dirFiles.some(f => f.buildsOnDarwin)
+      const definesCommand = Object.keys(constructorIndex.get(dir)).length > 0
+      if (anyLinux && !anyDarwin && definesCommand) {
+        linuxOnlyCommands.add(prefix)
+        continue
+      }
+    }
+
+    // Pattern 2: dual registration - diff subcommands registered from
+    // linux-buildable files vs darwin-buildable files
+    if (!hasDifferentialFile) continue
+
+    const refsFor = (goos) => {
+      const names = new Set()
+      for (const f of dirFiles) {
+        const buildable = goos === 'linux' ? f.buildsOnLinux : f.buildsOnDarwin
+        if (!buildable) continue
+        for (const ref of parseAddCommandRefs(f.content)) {
+          const name = resolveRef(dir, ref)
+          if (name) names.add(name)
+        }
+      }
+      return names
+    }
+
+    const linuxRefs = refsFor('linux')
+    const darwinRefs = refsFor('darwin')
+
+    for (const name of linuxRefs) {
+      if (!darwinRefs.has(name)) {
+        linuxOnlyCommands.add(`${prefix} ${name}`)
+      }
+    }
+  }
+}
+
+/**
+ * Detect Linux-only rpk commands by statically analyzing Go source.
+ * Works on any platform, including Linux CI runners.
+ * @param {string} sourcePath - Path to the rpk Go source root (src/go/rpk)
+ * @returns {Set<string>} Linux-only command paths (e.g. 'rpk iotune').
+ *   Descendants of a returned path are implicitly Linux-only too.
+ */
+function detectLinuxOnlyFromSource(sourcePath) {
+  const linuxOnlyCommands = new Set()
+
+  const scannedRoots = new Set()
+  for (const root of SCAN_ROOTS) {
+    const absRoot = path.join(sourcePath, root)
+    if (!fs.existsSync(absRoot)) continue
+    // pkg/cli/cmd is nested inside pkg/cli; avoid scanning it twice
+    if ([...scannedRoots].some(r => absRoot.startsWith(r + path.sep))) continue
+    scannedRoots.add(absRoot)
+    scanRootForLinuxOnly(absRoot, linuxOnlyCommands)
+  }
+
+  // Drop any detected path that is a descendant of another detected path;
+  // platform markers already propagate to descendants.
+  for (const cmd of [...linuxOnlyCommands]) {
+    if ([...linuxOnlyCommands].some(other => other !== cmd && cmd.startsWith(other + ' '))) {
+      linuxOnlyCommands.delete(cmd)
+    }
+  }
+
+  return linuxOnlyCommands
+}
+
+/**
+ * List Go files under the scanned roots that carry a Linux-only build
+ * constraint (explicit tag or filename suffix). Used as a tripwire: if
+ * detection returns an empty set while this list is non-empty, the scan
+ * is almost certainly broken (wrong directory layout, changed tag style).
+ * @param {string} sourcePath - Path to the rpk Go source root
+ * @returns {string[]} Relative paths of Linux-constrained files
+ */
+function findLinuxConstrainedFiles(sourcePath) {
+  const results = []
+  for (const root of SCAN_ROOTS) {
+    const absRoot = path.join(sourcePath, root)
+    if (!fs.existsSync(absRoot)) continue
+    const files = []
+    collectGoFiles(absRoot, files)
+    for (const file of files) {
+      let content
+      try {
+        content = fs.readFileSync(file.absPath, 'utf8')
+      } catch (err) {
+        continue
+      }
+      if (fileBuildsOn(file.name, content, 'linux') && !fileBuildsOn(file.name, content, 'darwin')) {
+        results.push(path.relative(sourcePath, file.absPath))
+      }
+    }
+  }
+  return [...new Set(results)]
+}
+
+/**
+ * Emit a loud warning when platform detection came back empty even though
+ * the source demonstrably contains Linux-gated files. Never let a scan
+ * failure silently mark every command as cross-platform.
+ * @param {string} sourcePath - Path to the rpk Go source root
+ * @param {Set<string>} linuxOnlyCommands - Combined detection result
+ * @returns {boolean} True when the tripwire fired
+ */
+function warnIfDetectionLooksBroken(sourcePath, linuxOnlyCommands) {
+  if (linuxOnlyCommands.size > 0) return false
+
+  const constrained = findLinuxConstrainedFiles(sourcePath)
+  if (constrained.length === 0) return false
+
+  console.warn('\n' + '!'.repeat(70))
+  console.warn('⚠ PLATFORM DETECTION TRIPWIRE: no Linux-only commands were detected,')
+  console.warn(`⚠ but the rpk source contains ${constrained.length} Linux-constrained file(s), e.g.:`)
+  for (const file of constrained.slice(0, 5)) {
+    console.warn(`⚠   - ${file}`)
+  }
+  console.warn('⚠ This usually means the static source scan failed (unexpected')
+  console.warn('⚠ directory layout or build-tag style) and every command is about')
+  console.warn('⚠ to be marked as available on both Linux and macOS, which is wrong.')
+  console.warn('⚠ Fix tools/rpk-docs/detect-platform-commands.js before publishing')
+  console.warn('⚠ these docs. See redpanda-data/docs#1831 for the impact of this.')
+  console.warn('!'.repeat(70) + '\n')
+  return true
+}
+
+module.exports = {
+  detectLinuxOnlyFromSource,
+  findLinuxConstrainedFiles,
+  warnIfDetectionLooksBroken,
+  // Exported for unit tests
+  fileBuildsOn,
+  goosFromFileName,
+  evaluateBuildExpr,
+  evaluatePlusBuildLines,
+  parseConstructors,
+  parseAddCommandRefs,
+  commandNameFromConstructor
+}

package/tools/rpk-docs/generate-rpk-docs.js

@@ -291,6 +291,24 @@ function shouldUsePartialDir(overrides, commandPath) {
   return false
 }
 
+/**
+ * Check if a command belongs to the rpk cloud or rpk security secret families.
+ * Their pages are routed to the cloud partials directory (cloudSecretDir) and
+ * published by cloud-docs, so links to them from regular pages must cross to
+ * the cloud component.
+ * @param {string} commandPath - Full command path (e.g., "rpk cloud login")
+ * @returns {boolean}
+ */
+function isCloudSecretCommand(commandPath) {
+  return commandPath === 'rpk cloud' || commandPath.startsWith('rpk cloud ') ||
+    commandPath === 'rpk security secret' || commandPath.startsWith('rpk security secret ')
+}
+
+/**
+ * Antora component that publishes the rpk cloud and rpk security secret pages.
+ */
+const CLOUD_DOCS_COMPONENT = 'cloud-data-platform'
+
 /**
  * Get command metadata from overrides
  * @param {Object} overrides - Overrides object (resolved)
@@ -2420,8 +2438,7 @@ function updateNavFile(navFile, commands, resolvedOverrides, topLevelWithSubcomm
     if (isProtectedCommandPath(commandPath, protectedPlugins)) continue
     if (shouldExcludeCommand(resolvedOverrides, commandPath)) continue
     if (shouldUsePartialDir(resolvedOverrides, commandPath)) continue
-    if (commandPath.startsWith('rpk cloud')) continue
-    if (commandPath.startsWith('rpk security secret')) continue
+    if (isCloudSecretCommand(commandPath)) continue
 
     const parts = commandPath.split(' ')
     const stars = '*'.repeat(parts.length + 1)
@@ -2725,16 +2742,13 @@ async function generateRpkDocs(options = {}) {
     // Build subcommands with correct xref paths
     // Filter out excluded and asPartial subcommands — excluded have no file,
     // asPartial ones live in the partials directory with no linkable xref.
-    // rpk cloud and rpk security secret are hardcoded-routed to partials
-    // (single-sourced into cloud docs), so they have no linkable pages
-    // either: rpk-security.adoc linking rpk-security-secret.adoc was a
-    // broken xref in the published site.
+    // rpk cloud and rpk security secret rows stay in the table: their pages
+    // are routed to the cloud partials directory and published by
+    // cloud-docs, so the xref below links across to the cloud component
+    // instead of dropping the row (which hid the subcommand entirely).
     const subcommands = (command.commands || [])
       .filter(sub => {
         const subPath = `${commandPath} ${sub.name}`
-        if (subPath.startsWith('rpk cloud') || subPath.startsWith('rpk security secret')) {
-          return false
-        }
         return !shouldExcludeCommand(resolvedOverrides, subPath) && !shouldUsePartialDir(resolvedOverrides, subPath)
       })
       .map(sub => {
@@ -2756,6 +2770,13 @@ async function generateRpkDocs(options = {}) {
           }
         }
 
+        // rpk cloud and rpk security secret pages are routed to the cloud
+        // partials directory and published by cloud-docs, so rows in regular
+        // pages must link across to the cloud component.
+        if (cloudSecretDir && isCloudSecretCommand(subPath) && !isCloudSecretCommand(commandPath)) {
+          xrefPath = `${CLOUD_DOCS_COMPONENT}:${xrefPath}`
+        }
+
         // Use overridden description if available
         const subOverride = resolvedOverrides?.commands?.[subPath]
         const subDescription = subOverride?.description || sub.description || ''
@@ -2765,6 +2786,8 @@ async function generateRpkDocs(options = {}) {
           fullPath: subPath,
           dashifiedPath: dashifiedSubPath,
           xrefPath,
+          cloudOnly: subOverride?.cloudOnly === true,
+          selfHostedOnly: subOverride?.selfHostedOnly === true,
           shortDesc: ensurePeriod(capToTwoSentences(formatDescription(subDescription, textTransformations, { skipTableConversion: true, skipListConversion: true })))
         }
       })
@@ -2949,10 +2972,8 @@ async function generateRpkDocs(options = {}) {
 
     // Determine output path
     // Check if this command should go to cloudSecretDir
-    const isCloudCommand = commandPath.startsWith('rpk cloud')
-    const isSecuritySecretCommand = commandPath.startsWith('rpk security secret')
     const useCloudSecretDir = cloudSecretDir && (
-      isCloudCommand || isSecuritySecretCommand || shouldUsePartialDir(resolvedOverrides, commandPath)
+      isCloudSecretCommand(commandPath) || shouldUsePartialDir(resolvedOverrides, commandPath)
     )
     const effectiveOutputDir = useCloudSecretDir ? cloudSecretDir : outputDir
 

package/tools/rpk-docs/rpk-docs-handler.js

@@ -8,6 +8,7 @@ const os = require('os')
 const semver = require('semver')
 const { findRepoRoot } = require('../../cli-utils/doc-tools-utils')
 const { generateRpkDocs, applyOverridesToTree, resolveReferences, shouldExcludeCommand, shouldUsePartialDir } = require('./generate-rpk-docs')
+const { detectLinuxOnlyFromSource, warnIfDetectionLooksBroken } = require('./detect-platform-commands')
 const { generateRpkDiff, printDiffReport, generateWhatsNewSection, flattenToMap } = require('./report-delta')
 const { loadAndValidateOverrides, ValidationResult } = require('./validate-overrides')
 const { validateDirectory, formatResults } = require('./validate-output')
@@ -656,105 +657,6 @@ function fetchRpkTreeFromLinuxSource(sourcePath, pluginPins = {}) {
   }
 }
 
-/**
- * Scan Go source files for Linux-only build tags
- * Looks for //go:build linux or // +build linux
- * @param {string} sourcePath - Path to rpk Go source directory
- * @returns {Set<string>} Set of Linux-only command paths (e.g., 'rpk redpanda tune')
- */
-function detectLinuxOnlyFromSource(sourcePath) {
-  const linuxOnlyCommands = new Set()
-
-  // Map of source directory patterns to command paths
-  // rpk commands are typically in pkg/cli/cmd/<command>/<subcommand>/
-  const scanDirectory = (dir, prefix = '') => {
-    if (!fs.existsSync(dir)) return
-
-    const entries = fs.readdirSync(dir, { withFileTypes: true })
-
-    for (const entry of entries) {
-      const fullPath = path.join(dir, entry.name)
-
-      if (entry.isDirectory()) {
-        // Recurse into subdirectories
-        const newPrefix = prefix ? `${prefix} ${entry.name}` : entry.name
-        scanDirectory(fullPath, newPrefix)
-      } else if (entry.name.endsWith('.go') && !entry.name.endsWith('_test.go')) {
-        // Check Go files for build tags
-        try {
-          const content = fs.readFileSync(fullPath, 'utf8')
-          const firstLines = content.split('\n').slice(0, 20).join('\n')
-
-          // Check for Linux build constraints
-          const hasLinuxTag = /\/\/go:build\s+.*linux/.test(firstLines) ||
-                             /\/\/\s*\+build\s+.*linux/.test(firstLines)
-
-          if (hasLinuxTag) {
-            // Try to determine command path from file location
-            const commandPath = inferCommandPath(sourcePath, fullPath, entry.name)
-            if (commandPath) {
-              linuxOnlyCommands.add(commandPath)
-            }
-          }
-        } catch (err) {
-          // Skip files we can't read
-        }
-      }
-    }
-  }
-
-  // Scan the cmd/rpk directory for command implementations
-  const cmdDir = path.join(sourcePath, 'pkg', 'cli', 'cmd')
-  if (fs.existsSync(cmdDir)) {
-    scanDirectory(cmdDir, 'rpk')
-  }
-
-  // Also check the older structure
-  const oldCmdDir = path.join(sourcePath, 'cmd', 'rpk')
-  if (fs.existsSync(oldCmdDir)) {
-    scanDirectory(oldCmdDir, 'rpk')
-  }
-
-  return linuxOnlyCommands
-}
-
-/**
- * Infer command path from Go source file location
- * @param {string} sourcePath - Root source path
- * @param {string} filePath - Full path to Go file
- * @param {string} fileName - Name of the Go file
- * @returns {string|null} Command path or null
- */
-function inferCommandPath(sourcePath, filePath, fileName) {
-  // Get relative path from source root
-  const relativePath = filePath.replace(sourcePath, '').replace(/^\//, '')
-
-  // Common patterns:
-  // pkg/cli/cmd/redpanda/tune.go -> rpk redpanda tune
-  // pkg/cli/cmd/redpanda/start.go -> rpk redpanda start
-  // cmd/rpk/iotune/iotune.go -> rpk iotune
-
-  // Remove common prefixes and file extension
-  let parts = relativePath
-    .replace(/^pkg\/cli\/cmd\//, '')
-    .replace(/^cmd\/rpk\//, '')
-    .replace(/\.go$/, '')
-    .split('/')
-
-  // If file name matches directory name, use directory only
-  // e.g., iotune/iotune.go -> iotune
-  if (parts.length > 1 && parts[parts.length - 1] === parts[parts.length - 2]) {
-    parts = parts.slice(0, -1)
-  }
-
-  // Filter out common non-command directories
-  parts = parts.filter(p => !['internal', 'common', 'config', 'cmd'].includes(p))
-
-  if (parts.length === 0) return null
-
-  return 'rpk ' + parts.join(' ')
-}
-
 /**
  * Add platform markers to command tree based on source analysis
  * @param {Object} tree - Command tree from rpk --print-tree
@@ -769,11 +671,18 @@ function addPlatformMarkersFromSource(tree, linuxOnlyCommands) {
            [...linuxOnlyCommands].some(loc => cmdPath.startsWith(loc + ' '))
   }
 
+  // Collect every tree path actually marked Linux-only so the persisted
+  // linux_only_commands list is fully expanded (each descendant listed),
+  // matching what dynamic Linux-vs-Darwin tree comparison produces.
+  const markedPaths = new Set()
+
   const markCommands = (commands, parentPath = 'rpk') => {
     if (!commands) return commands
     return commands.map(cmd => {
       const fullPath = `${parentPath} ${cmd.name}`
-      const platforms = isLinuxOnly(fullPath)
+      const linuxOnly = isLinuxOnly(fullPath)
+      if (linuxOnly) markedPaths.add(fullPath)
+      const platforms = linuxOnly
         ? [PLATFORMS.LINUX]
         : [PLATFORMS.LINUX, PLATFORMS.DARWIN]
       return {
@@ -792,11 +701,15 @@ function addPlatformMarkersFromSource(tree, linuxOnlyCommands) {
     }
   }
 
+  const markedCommands = markCommands(tree.commands)
+
   return {
     ...tree,
     platforms: [PLATFORMS.LINUX, PLATFORMS.DARWIN],
-    linux_only_commands: [...linuxOnlyCommands],
-    commands: markCommands(tree.commands)
+    // Union of detected paths and marked tree paths: keeps detected roots
+    // even when the tree was built on a platform where they don't exist
+    linux_only_commands: [...new Set([...linuxOnlyCommands, ...markedPaths])].sort(),
+    commands: markedCommands
   }
 }
 
@@ -1166,6 +1079,37 @@ function makeLinkablePredicate(overridesData) {
   }
 }
 
+// Command subtrees whose changes never belong in the Self-Managed What's
+// new. rpk ai's documentation home is adp-docs, and the ADP release notes
+// already cover its CLI changes per release. The plugin-release receiver
+// workflow excludes ai from --update-whats-new for exactly this reason; the
+// full-regeneration path must agree, or a full run floods the Self-Managed
+// release notes with rpk ai entries (a rename release alone produces 21 new
+// plus 21 removed bullets).
+const WHATS_NEW_EXCLUDED_SUBTREES = ['rpk ai']
+
+/**
+ * Return a copy of diffData without entries under the excluded subtrees.
+ * Only the published What's-new block filters; diff reports and PR
+ * summaries keep the full picture.
+ * @param {Object} diffData - Diff from generateRpkDiff
+ * @param {string[]} [excluded] - Command-path prefixes to drop
+ * @returns {Object} Filtered copy
+ */
+function filterDiffForWhatsNew(diffData, excluded = WHATS_NEW_EXCLUDED_SUBTREES) {
+  const outside = (cmdPath) => !excluded.some(prefix =>
+    cmdPath === prefix || (typeof cmdPath === 'string' && cmdPath.startsWith(prefix + ' ')))
+  const details = diffData.details || {}
+  const filteredDetails = { ...details }
+  for (const key of ['newCommands', 'newlyDeprecatedCommands', 'removedCommands', 'descriptionChanges']) {
+    if (Array.isArray(details[key])) filteredDetails[key] = details[key].filter(e => outside(e.path))
+  }
+  for (const key of ['newFlags', 'removedFlags', 'changedDefaults', 'changedFlagTypes', 'changedFlagRequirements', 'changedFlagDescriptions']) {
+    if (Array.isArray(details[key])) filteredDetails[key] = details[key].filter(e => outside(e.commandPath))
+  }
+  return { ...diffData, details: filteredDetails }
+}
+
 function updateWhatsNewFile(diffData, whatsNewPath, version, options = {}) {
   // Each block opens with a "=== <version>" heading so accumulated blocks
   // (successive RCs, multiple plugin releases) never collide on section ids
@@ -1437,8 +1381,28 @@ function acquireRpkBinary(rpkVersion, options = {}) {
     console.warn(`Native build failed (${nativeErr.message.split('\n')[0]}); building in a container...`)
     const goVersion = getRequiredGoVersion(sourcePath)
     const goImage = goVersion ? `golang:${goVersion}` : 'golang:1'
+    // Cross-compile for the HOST platform: the container reports
+    // GOOS=linux, and a linux binary dies silently when executed on the
+    // macOS host that needs it for plugin installs (review finding on the
+    // 5.3.0 train). rpk builds with CGO disabled, so cross-compilation
+    // from the linux container is safe.
+    // Only macOS and Linux hosts are supported: mapping anything else to
+    // linux would hand a Windows host an unrunnable binary, the exact bug
+    // class the cross-compile fixes (review finding on #238).
+    if (process.platform !== 'darwin' && process.platform !== 'linux') {
+      throw new Error(
+        `${nativeErr.message}\n` +
+        `Container fallback does not support host platform "${process.platform}". ` +
+        'Update Go, or pass --rpk-bin <path> to use an existing rpk binary.'
+      )
+    }
+    const hostGoos = process.platform === 'darwin' ? 'darwin' : 'linux'
+    const hostGoarch = process.arch === 'arm64' ? 'arm64' : 'amd64'
     const buildResult = spawnSync('docker', [
       'run', '--rm',
+      '-e', `GOOS=${hostGoos}`,
+      '-e', `GOARCH=${hostGoarch}`,
+      '-e', 'CGO_ENABLED=0',
       '-v', `${path.resolve(sourcePath)}:/rpk-source:ro`,
       '-v', `${workDir}:/out`,
       '-w', '/rpk-source',
@@ -2001,10 +1965,14 @@ async function handleRpkDocsGeneration(options = {}) {
         // render without xrefs because plugin subtrees may render as
         // partials with no linkable pages.
         if (whatsNewPath) {
-          const label = resolvedVersion
-            ? `${plugin} plugin ${resolvedVersion}`
-            : `${plugin} plugin`
-          updateWhatsNewFile(pluginDiffData, whatsNewPath, label, { xrefs: false, sectionHeading: '== rpk plugins' })
+          if (WHATS_NEW_EXCLUDED_SUBTREES.includes(`rpk ${plugin}`)) {
+            console.log(`Skipping What's new for rpk ${plugin}: its documentation home covers CLI changes in its own release notes`)
+          } else {
+            const label = resolvedVersion
+              ? `${plugin} plugin ${resolvedVersion}`
+              : `${plugin} plugin`
+            updateWhatsNewFile(pluginDiffData, whatsNewPath, label, { xrefs: false, sectionHeading: '== rpk plugins' })
+          }
         }
       }
 
@@ -2117,7 +2085,7 @@ async function handleRpkDocsGeneration(options = {}) {
 
           // Update what's-new file if requested
           if (whatsNewPath) {
-            updateWhatsNewFile(diffData, whatsNewPath, rpkVersion, { linkable: makeLinkablePredicate(overridesData), hasSubcommands: makeSubcommandPredicate(tree) })
+            updateWhatsNewFile(filterDiffForWhatsNew(diffData), whatsNewPath, rpkVersion, { linkable: makeLinkablePredicate(overridesData), hasSubcommands: makeSubcommandPredicate(tree) })
           }
         } else {
           console.warn(`Warning: Could not load previous version ${diffVersion} for diff`)
@@ -2217,10 +2185,17 @@ async function handleRpkDocsGeneration(options = {}) {
     rpkVersion = effectiveRef || 'local'
 
     // Step 2: Detect Linux-only commands
-    // Try dynamic detection first (compare Linux vs Darwin builds)
-    // Fall back to static lists for plugins and known commands
+    // Static detection (build-constraint analysis) works on any platform,
+    // including Linux CI runners. Dynamic detection (comparing Linux vs
+    // Darwin builds) supplements it below when the host can run both.
     console.log('\nAnalyzing source for Linux-only commands...')
     let linuxOnlyCommands = detectLinuxOnlyFromSource(sourcePath)
+    if (linuxOnlyCommands.size > 0) {
+      console.log(`Static detection found ${linuxOnlyCommands.size} Linux-only command path(s):`)
+      for (const cmd of [...linuxOnlyCommands].sort()) {
+        console.log(`  - ${cmd}`)
+      }
+    }
 
     // Step 3: Build rpk and get command tree
     // Use Docker if available (for running rpk plugins in Linux)
@@ -2230,8 +2205,19 @@ async function handleRpkDocsGeneration(options = {}) {
     const canBuildNative = goCheck.status === 0
     const canBuildLinux = dockerCheck.status === 0
 
-    // Dynamic detection: if we can build on both platforms, compare the trees
-    if (canBuildLinux && canBuildNative && os.platform() !== 'linux') {
+    // Dynamic detection: if we can build on both platforms, compare the trees.
+    // Only possible on non-Linux hosts: a Linux runner can cross-compile a
+    // darwin rpk but cannot execute it to get its command tree, so Linux CI
+    // relies on the static detection above.
+    // RPK_DOCS_SKIP_DYNAMIC_DETECTION=1 forces the static-only path (useful
+    // for testing what a Linux CI runner would produce).
+    const skipDynamicDetection = ['1', 'true'].includes(
+      String(process.env.RPK_DOCS_SKIP_DYNAMIC_DETECTION || '').toLowerCase()
+    )
+    if (skipDynamicDetection) {
+      console.log('\nDynamic platform detection disabled via RPK_DOCS_SKIP_DYNAMIC_DETECTION')
+    }
+    if (canBuildLinux && canBuildNative && os.platform() !== 'linux' && !skipDynamicDetection) {
       console.log('\nBuilding rpk on both Linux and Darwin for dynamic platform detection...')
 
       try {
@@ -2297,6 +2283,12 @@ async function handleRpkDocsGeneration(options = {}) {
       )
     }
 
+    // Tripwire: an empty combined detection result while the source tree
+    // demonstrably contains Linux-gated files means the scan is broken and
+    // Linux-only pages are about to be published as cross-platform
+    // (see redpanda-data/docs#1831).
+    warnIfDetectionLooksBroken(sourcePath, linuxOnlyCommands)
+
     // Step 4: Add platform markers based on detection
     // This includes both source scanning results and static fallback lists
     tree = addPlatformMarkersFromSource(tree, linuxOnlyCommands)
@@ -2413,7 +2405,7 @@ async function handleRpkDocsGeneration(options = {}) {
 
         // Update what's-new file if requested
         if (whatsNewPath) {
-          updateWhatsNewFile(diffData, whatsNewPath, rpkVersion, { linkable: makeLinkablePredicate(overridesData), hasSubcommands: makeSubcommandPredicate(tree) })
+          updateWhatsNewFile(filterDiffForWhatsNew(diffData), whatsNewPath, rpkVersion, { linkable: makeLinkablePredicate(overridesData), hasSubcommands: makeSubcommandPredicate(tree) })
         }
       } else {
         console.warn(`Warning: Could not load previous version ${diffVersion} for diff`)
@@ -2827,6 +2819,7 @@ module.exports = {
   getPlatformDescription,
   getCurrentPlatform,
   updateOverridesWithIntroducedVersions,
+  filterDiffForWhatsNew,
   computeDescriptionCoverage,
   updateWhatsNewFile,
   KNOWN_PLUGINS,

package/tools/rpk-docs/templates/command.hbs

@@ -389,8 +389,20 @@ This section provides examples of how to use `{{commandPath}}`.
 |Command |Description
 
 {{#each subcommands}}
+{{#if cloudOnly}}
+ifdef::env-cloud[]
+{{/if}}
+{{#if selfHostedOnly}}
+ifndef::env-cloud[]
+{{/if}}
 |xref:{{xrefPath}}[`{{fullPath}}`]
 |{{{shortDesc}}}
+{{#if cloudOnly}}
+endif::[]
+{{/if}}
+{{#if selfHostedOnly}}
+endif::[]
+{{/if}}
 
 {{/each}}
 |===

package/tools/rpk-docs/validate-overrides.js

@@ -465,8 +465,24 @@ function validatePlatforms(commandOverride, context) {
 function validateFlags(commandOverride, context) {
   const result = new ValidationResult()
 
+  // cloudOnly and selfHostedOnly are mutually exclusive: setting both wraps
+  // the row in an ifdef::env-cloud + ifndef::env-cloud pair that no build
+  // can satisfy, so the row silently vanishes from BOTH sites.
+  if (commandOverride.cloudOnly && commandOverride.selfHostedOnly) {
+    result.addError(
+      'cloudOnly and selfHostedOnly are both set: the command row is unsatisfiable and disappears from every build. Set at most one.',
+      context
+    )
+  }
+
   if (commandOverride.flags) {
     for (const [flagName, flagOverride] of Object.entries(commandOverride.flags)) {
+      if (flagOverride.cloudOnly && flagOverride.selfHostedOnly) {
+        result.addError(
+          `cloudOnly and selfHostedOnly are both set on flag "${flagName}": the flag row is unsatisfiable and disappears from every build. Set at most one.`,
+          `${context}.flags.${flagName}`
+        )
+      }
       // Validate flag name format
       if (!flagName.match(/^[a-zA-Z][-a-zA-Z0-9]*$/)) {
         result.addWarning(