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

package/bin/doc-tools.js

@@ -529,6 +529,103 @@ programCli
     }
   })
 
+/**
+ * @description Copy this package's docs-data/*.schema.json files into a
+ * content repo's own docs-data/ (the file that documents docs-data/x.json
+ * lives alongside x.json itself, so a writer can change both in one PR
+ * without waiting on a package release first). Run this after bumping
+ * @redpanda-data/docs-extensions-and-macros so the local copy picks up
+ * whatever changed upstream.
+ * @why Nothing keeps a content repo's schema copy in sync with this
+ * package's copy today, in either direction. A content repo's copy can
+ * legitimately be ahead of this package's (confirmed happening in
+ * practice: the docs repo's rpk-overrides.schema.json documents a real,
+ * working `asPartial` override field that this package's own copy is
+ * missing) — overwriting it in that case would delete real, correct
+ * documentation, not fix drift. This only overwrites when this package's
+ * 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.
+ * @example
+ * # Sync into ./docs-data (writes any missing or out-of-date schema)
+ * npx doc-tools sync-schemas
+ *
+ * # Report drift without writing -- exits 1 if anything is out of sync
+ * npx doc-tools sync-schemas --check
+ *
+ * # Sync into a non-default location
+ * npx doc-tools sync-schemas --dest path/to/docs-data
+ *
+ * # Overwrite even a destination that has diverged (rarely correct --
+ * # read the 'diverged' output first; it names what would be lost)
+ * npx doc-tools sync-schemas --force
+ * @requirements None.
+ */
+programCli
+  .command('sync-schemas')
+  .description("Sync this package's docs-data/*.schema.json into a content repo's docs-data/")
+  .option('--dest <path>', 'Destination docs-data directory', 'docs-data')
+  .option('--check', 'Report drift without writing; exit 1 if any schema is missing, out of date, or diverged')
+  .option('--force', 'Overwrite even a destination that has diverged (has content this package lacks)')
+  .action((options) => {
+    const { syncSchemas } = require('../cli-utils/sync-schemas')
+
+    try {
+      const { destDir, results, drift } = syncSchemas({
+        destDir: options.dest,
+        check: Boolean(options.check),
+        force: Boolean(options.force),
+      })
+
+      if (results.length === 0) {
+        console.log('No *.schema.json files found in this package to sync.')
+        process.exit(0)
+      }
+
+      console.log(`${options.check ? 'Checking' : 'Syncing'} against: ${destDir}`)
+      console.log('')
+      let hasUnresolvedDivergence = false
+      for (const { name, status, destOnlyPaths } of results) {
+        const label = {
+          unchanged: '✓ up to date',
+          created: '+ created',
+          updated: '↻ updated',
+          diverged: options.force ? '↻ updated (forced)' : '⚠ diverged, left alone',
+        }[status]
+        console.log(`  ${label}  ${name}`)
+        if (status === 'diverged' && !options.force) {
+          hasUnresolvedDivergence = true
+          for (const p of destOnlyPaths) console.log(`      only in the destination: ${p}`)
+        }
+      }
+      console.log('')
+
+      if (options.check) {
+        if (drift) {
+          const hint = hasUnresolvedDivergence
+            ? 'A diverged file needs a human decision (see paths above), not just a re-run.'
+            : 'Run `npx doc-tools sync-schemas` to fix.'
+          console.log(`✗ One or more schemas are out of date. ${hint}`)
+          process.exit(1)
+        }
+        console.log('✓ All schemas are in sync.')
+        process.exit(0)
+      }
+
+      if (hasUnresolvedDivergence) {
+        console.log('⚠ Synced what was safe to sync. One or more files diverged and were left alone -- see paths above. Re-run with --force only after confirming the destination-only content should be lost.')
+        process.exit(1)
+      }
+
+      console.log(drift ? '✓ Synced.' : '✓ Already in sync -- nothing to do.')
+      process.exit(0)
+    } catch (err) {
+      console.error(`Error: ${err.message}`)
+      process.exit(1)
+    }
+  })
+
 /**
  * @description Show MCP server version information including available tools
  * and optionally usage statistics from previous sessions.

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.14.0",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",