@redpanda-data/docs-extensions-and-macros 5.46.0 → 5.47.1

package/bin/doc-tools.js

@@ -558,7 +558,15 @@ programCli
  * copy is a strict superset of the destination; otherwise it reports which
  * keys only the destination has and leaves the file alone (status
  * 'diverged') unless --force is passed. --check never writes, for a CI
- * gate.
+ * gate. A schema is also only synced into a repo that is plausibly its
+ * home: one that already has the schema, or that has the *.json the schema
+ * documents. Anything else is reported as 'not for this repo' and skipped,
+ * and never counts as drift. kapa-source-groups.json is the reason: it is
+ * generated into this package and read from node_modules by an Antora
+ * extension, so it never lives in a content repo at all, and planting its
+ * schema in redpanda-data/docs would leave a file describing data that repo
+ * will never have, with --check reporting its absence as drift on every run
+ * afterwards.
  * @example
  * # Sync into ./docs-data (writes any missing or out-of-date schema)
  * npx doc-tools sync-schemas
@@ -604,8 +612,13 @@ programCli
           created: '+ created',
           updated: '↻ updated',
           diverged: options.force ? '↻ updated (forced)' : '⚠ diverged, left alone',
+          'not-applicable': '- not for this repo',
         }[status]
         console.log(`  ${label}  ${name}`)
+        if (status === 'not-applicable') {
+          // Said out loud, because a silently missing schema looks like a bug.
+          console.log(`      no ${name.replace(/\.schema\.json$/, '.json')} here, so this schema has no data file to document`)
+        }
         if (status === 'diverged' && !options.force) {
           hasUnresolvedDivergence = true
           for (const p of destOnlyPaths) console.log(`      only in the destination: ${p}`)
@@ -2630,7 +2643,7 @@ validation
  * Validates docs-data/property-overrides.json against its JSON Schema:
  * unknown keys (a typo that would otherwise be silently dropped by the
  * extractor), and the see_also shape (a plain string, or an object naming
- * exactly one of cloud_only/self_hosted_only).
+ * exactly one of cloud_only/self_managed_only).
  *
  * @why
  * property-overrides.json has no catch-all pass-through when an override

package/cli-utils/sync-schemas.js

