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

package/tools/overrides-audit/index.js

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+
+/**
+ * Overrides Audit CLI
+ *
+ * Field-level classification of docs-side override entries against
+ * extracted source strings, powering the override-retirement loop
+ * (retirement: delete REDUNDANT fields on each release regeneration;
+ * upstreaming: draft source PRs from UPSTREAMABLE/SPLIT candidates).
+ *
+ * Usage (standalone):
+ *   node tools/overrides-audit/index.js \
+ *     --overrides docs-data/property-overrides.json \
+ *     --extracted tools/property-extractor/gen/properties-output.json \
+ *     [--surface properties|rpk|connect] [--format json|human] [--output <file>]
+ *
+ * Also exposed as `doc-tools overrides audit` and the `audit_overrides`
+ * MCP tool. See README.adoc in this directory for the classification rules
+ * and the upstream_ref policy.
+ */
+
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+const ADAPTERS = {
+  properties: () => require('./adapters/properties'),
+  rpk: () => require('./adapters/rpk'),
+  connect: () => require('./adapters/connect')
+}
+
+/**
+ * Run the audit and return the result object.
+ *
+ * @param {Object} options - { overrides, extracted, surface, format, output }.
+ * @returns {Object} Audit result ({ surface, manifest, summary, ... }).
+ */
+function runAudit (options) {
+  const surface = options.surface || 'properties'
+  const adapterFactory = ADAPTERS[surface]
+  if (!adapterFactory) {
+    throw new Error(`Unknown surface '${surface}'. Valid surfaces: ${Object.keys(ADAPTERS).join(', ')}`)
+  }
+  if (!options.overrides) {
+    throw new Error('Missing required option --overrides <path>')
+  }
+  let extractedPath = options.extracted ? path.resolve(options.extracted) : undefined
+  if (surface === 'properties' && !extractedPath) {
+    if (!options.repo) {
+      throw new Error('Provide --extracted <path> (raw extractor JSON, no overrides applied) or --repo <path> (a redpanda checkout to extract from)')
+    }
+    // Extract raw source strings ourselves. Never audit against a published
+    // redpanda-properties-<tag>.json: those already have overrides applied,
+    // which classifies every description REDUNDANT.
+    const fs = require('fs')
+    const os = require('os')
+    const { runExtractor } = require('../lint-strings/surfaces/properties')
+    const json = runExtractor(path.resolve(options.repo), (msg) => console.error(msg))
+    extractedPath = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'overrides-audit-')), 'extracted.json')
+    fs.writeFileSync(extractedPath, JSON.stringify(json))
+  }
+
+  const adapter = adapterFactory()
+  return adapter.audit({
+    overridesPath: path.resolve(options.overrides),
+    extractedPath
+  })
+}
+
+/**
+ * Render the audit result as a human-readable report.
+ *
+ * @param {Object} result - Audit result from runAudit().
+ * @returns {string} Multi-line report.
+ */
+function formatHumanReport (result) {
+  const lines = []
+  const { summary } = result
+  lines.push('='.repeat(64))
+  lines.push(`Overrides audit — surface: ${result.surface}`)
+  lines.push(`Overrides: ${result.overrides_file}`)
+  lines.push(`Extracted: ${result.extracted_file || '(none)'}`)
+  lines.push('='.repeat(64))
+  lines.push('')
+  lines.push(`Classified ${summary.total} override field(s):`)
+  const order = [
+    'REDUNDANT',
+    'UPSTREAMABLE',
+    'KEEP_UNTIL_UPSTREAMED',
+    'UPSTREAMABLE_SLOT',
+    'REDUNDANT_OR_UPSTREAMABLE',
+    'KEEP',
+    'REVIEW'
+  ]
+  for (const cls of order) {
+    if (summary.byClass[cls]) {
+      lines.push(`  ${cls.padEnd(26)} ${summary.byClass[cls]}`)
+    }
+  }
+  lines.push('')
+  lines.push('Per field:')
+  for (const [field, byClass] of Object.entries(summary.byField)) {
+    const parts = Object.entries(byClass).map(([cls, count]) => `${cls}: ${count}`)
+    lines.push(`  ${field.padEnd(20)} ${parts.join(', ')}`)
+  }
+
+  const sections = [
+    ['REDUNDANT', 'Retire in the next auto-docs PR (source already matches)'],
+    ['UPSTREAMABLE', 'Send upstream verbatim'],
+    ['UPSTREAMABLE_SLOT', 'Migrate to a source metadata slot'],
+    ['REDUNDANT_OR_UPSTREAMABLE', 'Needs a human ruling'],
+    ['REVIEW', 'Needs attention (possible source bug, typo, or missing property)']
+  ]
+  for (const [cls, heading] of sections) {
+    const rows = result.manifest.filter((row) => row.class === cls)
+    if (rows.length === 0) continue
+    lines.push('')
+    lines.push(`${cls} — ${heading} (${rows.length}):`)
+    for (const row of rows) {
+      lines.push(`  • ${row.name} [${row.field}]${row.note ? ` — ${row.note}` : ''}`)
+    }
+  }
+
+  if (result.cross_check) {
+    lines.push('')
+    lines.push('Cross-check (compare-properties.js):')
+    lines.push(`  descriptions still masked by overrides: ${result.cross_check.changedDescriptions}`)
+    lines.push(`  empty source descriptions: ${result.cross_check.emptyDescriptions}`)
+    if (result.cross_check.violations.length > 0) {
+      lines.push(`  CLASSIFIER BUG — raw-equal but not REDUNDANT: ${result.cross_check.violations.join(', ')}`)
+    } else {
+      lines.push('  consistency: OK (every raw-equal description classified REDUNDANT)')
+    }
+  }
+
+  lines.push('')
+  lines.push('='.repeat(64))
+  return lines.join('\n')
+}
+
+/**
+ * CLI entry point.
+ *
+ * @param {string[]} argv - process.argv.
+ */
+function main (argv) {
+  const { Command } = require('commander')
+  const program = new Command()
+
+  program
+    .name('overrides-audit')
+    .description('Classify docs-side override fields against extracted source strings')
+    .requiredOption('--overrides <path>', 'Path to the overrides JSON file (for example docs-data/property-overrides.json)')
+    .option('--extracted <path>', 'Path to the extracted source JSON (property extractor raw output; required for the properties surface)')
+    .option('--surface <surface>', 'Override surface: properties, rpk, or connect', 'properties')
+    .option('--format <format>', 'Output format: json or human', 'json')
+    .option('--output <path>', 'Also write the JSON result to this file')
+    .action((options) => {
+      try {
+        const result = runAudit(options)
+        if (options.output) {
+          fs.mkdirSync(path.dirname(path.resolve(options.output)), { recursive: true })
+          fs.writeFileSync(path.resolve(options.output), JSON.stringify(result, null, 2) + '\n')
+          console.error(`JSON result written to ${options.output}`)
+        }
+        if (options.format === 'human') {
+          console.log(formatHumanReport(result))
+        } else {
+          console.log(JSON.stringify(result, null, 2))
+        }
+      } catch (err) {
+        console.error(`Error: ${err.message}`)
+        process.exit(1)
+      }
+    })
+
+  program.parse(argv)
+}
+
+if (require.main === module) {
+  main(process.argv)
+}
+
+module.exports = { runAudit, formatHumanReport }

