@redpanda-data/docs-extensions-and-macros 5.13.5 → 5.17.0

package/cli-utils/sync-schemas.js

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

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "5.13.5",
+  "version": "5.17.0",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
@@ -32,6 +32,7 @@
     "test:python": "./__tests__/tools/property-extractor/setup-and-test.sh",
     "test:cgo": "node __tests__/tools/cgo-detection.test.js",
     "test:all": "npm run test && npm run test:python && npm run test:cgo",
+    "eval:doc-strings": "node evals/doc-strings/run-evals.js",
     "generate:cli-docs": "node tools/generate-cli-docs.js",
     "bundle:admin": "doc-tools generate bundle-openapi --surface admin",
     "bundle:connect": "doc-tools generate bundle-openapi --surface connect",

package/tools/generate-cli-docs.js

@@ -277,74 +277,35 @@ IMPORTANT: This documentation is auto-generated. Do not edit manually. Run \`npm
   const mainData = parseHelp(mainHelp);
   doc += generateCommandDoc('', mainData, null, 2);
 
-  // Top-level commands (excluding 'generate' which has subcommands)
-  const topLevelCommands = [
-    'install-test-dependencies',
-    'get-redpanda-version',
-    'get-console-version',
-    'link-readme',
-    'fetch',
-    'setup-mcp',
-    'validate-mcp',
-    'preview-prompt',
-    'mcp-version'
-  ];
-
-  topLevelCommands.forEach(cmd => {
-    console.log(`  Generating docs for: ${cmd}`);
-    const help = getHelpOutput(cmd);
-    const data = parseHelp(help);
-    const jsdoc = jsdocs[cmd];
-    doc += generateCommandDoc(cmd, data, jsdoc, 2);
-  });
-
-  // Generate command and its subcommands
-  console.log('  Generating docs for: generate');
-  const generateHelp = getHelpOutput('generate');
-  const generateData = parseHelp(generateHelp);
-  doc += generateCommandDoc('generate', generateData, null, 2);
-
-  // Generate subcommands
-  const generateSubcommands = [
-    'property-docs',
-    'metrics-docs',
-    'rpk-docs',
-    'rpk-env-partial',
-    'rpcn-connector-docs',
-    'helm-spec',
-    'cloud-regions',
-    'crd-spec',
-    'bundle-openapi',
-    'update-connect-version',
-    'migrate-rpcn-metadata',
-    'migrate-rpcn-descriptions'
-  ];
-
-  generateSubcommands.forEach(subcmd => {
-    console.log(`    Generating docs for: generate ${subcmd}`);
-    const help = getHelpOutput(`generate ${subcmd}`);
-    const data = parseHelp(help);
-    const jsdoc = jsdocs[subcmd];
-    doc += generateCommandDoc(`generate ${subcmd}`, data, jsdoc, 3);
-  });
+  // Walk the command tree the CLI itself reports, rather than three
+  // hardcoded lists. Those lists had drifted both ways at once: lint-strings,
+  // preview-string and overrides were undocumented while README.adoc points
+  // users here as the complete reference, and `preview-prompt` was still
+  // getting a section even though the command no longer exists (the generator
+  // fell back to the top-level help for it, so the section was real-looking
+  // and wrong). A command group is anything whose help lists Commands: of its
+  // own, so a new command or subcommand is documented the moment it is
+  // registered.
+  const documentCommand = (commandPath, level) => {
+    const label = commandPath.join(' ');
+    console.log(`${'  '.repeat(level - 1)}Generating docs for: ${label}`);
+    const data = parseHelp(getHelpOutput(label));
+    const jsdoc = jsdocs[commandPath[commandPath.length - 1]];
+    doc += generateCommandDoc(label, data, jsdoc, level);
+    for (const child of data.commands) {
+      // Commander lists `help [command]` in every group; it is not a command
+      // anyone documents.
+      const childName = child.name.split(/[\s[<]/)[0];
+      if (childName === 'help') continue;
+      documentCommand([...commandPath, childName], level + 1);
+    }
+  };
 
-  // Validate command and its subcommands
-  console.log('  Generating docs for: validate');
-  const validateHelp = getHelpOutput('validate');
-  const validateData = parseHelp(validateHelp);
-  doc += generateCommandDoc('validate', validateData, null, 2);
-
-  const validateSubcommands = [
-    'enterprise-features'
-  ];
-
-  validateSubcommands.forEach(subcmd => {
-    console.log(`    Generating docs for: validate ${subcmd}`);
-    const help = getHelpOutput(`validate ${subcmd}`);
-    const data = parseHelp(help);
-    const jsdoc = jsdocs[subcmd];
-    doc += generateCommandDoc(`validate ${subcmd}`, data, jsdoc, 3);
-  });
+  for (const child of mainData.commands) {
+    const childName = child.name.split(/[\s[<]/)[0];
+    if (childName === 'help') continue;
+    documentCommand([childName], 2);
+  }
 
   // Write to file
   const outputPath = path.join(__dirname, '..', 'CLI_REFERENCE.adoc');

package/tools/lint-strings/diff.js

@@ -0,0 +1,137 @@
+'use strict'
+
+const { spawnSync } = require('child_process')
+
+/**
+ * Diff support for declaration-anchored linting.
+ *
+ * Diff mode never lints hunks directly: descriptions are clang-format-wrapped
+ * adjacent string literals, so a PR touching one wrapped line must surface the
+ * FULL declaration. The flow is: parse `git diff <base>...HEAD` into changed
+ * (post-image) line numbers per file, route each file to a surface by path,
+ * extract declarations from those files at HEAD, and keep declarations whose
+ * line span intersects the changed lines.
+ */
+
+/**
+ * Path -> surface routing table. First match wins. A surface routed here
+ * without an extractor in the index.js SURFACES registry is reported as
+ * not-yet-supported instead of silently dropping the files.
+ */
+const SURFACE_ROUTES = [
+  { surface: 'properties', pattern: /^src\/v\/config\// },
+  { surface: 'metrics', pattern: /(^|\/)[^/]*probe\.cc$|^src\/v\/metrics\// },
+  { surface: 'rpk', pattern: /^src\/go\/rpk\/pkg\/cli\// },
+  // Both chart layouts ship: charts/<name>/chart/values.yaml (redpanda,
+  // console) and charts/<name>/values.yaml (connectors).
+  { surface: 'helm', pattern: /^charts\/[^/]+\/(chart\/)?values\.yaml$/ },
+  { surface: 'crd', pattern: /^operator\/api\// },
+  { surface: 'connect', pattern: /^internal\/impl\// }
+]
+
+/**
+ * Route a repo-relative file path to a surface id, or null when the file is
+ * not a doc-string surface.
+ */
+function routeFile (file) {
+  for (const route of SURFACE_ROUTES) {
+    if (route.pattern.test(file)) return route.surface
+  }
+  return null
+}
+
+/**
+ * Run `git diff <base>...HEAD` in the repo and parse it into a map of
+ * file -> Set of changed line numbers in the post-image (HEAD) version.
+ * Deleted files (no post-image) are omitted.
+ *
+ * @param {string} repo - Path to the git checkout
+ * @param {string} base - Base ref (`git diff base...HEAD`)
+ * @returns {Map<string, Set<number>>}
+ */
+function getChangedLines (repo, base) {
+  const result = spawnSync(
+    'git',
+    ['diff', '--unified=0', '--no-color', `${base}...HEAD`],
+    { cwd: repo, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 }
+  )
+  if (result.error) throw result.error
+  if (result.status !== 0) {
+    throw new Error(`git diff ${base}...HEAD failed in ${repo}: ${result.stderr || result.stdout}`)
+  }
+  return parseUnifiedDiff(result.stdout)
+}
+
+/**
+ * Parse unified diff text (produced with --unified=0) into
+ * file -> Set(changed post-image line numbers).
+ */
+function parseUnifiedDiff (diffText) {
+  const changed = new Map()
+  let currentFile = null
+
+  for (const line of diffText.split('\n')) {
+    // Only git's file headers count: "+++ b/<path>" or "+++ /dev/null".
+    // (An added content line that itself starts with "++ " would otherwise
+    // look like a header under --unified=0.)
+    if (line.startsWith('+++ b/')) {
+      currentFile = line.slice(6).trim()
+      continue
+    }
+    if (line.startsWith('+++ /dev/null')) {
+      currentFile = null
+      continue
+    }
+    if (!line.startsWith('@@') || currentFile === null) continue
+
+    const hunk = line.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/)
+    if (!hunk) continue
+    const start = parseInt(hunk[1], 10)
+    const count = hunk[2] === undefined ? 1 : parseInt(hunk[2], 10)
+    if (count === 0) continue // pure deletion: no post-image lines
+
+    if (!changed.has(currentFile)) changed.set(currentFile, new Set())
+    const lines = changed.get(currentFile)
+    for (let i = 0; i < count; i++) lines.add(start + i)
+  }
+
+  return changed
+}
+
+/**
+ * Group changed files by surface.
+ *
+ * @param {Map<string, Set<number>>} changedLines - From getChangedLines
+ * @returns {Object} surface -> Map(file -> Set(lines))
+ */
+function classifyDiff (changedLines) {
+  const bySurface = {}
+  for (const [file, lines] of changedLines) {
+    const surface = routeFile(file)
+    if (!surface) continue
+    if (!bySurface[surface]) bySurface[surface] = new Map()
+    bySurface[surface].set(file, lines)
+  }
+  return bySurface
+}
+
+/**
+ * True when the inclusive line span [lineStart, lineEnd] contains at least
+ * one changed line.
+ */
+function spanIntersects (lineStart, lineEnd, lineSet) {
+  if (lineStart == null || lineEnd == null || !lineSet) return false
+  for (const line of lineSet) {
+    if (line >= lineStart && line <= lineEnd) return true
+  }
+  return false
+}
+
+module.exports = {
+  SURFACE_ROUTES,
+  routeFile,
+  getChangedLines,
+  parseUnifiedDiff,
+  classifyDiff,
+  spanIntersects
+}

package/tools/lint-strings/engine.js

@@ -0,0 +1,163 @@
+'use strict'
+
+/**
+ * Rule runner for lint-strings.
+ *
+ * Adopts the VALIDATION_RULES shape from tools/rpk-docs/validate-output.js:
+ * each rule is { name, description, severity, check() -> issues[] }, with
+ * skipRules/onlyRules filtering and a byRule summary. The difference is the
+ * unit of work: rules here check one extracted *declaration* (a property,
+ * metric, rpk command, ...) rather than a generated .adoc file.
+ *
+ * Declaration shape (produced by the surface modules in ./surfaces):
+ *   {
+ *     surface: 'properties',          // surface id
+ *     name: 'cluster_id',             // declared name (null if unresolvable)
+ *     file: 'src/v/config/...',       // path relative to --repo
+ *     line_start: 1852,               // 1-indexed, inclusive
+ *     line_end: 1857,                 //   spans the FULL declaration
+ *     string: 'The doc string',       // extracted doc string (null if none)
+ *     declaration_text: '...',        // exact source lines of the span
+ *     convention: { ... },            // surface conventions (echoed in findings)
+ *     meta: { ... }                   // surface-specific extras for rules
+ *   }
+ *
+ * Severity levels: error | warning | info.
+ */
+
+const SEVERITIES = ['error', 'warning', 'info']
+
+/**
+ * Run rules over a list of declarations.
+ *
+ * @param {Array} declarations - Declarations from a surface module
+ * @param {Array} rules - Rules ({ name, severity, check(decl) -> issues[] }).
+ *   Optional rule fields:
+ *   - runOnUnverifiable: also run when decl.meta.unverifiable is set
+ *     (all other rules are skipped for unverifiable declarations, so a
+ *     non-literal source string can never produce an error)
+ * @param {Object} options - { skipRules: [names], onlyRules: [names] }
+ * @returns {Object} { findings, summary: { byRule, bySurface } }
+ */
+function runRules (declarations, rules, options = {}) {
+  const { skipRules = [], onlyRules = null } = options
+  const findings = []
+  const summary = emptySummary()
+
+  for (const decl of declarations) {
+    summary.totalDeclarations++
+    ensureSurface(summary, decl.surface).declarations++
+    const issues = []
+
+    for (const rule of rules) {
+      if (skipRules.includes(rule.name)) continue
+      if (onlyRules && !onlyRules.includes(rule.name)) continue
+      // Unverifiable declarations (for example, a metric description built
+      // with fmt::format) only run rules that opt in; they must never error.
+      if (decl.meta && decl.meta.unverifiable && !rule.runOnUnverifiable) continue
+
+      try {
+        for (const issue of rule.check(decl) || []) {
+          const severity = issue.severity || rule.severity
+          issues.push({
+            id: rule.name,
+            severity: SEVERITIES.includes(severity) ? severity : 'warning',
+            message: issue.message
+          })
+        }
+      } catch (err) {
+        issues.push({
+          id: rule.name,
+          severity: 'error',
+          message: `Rule execution failed: ${err.message}`
+        })
+      }
+    }
+
+    if (issues.length === 0) continue
+
+    findings.push({
+      surface: decl.surface,
+      name: decl.name,
+      file: decl.file,
+      line_start: decl.line_start,
+      line_end: decl.line_end,
+      string: decl.string,
+      declaration_text: decl.declaration_text,
+      rules: issues,
+      convention: decl.convention || {},
+      in_pr_diff: Boolean(decl.in_pr_diff)
+    })
+
+    tally(summary, decl.surface, issues)
+  }
+
+  return { findings, summary }
+}
+
+function emptySummary () {
+  return {
+    totalDeclarations: 0,
+    flaggedDeclarations: 0,
+    errors: 0,
+    warnings: 0,
+    info: 0,
+    byRule: {},
+    bySurface: {}
+  }
+}
+
+function ensureSurface (summary, surface) {
+  if (!summary.bySurface[surface]) {
+    summary.bySurface[surface] = { declarations: 0, flagged: 0, errors: 0, warnings: 0, info: 0 }
+  }
+  return summary.bySurface[surface]
+}
+
+function tally (summary, surface, issues) {
+  summary.flaggedDeclarations++
+  ensureSurface(summary, surface).flagged++
+
+  for (const issue of issues) {
+    if (!summary.byRule[issue.id]) {
+      summary.byRule[issue.id] = { errors: 0, warnings: 0, info: 0 }
+    }
+    const bucket = issue.severity === 'error' ? 'errors' : issue.severity === 'warning' ? 'warnings' : 'info'
+    summary.byRule[issue.id][bucket]++
+    summary.bySurface[surface][bucket]++
+    summary[bucket]++
+  }
+}
+
+/**
+ * Merge per-surface run results into one combined result.
+ */
+function mergeResults (results) {
+  const merged = { findings: [], summary: emptySummary() }
+  for (const result of results) {
+    merged.findings.push(...result.findings)
+    const s = result.summary
+    merged.summary.totalDeclarations += s.totalDeclarations
+    merged.summary.flaggedDeclarations += s.flaggedDeclarations
+    merged.summary.errors += s.errors
+    merged.summary.warnings += s.warnings
+    merged.summary.info += s.info
+    for (const [rule, counts] of Object.entries(s.byRule)) {
+      if (!merged.summary.byRule[rule]) merged.summary.byRule[rule] = { errors: 0, warnings: 0, info: 0 }
+      merged.summary.byRule[rule].errors += counts.errors
+      merged.summary.byRule[rule].warnings += counts.warnings
+      merged.summary.byRule[rule].info += counts.info
+    }
+    for (const [surface, counts] of Object.entries(s.bySurface)) {
+      if (!merged.summary.bySurface[surface]) {
+        merged.summary.bySurface[surface] = { declarations: 0, flagged: 0, errors: 0, warnings: 0, info: 0 }
+      }
+      for (const key of Object.keys(counts)) {
+        merged.summary.bySurface[surface][key] += counts[key]
+      }
+    }
+  }
+  return merged
+}
+
+module.exports = { runRules, mergeResults, SEVERITIES }

package/tools/lint-strings/fixtures/connect/lint_connect.go

@@ -0,0 +1,67 @@
+// Package lintfixture is a lint-strings test fixture mirroring connect
+// ConfigSpec shapes. It only needs to parse as Go text for the scanner.
+package lintfixture
+
+import (
+	"github.com/redpanda-data/benthos/v4/public/service"
+)
+
+const (
+	// Field name constants resolve like the kfc* pattern in franz_client.go.
+	fixFieldSeedBrokers = "seed_brokers"
+	fixFieldClientID    = "client_id"
+
+	fixFieldSeedBrokersDescription = "A list of broker addresses to connect to in order to establish the connection."
+)
+
+func fixtureInputConfig() *service.ConfigSpec {
+	return service.NewConfigSpec().
+		Categories("Services").
+		Summary(`A fixture input using the https://example.com[example client library^].`).
+		Description(`
+When a consumer group is specified this input consumes one or more topics.
+
+This fixture exercises the ` + "`raw` + interpreted + `raw`" + ` concatenation idiom.
+
+== Metadata
+
+This heading and the table below are legitimate AsciiDoc:
+
+|===
+| kafka_key | The record key
+|===
+`).
+		Fields(fixtureConfigFields()...)
+}
+
+func fixtureConfigFields() []*service.ConfigField {
+	return []*service.ConfigField{
+		service.NewStringListField(fixFieldSeedBrokers).
+			Description(fixFieldSeedBrokersDescription + " When omitted the global block is referenced.").
+			Example([]string{"localhost:9092"}),
+		service.NewStringField(fixFieldClientID).
+			Description("An identifier for the client connection.").
+			Default("fixture").
+			Advanced(),
+		// Composite helper with built-in docs: never flagged.
+		service.NewTLSToggledField("tls"),
+		// Known-bad: a bare constructor with no Description ships blank.
+		service.NewStringField("naked_field").
+			Default(""),
+		// Known-bad: description merely restates the field name.
+		service.NewDurationField("poll_interval").
+			Description("Poll interval."),
+		// Deprecated fields are exempt from the missing-description rule.
+		service.NewStringField("old_token").Deprecated().Default(""),
+		// Dynamic description: skipped silently, never guessed at.
+		service.NewStringField("dynamic_field").
+			Description(dynamicDescription()),
+	}
+}
+
+func init() {
+	service.MustRegisterBatchInput("fixture_input", fixtureInputConfig(),
+		func(conf *service.ParsedConfig, mgr *service.Resources) (service.BatchInput, error) {
+			return nil, nil
+		})
+}

package/tools/lint-strings/fixtures/crd/crd-ref-docs-config.yaml

@@ -0,0 +1,15 @@
+# lint-strings test fixture mirroring operator/crd-ref-docs-config.yaml.
+processor:
+  ignoreTypes:
+  - 'List$'
+  - 'Deprecated.*$'
+  ignoreFields:
+  - 'migration$'
+  customMarkers:
+  - name: "hidefromdoc"
+    target: field
+  - name: "hidefromdoc"
+    target: type
+
+render:
+  kubernetesVersion: 1.28