@@ -23,6 +23,16 @@ const { isDeepStrictEqual } = require('util')
  * 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`.
+ *
+ * Not every schema belongs in every content repo. kapa-source-groups.json is
+ * generated into THIS package and read from node_modules by an Antora
+ * extension, so it never lives in a content repo at all; copying its schema
+ * into redpanda-data/docs leaves a file describing data that repo will never
+ * have, and `check` mode then reports its absence as drift forever. So a
+ * schema is only synced into a destination that is plausibly its home: the
+ * destination already has the schema, or it has the *.json the schema
+ * documents. Anything else is reported as 'not-applicable' and does not count
+ * as drift.
  */
 
 const PACKAGE_SCHEMA_DIR = path.resolve(__dirname, '..', 'docs-data')
@@ -42,16 +52,27 @@ function listPackageSchemas () {
 /**
  * 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).
+ * doesn't". Most arrays are compared as opaque leaves: `required`/`enum`
+ * hold literal values, not named content, so there is nothing inside one to
+ * be "destination-only" in the sense this function cares about.
+ *
+ * `oneOf`/`anyOf`/`allOf` are the exception, and are recursed into by
+ * matching index. Those are JSON Schema's own combinators, and their array
+ * ELEMENTS are full schema objects that can carry real, named content --
+ * `see_also.items.oneOf[1].properties.cloud_only` is exactly the
+ * distinguishable content this function otherwise only looks for inside a
+ * plain object. Treating them as opaque like `required`/`enum` missed
+ * every audience flag living inside see_also's object variant, and would
+ * let a write-mode sync silently delete a destination-only flag added
+ * there, with no warning and no --force.
  *
  * @param {*} source
  * @param {*} dest
  * @param {string} [pathPrefix]
  * @returns {string[]} Dotted paths that exist in dest but not source.
  */
+const SCHEMA_COMBINATOR_KEYS = new Set(['oneOf', 'anyOf', 'allOf'])
+
 function findDestOnlyPaths (source, dest, pathPrefix = '') {
   if (
     dest === null || typeof dest !== 'object' || Array.isArray(dest) ||
@@ -67,11 +88,35 @@ function findDestOnlyPaths (source, dest, pathPrefix = '') {
       onlyInDest.push(keyPath)
       continue
     }
-    onlyInDest.push(...findDestOnlyPaths(source[key], destValue, keyPath))
+    const sourceValue = source[key]
+    if (SCHEMA_COMBINATOR_KEYS.has(key) && Array.isArray(destValue) && Array.isArray(sourceValue)) {
+      const length = Math.max(destValue.length, sourceValue.length)
+      for (let i = 0; i < length; i++) {
+        const itemPath = `${keyPath}[${i}]`
+        if (i >= sourceValue.length) {
+          onlyInDest.push(itemPath)
+          continue
+        }
+        onlyInDest.push(...findDestOnlyPaths(sourceValue[i], destValue[i], itemPath))
+      }
+      continue
+    }
+    onlyInDest.push(...findDestOnlyPaths(sourceValue, destValue, keyPath))
   }
   return onlyInDest
 }
 
+/**
+ * The docs-data file a schema documents: property-overrides.schema.json
+ * documents property-overrides.json.
+ *
+ * @param {string} schemaName - Bare schema filename.
+ * @returns {string} The data filename it documents.
+ */
+function dataFileFor (schemaName) {
+  return schemaName.replace(/\.schema\.json$/, '.json')
+}
+
 /**
  * Compare this package's schemas against the copies in a destination
  * directory (a content repo's docs-data/), and optionally write updates.
@@ -88,15 +133,18 @@ function findDestOnlyPaths (source, dest, pathPrefix = '') {
  *   destDir: string,
  *   results: Array<{
  *     name: string,
- *     status: ('created'|'updated'|'unchanged'|'diverged'),
+ *     status: ('created'|'updated'|'unchanged'|'diverged'|'not-applicable'),
  *     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.
+ * }} drift is true when any applicable 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. status 'not-applicable' means neither the schema nor the *.json it
+ *   documents is in the destination, so that schema does not belong there;
+ *   nothing is written and it never counts as drift.
  */
 function syncSchemas ({ destDir, check = false, force = false } = {}) {
   const resolvedDest = path.resolve(destDir || 'docs-data')
@@ -110,7 +158,13 @@ function syncSchemas ({ destDir, check = false, force = false } = {}) {
 
     let status
     let destOnlyPaths
-    if (!destExists) {
+    if (!destExists && !fs.existsSync(path.join(resolvedDest, dataFileFor(name)))) {
+      // Neither the schema nor the data file it documents is here, so this
+      // repo is not where that schema lives. Writing it would plant a file
+      // describing data this repo never has, and `check` would then call its
+      // absence drift on every run.
+      status = 'not-applicable'
+    } else if (!destExists) {
       status = 'created'
     } else {
       // Compare parsed content, not raw text — a destination reformatted by a
@@ -136,9 +190,9 @@ function syncSchemas ({ destDir, check = false, force = false } = {}) {
     return { name, status, sourcePath, destPath, ...(destOnlyPaths ? { destOnlyPaths } : {}) }
   })
 
-  const drift = results.some((r) => r.status !== 'unchanged')
+  const drift = results.some((r) => r.status !== 'unchanged' && r.status !== 'not-applicable')
 
   return { destDir: resolvedDest, results, drift }
 }
 
-module.exports = { listPackageSchemas, syncSchemas, findDestOnlyPaths, PACKAGE_SCHEMA_DIR }
+module.exports = { listPackageSchemas, syncSchemas, findDestOnlyPaths, dataFileFor, PACKAGE_SCHEMA_DIR }

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

@@ -7,8 +7,10 @@
   "properties": {
     "properties": {
       "type": "object",
-      "description": "Keyed by property key or name (see property_extractor.py's name-fallback lookup). An override key that matches neither creates a phantom stub property — see property_extractor.py's report_phantom_stubs().",
-      "additionalProperties": { "$ref": "#/$defs/propertyOverride" }
+      "description": "Keyed by property key or name (see property_extractor.py's name-fallback lookup). An override key that matches neither creates a phantom stub property \u2014 see property_extractor.py's report_phantom_stubs().",
+      "additionalProperties": {
+        "$ref": "#/$defs/propertyOverride"
+      }
     }
   },
   "additionalProperties": false,
@@ -21,10 +23,40 @@
           "type": "string",
           "description": "Free-text note to whoever edits this entry next. Never read by the generator."
         },
-        "description": { "type": "string" },
+        "description": {
+          "description": "Property description. A plain string, or an array of paragraphs when one of them belongs to a single docs build: an array entry may carry a 'cloud-only:' / 'self-managed-only:' prefix and the generator wraps it in the matching ifdef::env-cloud[] conditional. Prefer the array form over writing the conditional into the string, because the overrides audit can only compare prose it can separate from markup, so a hand-written conditional pins the override forever.",
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "string"
+              }
+            }
+          ]
+        },
+        "links": {
+          "type": "object",
+          "description": "Inline links, keyed by the literal text to find in the prose (backticks included, as written) and valued by the target. Only the first occurrence of a key is linked, and the longest key wins. Two target forms: '#<property_name>' emits a prop macro, which resolves the reference page itself and renders plain code in a build that does not publish the target, so it needs no conditional and cannot dangle; 'xref:<target>' emits a literal xref with the key as its link text; 'glossterm' wraps the key in a glossary tooltip (use 'glossterm:<Term>' when the prose says something other than the term's own name). A target may carry a 'cloud-only:' / 'self-managed-only:' prefix, in which case the containing paragraph is emitted twice: linked in that branch, plain in the other. Keeping links here rather than in the sentence is what lets the description stay prose the audit can compare against the source string.",
+          "additionalProperties": {
+            "type": "string",
+            "pattern": "^(?:(?:cloud-only|self-managed-only):\\s*)?(?:#[^\\s#]+|xref:[^\\s\\[\\]]+|glossterm(?::[^\\[\\]]+)?)$"
+          }
+        },
+        "includes": {
+          "description": "Shared partials pulled into this property's entry, as Antora resource IDs (for example reference:partial$internal-use-property.adoc). Rendered as include:: directives immediately after the description, which is where they used to be written by hand. Keeping them here rather than inside the description string is what lets the prose stay comparable to the source doc string. An entry may carry a 'cloud-only:' / 'self-managed-only:' prefix, and its own [attrs] if it needs them.",
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          }
+        },
         "upstream_ref": {
           "type": "string",
-          "description": "The upstream issue or PR (against the engineering repo whose defective string this description patches, either the short form 'redpanda-data/streaming-enterprise#12345' or the full URL) that will make this description override redundant once merged and released. A description override is a stopgap, not a fix: set this so the override is born with a retirement path, and remove both the override and this field once the fix ships. Only meaningful alongside 'description' — has no effect on generation or rendering."
+          "description": "The upstream issue or PR (against the engineering repo whose defective string this description patches, either the short form 'redpanda-data/streaming-enterprise#12345' or the full URL) that will make this description override redundant once merged and released. A description override is a stopgap, not a fix: set this so the override is born with a retirement path, and remove both the override and this field once the fix ships. Only meaningful alongside 'description' \u2014 has no effect on generation or rendering."
         },
         "version": {
           "type": "string",
@@ -33,17 +65,30 @@
         "example": {
           "description": "Literal example content, or an example_file/example_yaml reference resolved relative to this overrides file."
         },
-        "example_file": { "type": "string" },
-        "example_yaml": { "type": "string" },
+        "example_file": {
+          "type": "string"
+        },
+        "example_yaml": {
+          "type": "string"
+        },
         "default": {
-          "description": "Replaces the extracted default. Prefer leaving this unset — it silently pins a value the extractor would otherwise keep in sync with the C++ source on every release."
+          "description": "Replaces the extracted default. Prefer leaving this unset \u2014 it silently pins a value the extractor would otherwise keep in sync with the C++ source on every release."
+        },
+        "type": {
+          "type": "string"
         },
-        "type": { "type": "string" },
         "config_scope": {
-          "enum": ["cluster", "broker", "topic", null],
-          "description": "Almost always inferred automatically from defined_in — see property_extractor.py's add_config_scope(). Only set this for an override-created property (defined_in: 'override'), which has no source file to infer from."
+          "enum": [
+            "cluster",
+            "broker",
+            "topic",
+            null
+          ],
+          "description": "Almost always inferred automatically from defined_in \u2014 see property_extractor.py's add_config_scope(). Only set this for an override-created property (defined_in: 'override'), which has no source file to infer from."
+        },
+        "exclude_from_docs": {
+          "type": "boolean"
         },
-        "exclude_from_docs": { "type": "boolean" },
         "category": {
           "type": "string",
           "description": "Documentation grouping. Not inferable for cluster/broker properties; topic properties get a mechanical default from infer_category() that this can still override."
@@ -53,17 +98,23 @@
           "description": "Replaces the enum field to filter displayed values (e.g. hiding an internal-only mode).",
           "items": {}
         },
-        "is_deprecated": { "type": "boolean" },
-        "visibility": { "type": "string" },
+        "is_deprecated": {
+          "type": "boolean"
+        },
+        "visibility": {
+          "type": "string"
+        },
         "related_topics": {
           "type": "array",
           "deprecated": true,
-          "description": "Deprecated — use see_also. A plain string, or one prefixed 'cloud-only:'/'self-managed-only:' for conditional display. The prefix is free text with no validation; still read for existing entries, normalized alongside see_also by seeAlsoView.js.",
-          "items": { "type": "string" }
+          "description": "Deprecated \u2014 use see_also. A plain string, or one prefixed 'cloud-only:'/'self-managed-only:' for conditional display. The prefix is free text with no validation; still read for existing entries, normalized alongside see_also by seeAlsoView.js.",
+          "items": {
+            "type": "string"
+          }
         },
         "see_also": {
           "type": "array",
-          "description": "Related commands or documentation pages, in the docs-data/rpk-overrides.json 'seeAlso' shape. Each item is a plain string (shown everywhere) or an object naming exactly one of cloud_only/self_hosted_only (shown only in that build).",
+          "description": "Related commands or documentation pages. Each item is a plain string (shown everywhere) or an object naming exactly one of cloud_only/self_managed_only (shown only in that build). Same shape as rpk-overrides.json's 'seeAlso', except that file spells the flags in camelCase to match its own key style.",
           "items": {
             "oneOf": [
               {
@@ -79,24 +130,80 @@
                     "description": "The xref link or related-topic text."
                   },
                   "cloud_only": {
-                    "type": "boolean",
-                    "description": "If true, only shown in Cloud docs (wrapped with ifdef::env-cloud[])."
+                    "const": true,
+                    "description": "If true, only shown in Cloud docs (wrapped with ifdef::env-cloud[]). Only `true` is accepted: the emitters test for exactly true, so `false` behaves as if the key were absent while reading as though it meant the opposite audience. Omit the key instead."
                   },
                   "self_hosted_only": {
-                    "type": "boolean",
-                    "description": "If true, only shown in self-hosted docs (wrapped with ifndef::env-cloud[])."
+                    "const": true,
+                    "deprecated": true,
+                    "description": "Deprecated spelling of self_managed_only. Still read, so an override written against the older schema keeps working, but nothing emits it. Use self_managed_only. Only `true` is accepted: the emitters test for exactly true, so `false` behaves as if the key were absent while reading as though it meant the opposite audience. Omit the key instead."
+                  },
+                  "self_managed_only": {
+                    "const": true,
+                    "description": "If true, only shown in self-managed docs (wrapped with ifndef::env-cloud[]). Only `true` is accepted: the emitters test for exactly true, so `false` behaves as if the key were absent while reading as though it meant the opposite audience. Omit the key instead."
                   }
                 },
-                "required": ["content"],
+                "required": [
+                  "content"
+                ],
                 "additionalProperties": false,
                 "oneOf": [
                   {
-                    "required": ["cloud_only"],
-                    "not": { "required": ["self_hosted_only"] }
+                    "required": [
+                      "cloud_only"
+                    ],
+                    "not": {
+                      "anyOf": [
+                        {
+                          "required": [
+                            "self_managed_only"
+                          ]
+                        },
+                        {
+                          "required": [
+                            "self_hosted_only"
+                          ]
+                        }
+                      ]
+                    }
+                  },
+                  {
+                    "required": [
+                      "self_managed_only"
+                    ],
+                    "not": {
+                      "anyOf": [
+                        {
+                          "required": [
+                            "cloud_only"
+                          ]
+                        },
+                        {
+                          "required": [
+                            "self_hosted_only"
+                          ]
+                        }
+                      ]
+                    }
                   },
                   {
-                    "required": ["self_hosted_only"],
-                    "not": { "required": ["cloud_only"] }
+                    "required": [
+                      "self_hosted_only"
+                    ],
+                    "not": {
+                      "anyOf": [
+                        {
+                          "required": [
+                            "cloud_only"
+                          ]
+                        },
+                        {
+                          "required": [
+                            "self_managed_only"
+                          ]
+                        }
+                      ]
+                    }
                   }
                 ]
               }
@@ -108,14 +215,31 @@
           "description": "Structured NOTE/TIP/IMPORTANT/WARNING/CAUTION callouts, rendered as Asciidoctor admonition blocks instead of hand-written markup in description. Each entry needs type and text; title is optional. See property_extractor.py's _normalize_admonitions() -- an entry that doesn't match this shape is dropped with a warning, not rejected here, so the schema stays permissive on casing/whitespace that the generator itself normalizes.",
           "items": {
             "type": "object",
-            "required": ["type", "text"],
+            "required": [
+              "type",
+              "text"
+            ],
             "properties": {
               "type": {
                 "type": "string",
                 "description": "Case-insensitive; normalized to uppercase. One of note, tip, important, warning, caution.",
-                "enum": ["note", "tip", "important", "warning", "caution",
-                         "NOTE", "TIP", "IMPORTANT", "WARNING", "CAUTION",
-                         "Note", "Tip", "Important", "Warning", "Caution"]
+                "enum": [
+                  "note",
+                  "tip",
+                  "important",
+                  "warning",
+                  "caution",
+                  "NOTE",
+                  "TIP",
+                  "IMPORTANT",
+                  "WARNING",
+                  "CAUTION",
+                  "Note",
+                  "Tip",
+                  "Important",
+                  "Warning",
+                  "Caution"
+                ]
               },
               "text": {
                 "type": "string",
@@ -124,8 +248,57 @@
               "title": {
                 "type": "string",
                 "description": "Optional admonition title, shown in place of the default type label."
+              },
+              "cloud_only": {
+                "const": true,
+                "description": "Show this admonition only in the Cloud build (wrapped with ifdef::env-cloud[]). Only `true` is accepted: the emitters test for exactly true, so `false` behaves as if the key were absent while reading as though it meant the opposite audience. Omit the key instead."
+              },
+              "self_managed_only": {
+                "const": true,
+                "description": "Show this admonition only in the self-managed build (wrapped with ifndef::env-cloud[]). Only `true` is accepted: the emitters test for exactly true, so `false` behaves as if the key were absent while reading as though it meant the opposite audience. Omit the key instead."
+              },
+              "self_hosted_only": {
+                "const": true,
+                "deprecated": true,
+                "description": "Deprecated spelling of self_managed_only. Still read, so an override written against the older schema keeps working, but nothing emits it: the product is Self-Managed and the string prefix has always been 'self-managed-only:', so one concept was going by two words depending on whether you wrote it as a prefix or a boolean. Use self_managed_only. Only `true` is accepted: the emitters test for exactly true, so `false` behaves as if the key were absent while reading as though it meant the opposite audience. Omit the key instead."
               }
             },
+            "allOf": [
+              {
+                "not": {
+                  "$comment": "Setting both audiences would wrap the block in ifdef and ifndef at once, so it would render in neither build. Only an exact true counts, so cloud_only: false beside self_managed_only: true stays valid.",
+                  "properties": {
+                    "cloud_only": {
+                      "const": true
+                    },
+                    "self_managed_only": {
+                      "const": true
+                    }
+                  },
+                  "required": [
+                    "cloud_only",
+                    "self_managed_only"
+                  ]
+                }
+              },
+              {
+                "not": {
+                  "$comment": "Same check against the deprecated spelling.",
+                  "properties": {
+                    "cloud_only": {
+                      "const": true
+                    },
+                    "self_hosted_only": {
+                      "const": true
+                    }
+                  },
+                  "required": [
+                    "cloud_only",
+                    "self_hosted_only"
+                  ]
+                }
+              }
+            ],
             "additionalProperties": false
           }
         }

package/package.json

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

package/tools/overrides-audit/adapters/properties.js

@@ -41,6 +41,13 @@ function loadJson (filePath, label) {
  * REDUNDANT (the audit's normalization only widens equality, never narrows
  * it), so a violation indicates a classifier bug.
  *
+ * One exemption, not an exception to the rule: a description carrying
+ * audience-scoped paragraphs classifies KEEP even when its unconditional prose
+ * is raw-equal to source, because retiring it would delete the scoped
+ * paragraphs too. Those entries are compared on their unconditional prose --
+ * skipping them outright would quietly drop the array form out of the
+ * invariant's coverage.
+ *
  * @param {Object} extractedDoc - Extracted properties document.
  * @param {Object} overrides - Override entries map.
  * @param {Object[]} manifest - Classified manifest rows.
@@ -51,8 +58,11 @@ function crossCheckWithCompare (extractedDoc, overrides, manifest) {
   const overlaidProps = {}
   for (const [name, prop] of Object.entries(extractedProps)) {
     const override = overrides[name]
-    overlaidProps[name] = override && typeof override.description === 'string'
-      ? { ...prop, description: override.description }
+    const description = override && override.description !== undefined
+      ? classify.unconditionalProse(override.description).prose
+      : undefined
+    overlaidProps[name] = description !== undefined
+      ? { ...prop, description }
       : prop
   }
 
@@ -72,7 +82,8 @@ function crossCheckWithCompare (extractedDoc, overrides, manifest) {
       row.field === 'description' &&
       row.class !== classify.CLASSES.REDUNDANT &&
       overrides[row.name] &&
-      typeof overrides[row.name].description === 'string' &&
+      overrides[row.name].description !== undefined &&
+      classify.unconditionalProse(overrides[row.name].description).scoped === 0 &&
       extractedProps[row.name] &&
       !changedNames.has(row.name)
   )