package/tools/preview-string/index.js

@@ -0,0 +1,245 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+/**
+ * doc-tools preview-string: render ONE doc-string declaration from local
+ * engineering source to the final published snippet, so an engineer can see
+ * what their string becomes on docs.redpanda.com BEFORE it ships.
+ *
+ * - properties: runs the real Python extractor and the real Handlebars
+ *   property template. With --overrides, renders a second "as shipped"
+ *   pane and prints a MASKED-BY-OVERRIDE notice when a docs-repo override
+ *   would replace the source string.
+ * - rpk: runs the string through the real formatDescription() transformer
+ *   from tools/rpk-docs (the killer demo: an ALLCAPS line becomes a "==="
+ *   heading before your eyes).
+ * - metrics/helm/crd/connect: renders the description in the surface's
+ *   output shape with a one-line header.
+ *
+ * Extraction reuses the lint-strings surface modules, so preview and lint
+ * always agree on what the source declares.
+ */
+
+const HR = '-'.repeat(72)
+
+function pane (title, body) {
+  return `${HR}\n${title}\n${HR}\n${body}\n`
+}
+
+/**
+ * Render a preview for one declaration.
+ *
+ * @param {Object} options
+ * @param {string} options.repo - Path to the engineering checkout
+ * @param {string} options.surface - properties|rpk|metrics|helm|crd|connect
+ * @param {string} options.name - Declaration name (property name, rpk
+ *   command or --flag, metric name, helm key path, crd json field, connect
+ *   component/field name)
+ * @param {string} [options.overrides] - Overrides JSON path (properties only)
+ * @param {Function} [options.log]
+ * @returns {string} The rendered preview text
+ */
+function previewString (options) {
+  const { repo, surface, name, overrides = null, log = (msg) => process.stderr.write(`${msg}\n`) } = options
+  if (!repo) throw new Error('preview-string requires --repo <path>')
+  if (!surface) throw new Error('preview-string requires --surface <name>')
+  if (!name) throw new Error('preview-string requires --name <name>')
+  const repoPath = path.resolve(repo)
+  if (!fs.existsSync(repoPath)) throw new Error(`Repo path does not exist: ${repoPath}`)
+
+  if (overrides && surface !== 'properties') {
+    log(`Note: --overrides applies to the properties surface only; ignoring it for ${surface}.`)
+  }
+
+  switch (surface) {
+    case 'properties': return previewProperty(repoPath, name, overrides, log)
+    case 'rpk': return previewRpk(repoPath, name, log)
+    case 'metrics':
+    case 'helm':
+    case 'crd':
+    case 'connect': return previewLintSurface(surface, repoPath, name, log)
+    default: throw new Error(`Unknown surface "${surface}". Supported: properties, rpk, metrics, helm, crd, connect`)
+  }
+}
+
+/* -------------------------------- properties ---------------------------- */
+
+function previewProperty (repo, name, overridesPath, log) {
+  const properties = require('../lint-strings/surfaces/properties')
+  const handlebars = require('handlebars')
+  // Requiring the generator registers its Handlebars helpers (eq, ...) as a
+  // side effect - the same environment a real generation run uses.
+  require('../property-extractor/generate-handlebars-docs')
+
+  const json = properties.runExtractor(repo, log)
+  const prop = (json.properties || {})[name]
+  if (!prop) {
+    const near = Object.keys(json.properties || {}).filter((k) => k.includes(name)).slice(0, 8)
+    throw new Error(`Property "${name}" not found in ${repo}.${near.length > 0 ? ` Close matches: ${near.join(', ')}` : ''}`)
+  }
+
+  const templatePath = path.join(properties.TOOL_ROOT, 'templates', 'property.hbs')
+  const template = handlebars.compile(fs.readFileSync(templatePath, 'utf8'))
+  const asSource = template({ ...prop, name }).trim()
+
+  const spanNote = prop.line_start != null
+    ? `${prop.defined_in || ''}:${prop.line_start}-${prop.line_end != null ? prop.line_end : prop.line_start}`
+    : (prop.defined_in || '(unknown source location)')
+  let out = `Property: ${name}  (${spanNote})\n\n`
+  out += pane('AS SOURCE (rendered from your checkout)', asSource)
+
+  if (overridesPath) {
+    const raw = JSON.parse(fs.readFileSync(path.resolve(overridesPath), 'utf8'))
+    // Accept both { properties: { name: {...} } } (docs-repo
+    // property-overrides.json) and a flat { name: {...} } map.
+    const entry = (raw.properties && raw.properties[name]) || (!raw.properties && raw[name]) || null
+    if (!entry) {
+      out += `\nNo override entry for "${name}" in ${overridesPath}: the source string ships as-is.\n`
+    } else {
+      const shipped = { ...prop, ...entry, name }
+      const asShipped = template(shipped).trim()
+      out += '\n' + pane('AS SHIPPED (override applied)', asShipped)
+      if (asShipped !== asSource) {
+        const maskedFields = Object.keys(entry).filter((k) => JSON.stringify(prop[k]) !== JSON.stringify(entry[k]))
+        out += `\nMASKED-BY-OVERRIDE: the docs repo overrides ${maskedFields.map((f) => `"${f}"`).join(', ') || 'this entry'} for ${name}.\n` +
+          'Changes to the source string will NOT reach docs.redpanda.com until the override field is retired (fix the source string upstream, then delete the override field).\n'
+      } else {
+        out += '\nOverride entry present but the rendered output is identical: the override is redundant and can be retired.\n'
+      }
+    }
+  }
+  return out
+}
+
+/* ----------------------------------- rpk -------------------------------- */
+
+/**
+ * Mirror the real generate-rpk-docs.js pipeline for one string:
+ * - Long: parseDescriptionSections first (ALLCAPS lines become "===" section
+ *   headings, exactly as on the generated command page), then
+ *   formatDescription + ensurePeriod on the main description and
+ *   formatDescription on each section body.
+ * - Short: ensurePeriod(capToTwoSentences(formatDescription(...))) - the
+ *   shortDesc path.
+ * - Flag usage: ensurePeriod(formatDescription(...)) - the flag table path.
+ */
+function publishRpkString (kind, text, helpers) {
+  const { formatDescription, parseDescriptionSections, ensurePeriod, capToTwoSentences } = helpers
+  if (kind === 'long') {
+    const { mainDescription, sections } = parseDescriptionSections(text)
+    let out = ensurePeriod(formatDescription(mainDescription))
+    for (const [section, body] of Object.entries(sections)) {
+      const title = section.charAt(0).toUpperCase() + section.slice(1).toLowerCase()
+      out += `\n\n=== ${title}\n\n${formatDescription(body)}`
+    }
+    return out.trim()
+  }
+  if (kind === 'short') {
+    return ensurePeriod(capToTwoSentences(formatDescription(text, null, { skipTableConversion: true, skipListConversion: true }))).trim()
+  }
+  return ensurePeriod(formatDescription(text)).trim()
+}
+
+function previewRpk (repo, name, log) {
+  const rpk = require('../lint-strings/surfaces/rpk')
+  const helpers = require('../rpk-docs/generate-rpk-docs')
+
+  log(`Scanning rpk sources in ${repo}...`)
+  const decls = rpk.extract({ repo, log })
+  const isFlag = name.startsWith('-')
+  const target = isFlag ? name.replace(/^-+/, '') : name
+  const matches = decls.filter((d) => isFlag
+    ? (d.meta.kind === 'flag' && d.name === target)
+    : (d.meta.kind !== 'flag' && d.name === target))
+  if (matches.length === 0) {
+    throw new Error(`No rpk ${isFlag ? 'flag' : 'command'} named "${target}" found under src/go/rpk/pkg/cli. Use the leaf command token (for example "health") or --flag-name.`)
+  }
+
+  let out = ''
+  for (const d of matches.slice(0, 10)) {
+    const label = d.meta.kind === 'flag' ? `--${d.name} (flag usage)` : `${d.name} (${d.meta.kind})`
+    out += `rpk ${label}  ${d.file}:${d.line_start}-${d.line_end}\n\n`
+    if (d.string == null) {
+      out += 'Source string is built dynamically (not a plain literal); preview unavailable.\n\n'
+      continue
+    }
+    out += pane('AS SOURCE', d.string)
+    out += '\n' + pane('AS PUBLISHED (after formatDescription)', publishRpkString(d.meta.kind, d.string, helpers)) + '\n'
+  }
+  if (matches.length > 10) out += `(${matches.length - 10} more matches not shown)\n`
+  return out
+}
+
+/* -------------------- metrics / helm / crd / connect --------------------- */
+
+const SHAPES = {
+  // How each surface's description lands on the published page.
+  metrics: (d) => `=== ${d.name}\n\n${d.string}`,
+  helm: (d) => `=== ${d.name}\n\n${d.string}${d.meta.default_annotation ? `\n\n*Default:* ${d.meta.default_annotation}` : ''}`,
+  crd: (d) => `| *\`${d.name}\`* +\n(table cell in the CRD reference and \`kubectl explain\` output)\n| ${d.string}`,
+  connect: (d) => d.string // connect descriptions ARE the AsciiDoc page body
+}
+
+function previewLintSurface (surfaceName, repo, name, log) {
+  const { SURFACES } = require('../lint-strings')
+  const surface = SURFACES[surfaceName]
+  log(`Scanning ${surfaceName} sources in ${repo}...`)
+  const decls = surface.extract({ repo, log })
+  const matches = decls.filter((d) => d.name === name ||
+    (surfaceName === 'crd' && `${d.meta.struct}.${d.name}` === name))
+  if (matches.length === 0) {
+    throw new Error(`No ${surfaceName} declaration named "${name}" found in ${repo}.`)
+  }
+
+  let out = ''
+  for (const d of matches.slice(0, 10)) {
+    out += `${surfaceName}: ${d.name}${d.meta.struct ? ` (in ${d.meta.struct})` : ''}  ${d.file}:${d.line_start}-${d.line_end}\n\n`
+    if (d.string == null) {
+      out += 'No description in source; this ships blank.\n\n'
+      continue
+    }
+    out += pane('AS PUBLISHED', SHAPES[surfaceName](d)) + '\n'
+  }
+  if (matches.length > 10) out += `(${matches.length - 10} more matches not shown)\n`
+  return out
+}
+
+/* ----------------------------------- CLI --------------------------------- */
+
+function runCli (options) {
+  try {
+    process.stdout.write(previewString({
+      repo: options.repo,
+      surface: options.surface,
+      name: options.name,
+      overrides: options.overrides || null
+    }))
+  } catch (err) {
+    console.error(`Error: ${err.message}`)
+    process.exit(2)
+  }
+  process.exit(0)
+}
+
+module.exports = { previewString, publishRpkString, runCli }
+
+// Direct usage: node tools/preview-string --repo <path> --surface <s> --name <n> [--overrides <path>]
+if (require.main === module) {
+  const args = process.argv.slice(2)
+  const options = {}
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === '--repo') options.repo = args[++i]
+    else if (arg === '--surface') options.surface = args[++i]
+    else if (arg === '--name') options.name = args[++i]
+    else if (arg === '--overrides') options.overrides = args[++i]
+    else {
+      console.error(`Unknown argument: ${arg}`)
+      console.error('Usage: node tools/preview-string --repo <path> --surface <s> --name <name> [--overrides <path>]')
+      process.exit(2)
+    }
+  }
+  runCli(options)
+}

package/tools/property-extractor/Makefile

@@ -20,6 +20,11 @@ TOOL_ROOT     := $(MODULE_ROOT)/tools/property-extractor
 TMP_ROOT      := $(TOOL_ROOT)/tmp
 REDPANDA_SRC  := $(TMP_ROOT)/redpanda
 TREESITTER_DIR:= $(TOOL_ROOT)/tree-sitter/tree-sitter-cpp
+# One pin, read from the module that also bootstraps this grammar at run time
+# (tools/lint-strings/surfaces/properties.js ensureTreesitter). Holding the tag
+# in both places meant a bump here would silently leave the linter checking out
+# a different grammar than the generator.
+TREESITTER_TAG:= $(shell node -p "require('$(MODULE_ROOT)/tools/lint-strings/surfaces/properties.js').TREESITTER_TAG")
 VENV          := $(TOOL_ROOT)/tmp/redpanda-property-extractor-venv
 PYTHON        := $(VENV)/bin/python
 TREE_SITTER   := npx tree-sitter
@@ -131,13 +136,13 @@ treesitter:
 	  git clone https://github.com/tree-sitter/tree-sitter-cpp.git "$(TREESITTER_DIR)"; \
 	fi
 	@CURRENT_TAG=$$(git -C "$(TREESITTER_DIR)" describe --tags --exact-match 2>/dev/null || true); \
-	if [ "$$CURRENT_TAG" = "v0.20.5" ] && [ -f "$(TREESITTER_DIR)/src/parser.c" ]; then \
-	  echo "✅ tree-sitter-cpp parser already generated at v0.20.5; skipping regeneration"; \
+	if [ "$$CURRENT_TAG" = "$(TREESITTER_TAG)" ] && [ -f "$(TREESITTER_DIR)/src/parser.c" ]; then \
+	  echo "✅ tree-sitter-cpp parser already generated at $(TREESITTER_TAG); skipping regeneration"; \
 	else \
-	  echo "🔄 Ensuring tree-sitter-cpp is at compatible version v0.20.5…"; \
+	  echo "🔄 Ensuring tree-sitter-cpp is at compatible version $(TREESITTER_TAG)…"; \
 	  cd "$(TREESITTER_DIR)" && \
 	    git fetch --tags -q && \
-	    git checkout -q v0.20.5 && \
+	    git checkout -q $(TREESITTER_TAG) && \
 	    echo "🔧 Generating parser in $(TREESITTER_DIR)…" && \
 	    export CFLAGS="-Wno-unused-but-set-variable" && \
 	    npm install --silent && \

package/tools/property-extractor/README.adoc

@@ -142,8 +142,12 @@ Create a `property-overrides.json` file to customize extracted documentation:
       "description": "Network address and port for Kafka API clients to connect to Redpanda brokers.",
       "example": ".Example\n[,yaml]\n----\nredpanda:\n  kafka_api:\n    - name: internal\n      address: 0.0.0.0\n      port: 9092\n    - name: external\n      address: redpanda.example.com\n      port: 19092\n----",
       "version": "v21.4.1",
-      "related_topics": [
-        "xref:manage:kubernetes/networking/k-networking-and-connectivity.adoc[]"
+      "see_also": [
+        "xref:manage:kubernetes/networking/k-networking-and-connectivity.adoc[]",
+        {
+          "content": "xref:manage:cluster-maintenance/config-cluster.adoc[]",
+          "cloud_only": true
+        }
       ]
     }
   }
@@ -156,7 +160,17 @@ Create a `property-overrides.json` file to customize extracted documentation:
 * `example` - Add usage example in AsciiDoc format
 * `example_file` - Load example from external file
 * `version` - Document when property was introduced
-* `related_topics` - Array of AsciiDoc xrefs to related content
+* `see_also` - Array of related links. Each item is either a plain string (shown in every build) or an object `{content, cloud_only}` / `{content, self_hosted_only}` (shown only in that build, wrapped with `ifdef::env-cloud[]`/`ifndef::env-cloud[]` at generation time). Setting both `cloud_only` and `self_hosted_only` on the same item is rejected by the schema — it would wrap the item in both directives at once, so it renders in neither build.
+* `related_topics` - Deprecated predecessor to `see_also`. An array of plain strings, optionally prefixed `cloud-only:` / `self-managed-only:` for the same conditional behavior — that prefix is free text with no validation, which is why `see_also` replaced it. Existing `related_topics` entries keep working; new entries should use `see_also`.
+
+Validate an overrides file against its schema (`docs-data/property-overrides.schema.json`) before generating docs:
+
+[,bash]
+----
+npx doc-tools validate property-overrides --overrides docs-data/property-overrides.json
+----
+
+This catches malformed `see_also` items and unrecognized override keys — including a typo that would otherwise be silently dropped, since applying an override to an *existing* property has no catch-all pass-through (only overrides that create a new property from scratch do).
 
 === Understanding property changes
 

package/tools/property-extractor/helpers/index.js

@@ -16,8 +16,7 @@ module.exports = {
   anchorName: require('./anchorName.js'),
   normalizePropertyAnchors: require('./normalizePropertyAnchors.js'),
   canonicalizePropertyXrefs: require('./canonicalizePropertyXrefs.js'),
-  parseRelatedTopic: require('./parseRelatedTopic.js'),
-  allTopicsConditional: require('./allTopicsConditional.js'),
+  seeAlsoView: require('./seeAlsoView.js'),
   capitalize: require('./capitalize.js'),
   length: require('./length.js'),
 };

package/tools/property-extractor/helpers/seeAlsoView.js

@@ -0,0 +1,76 @@
+'use strict';
+
+/**
+ * Normalizes a property's related-topics data into one shape for the
+ * templates to render, regardless of which field or convention the override
+ * author used:
+ *
+ *   - see_also (current): array of items, each either a plain string (shown
+ *     everywhere) or {content, cloud_only, self_hosted_only} (shown only in
+ *     the named build). Schema-validated — see docs-data/property-overrides.schema.json.
+ *   - related_topics (deprecated, still read for back-compat with existing
+ *     override files): array of strings, optionally prefixed with
+ *     'cloud-only:' / 'self-managed-only:' to get the same conditional
+ *     behaviour. That prefix was free text with no validation; see_also
+ *     replaces it with data a schema can check.
+ *
+ * @param {object} property - A property record, as extracted or overridden.
+ * @returns {Array<{content: string, cloudOnly: boolean, selfHostedOnly: boolean}>}
+ */
+function normalizeSeeAlso(property) {
+  if (!property) return [];
+  const rawItems = Array.isArray(property.see_also)
+    ? property.see_also
+    : Array.isArray(property.related_topics)
+      ? property.related_topics
+      : [];
+
+  return rawItems
+    .map((item) => {
+      if (typeof item === 'string') {
+        const trimmed = item.trim();
+        if (trimmed.startsWith('cloud-only:')) {
+          return { content: trimmed.slice('cloud-only:'.length).trim(), cloudOnly: true, selfHostedOnly: false };
+        }
+        if (trimmed.startsWith('self-managed-only:')) {
+          return { content: trimmed.slice('self-managed-only:'.length).trim(), cloudOnly: false, selfHostedOnly: true };
+        }
+        return { content: trimmed, cloudOnly: false, selfHostedOnly: false };
+      }
+      if (item && typeof item === 'object' && typeof item.content === 'string') {
+        return {
+          content: item.content.trim(),
+          cloudOnly: item.cloud_only === true,
+          selfHostedOnly: item.self_hosted_only === true,
+        };
+      }
+      return null;
+    })
+    .filter((item) => item && item.content);
+}
+
+/**
+ * Builds the single view object property.hbs/topic-property.hbs render the
+ * "Related topics" row from: the normalized item list, plus which env-cloud
+ * branch (if any) every item shares, so the row's own header can be wrapped
+ * once instead of duplicated per item.
+ *
+ * sectionType is 'cloud' only when every item is cloud-only, 'self-managed'
+ * only when every item is self-hosted-only, and 'normal' otherwise (a mix of
+ * conditional and/or unconditional items, each wrapped individually).
+ *
+ * @param {object} property - A property record, as extracted or overridden.
+ * @returns {{items: Array, sectionType: ('cloud'|'self-managed'|'normal')}}
+ */
+function seeAlsoView(property) {
+  const items = normalizeSeeAlso(property);
+  let sectionType = 'normal';
+  if (items.length > 0) {
+    if (items.every((item) => item.cloudOnly)) sectionType = 'cloud';
+    else if (items.every((item) => item.selfHostedOnly)) sectionType = 'self-managed';
+  }
+  return { items, sectionType };
+}
+
+module.exports = seeAlsoView;
+module.exports.normalizeSeeAlso = normalizeSeeAlso;

package/tools/property-extractor/parser.py

@@ -362,8 +362,29 @@ def parse_cpp_source(treesitter_parser, cpp_language, source_code):
     parameters = PropertyBag()
     current_field = None
     seen_first_argument = False
+    # Line spans (1-indexed, inclusive) of each full member-initializer entry
+    # (`name(arg, arg, ...)`), keyed by field name. Recorded so downstream
+    # consumers (for example, doc-string linting and PR suggestion blocks) can
+    # anchor a property to its exact source lines. Additive: existing
+    # consumers of the output JSON are unaffected.
+    declaration_spans = {}
 
     for node, label in captures:
+        # The SOURCE_QUERY also captures the whole field_initializer node as
+        # @field. Use it to record the declaration's line span; the entry is
+        # keyed by its field_identifier child so this works regardless of the
+        # order tree-sitter returns same-start captures in.
+        if label == "field" and node.type == "field_initializer":
+            name_node = next(
+                (c for c in node.children if c.type == "field_identifier"), None
+            )
+            if name_node is not None:
+                declaration_spans[name_node.text.decode("utf-8")] = (
+                    node.start_point[0] + 1,
+                    node.end_point[0] + 1,
+                )
+            continue
+
         # Start of a new field initializer
         if label == "field" and node.type == "field_identifier":
             current_field = node.text.decode("utf-8")
@@ -391,6 +412,11 @@ def parse_cpp_source(treesitter_parser, cpp_language, source_code):
             if normalized_param:
                 parameters[current_field]["params"].append(normalized_param)
 
+    for field_name, (line_start, line_end) in declaration_spans.items():
+        if field_name in parameters:
+            parameters[field_name]["line_start"] = line_start
+            parameters[field_name]["line_end"] = line_end
+
     return parameters