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

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

@@ -0,0 +1,117 @@
+/**
+ * Overrides Audit - Properties Adapter
+ *
+ * Reads docs-data/property-overrides.json and an extracted-properties JSON
+ * (the property extractor's raw --output, WITHOUT overrides applied) and
+ * classifies every override field. This is the complete reference adapter;
+ * rpk and connect adapters follow the same shape.
+ */
+
+'use strict'
+
+const fs = require('fs')
+const classify = require('../classify')
+const { compareProperties } = require('../../property-extractor/compare-properties')
+
+/**
+ * Load and parse a JSON file with a helpful error message.
+ *
+ * @param {string} filePath - Path to the JSON file.
+ * @param {string} label - Human label for error messages.
+ * @returns {Object} Parsed JSON.
+ */
+function loadJson (filePath, label) {
+  let raw
+  try {
+    raw = fs.readFileSync(filePath, 'utf8')
+  } catch (err) {
+    throw new Error(`Cannot read ${label} file at ${filePath}: ${err.message}`)
+  }
+  try {
+    return JSON.parse(raw)
+  } catch (err) {
+    throw new Error(`Invalid JSON in ${label} file ${filePath}: ${err.message}`)
+  }
+}
+
+/**
+ * Cross-check the audit with compare-properties.js: overlay the override
+ * descriptions onto a copy of the extracted properties and diff the two.
+ * Every description the raw diff reports as unchanged must have classified
+ * REDUNDANT (the audit's normalization only widens equality, never narrows
+ * it), so a violation indicates a classifier bug.
+ *
+ * @param {Object} extractedDoc - Extracted properties document.
+ * @param {Object} overrides - Override entries map.
+ * @param {Object[]} manifest - Classified manifest rows.
+ * @returns {Object} { changedDescriptions, emptyDescriptions, violations }.
+ */
+function crossCheckWithCompare (extractedDoc, overrides, manifest) {
+  const extractedProps = (extractedDoc && extractedDoc.properties) || {}
+  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 }
+      : prop
+  }
+
+  const report = compareProperties(
+    { properties: extractedProps },
+    { properties: overlaidProps },
+    'source',
+    'source+overrides'
+  )
+
+  // Normalization-only differences legitimately appear "changed" in the raw
+  // diff while classifying REDUNDANT. The inverse can never happen: a
+  // raw-equal description that did not classify REDUNDANT is a classifier bug.
+  const changedNames = new Set(report.changedDescriptions.map((entry) => entry.name))
+  const violations = manifest.filter(
+    (row) =>
+      row.field === 'description' &&
+      row.class !== classify.CLASSES.REDUNDANT &&
+      overrides[row.name] &&
+      typeof overrides[row.name].description === 'string' &&
+      extractedProps[row.name] &&
+      !changedNames.has(row.name)
+  )
+
+  return {
+    changedDescriptions: report.changedDescriptions.length,
+    emptyDescriptions: report.emptyDescriptions.length,
+    violations: violations.map((row) => row.name)
+  }
+}
+
+/**
+ * Run the audit for the properties surface.
+ *
+ * @param {Object} args - { overridesPath, extractedPath, attrAllowlist }.
+ * @returns {Object} { surface, manifest, summary, cross_check }.
+ */
+function audit ({ overridesPath, extractedPath, attrAllowlist }) {
+  const overridesDoc = loadJson(overridesPath, 'overrides')
+  const extractedDoc = loadJson(extractedPath, 'extracted properties')
+
+  if (!overridesDoc.properties || typeof overridesDoc.properties !== 'object') {
+    throw new Error(`Overrides file ${overridesPath} has no top-level "properties" object`)
+  }
+  if (!extractedDoc.properties || typeof extractedDoc.properties !== 'object') {
+    throw new Error(`Extracted file ${extractedPath} has no top-level "properties" object; pass the property extractor's JSON output`)
+  }
+
+  const { manifest, summary } = classify.classifyProperties(overridesDoc, extractedDoc, { attrAllowlist })
+  const crossCheck = crossCheckWithCompare(extractedDoc, overridesDoc.properties, manifest)
+
+  return {
+    surface: 'properties',
+    overrides_file: overridesPath,
+    extracted_file: extractedPath,
+    manifest,
+    summary,
+    cross_check: crossCheck
+  }
+}
+
+module.exports = { audit, loadJson }

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

@@ -0,0 +1,192 @@
+/**
+ * Overrides Audit - rpk Adapter (structural)
+ *
+ * Reads docs-data/rpk-overrides.json (schema: docs-data/rpk-overrides.schema.json)
+ * and enumerates every override unit per command:
+ * - command `description` and `flags.<flag>.description` are the
+ *   upstreamable prose fields (rpk cobra Short/Long and flag usage strings)
+ * - everything else (seeAlso, pageAliases, introducedInVersion, platforms,
+ *   selfHostedOnly, pageAttributes, $refs, _note, content, prerequisites,
+ *   descriptionScope, appendToDescription, exclude, asPartial) is docs-site
+ *   structure that stays in the override layer by design.
+ *
+ * TODO(quality logic): source comparison for rpk descriptions is deferred.
+ * Two blockers, both known:
+ * 1. The versioned rpk-v<ver>.json files in docs repos are POST-override
+ *    snapshots (rpk-docs generation applies rpk-overrides.json before
+ *    writing them), so auditing against them classifies every override
+ *    REDUNDANT. The audit needs a raw `rpk --print-tree` snapshot instead.
+ * 2. Generated docs pass source strings through formatDescription()
+ *    (tools/rpk-docs/generate-rpk-docs.js) — ~40 regex passes (md->adoc,
+ *    auto-backticking, ensurePeriod, ...). Equality must be computed on
+ *    formatDescription(source) vs the override, not on the raw cobra string,
+ *    or near-identical strings will misclassify as UPSTREAMABLE.
+ * Until then, prose fields classify REVIEW with an explicit note, and
+ * docs-structure fields classify KEEP, so the manifest shape is already
+ * stable for the retirement workflow.
+ */
+
+'use strict'
+
+const classify = require('../classify')
+const { loadJson } = require('./properties')
+
+// Top-level keys of rpk-overrides.json that are not command entries.
+const NON_COMMAND_KEYS = ['$schema', '_notes', 'textTransformations', 'definitions']
+
+// Per-command fields that stay in the override layer by design.
+const KEEP_BY_DESIGN_FIELDS = [
+  'seeAlso',
+  'pageAliases',
+  'introducedInVersion',
+  'platforms',
+  'selfHostedOnly',
+  'pageAttributes',
+  '$refs',
+  '_note',
+  'content',
+  'prerequisites',
+  'descriptionScope',
+  'appendToDescription',
+  'exclude',
+  'asPartial'
+]
+
+/**
+ * Find a command node in an extracted `rpk --print-tree` JSON by its full
+ * name (for example "rpk topic create").
+ *
+ * @param {Object} tree - Root tree node ({ name, commands: [...] }).
+ * @param {string} fullName - Space-separated command path.
+ * @returns {Object|null} The command node, or null when absent.
+ */
+function findCommandNode (tree, fullName) {
+  if (!tree || typeof tree !== 'object') return null
+  const parts = fullName.trim().split(/\s+/)
+  if (parts[0] !== tree.name) return null
+  let node = tree
+  for (const part of parts.slice(1)) {
+    const children = Array.isArray(node.commands) ? node.commands : []
+    node = children.find((child) => child && child.name === part) || null
+    if (!node) return null
+  }
+  return node
+}
+
+/**
+ * Build the manifest row for an rpk prose field (deferred quality logic).
+ *
+ * @param {string} name - Unit name ("rpk topic create" or "rpk topic create --partitions").
+ * @param {string} field - Manifest field label.
+ * @param {string} text - Override description text.
+ * @param {Object|undefined} upstreamRef - upstream_ref carried from the override.
+ * @param {boolean|null} foundInTree - Whether the command exists in the extracted tree (null when no tree given).
+ * @returns {Object} Manifest row.
+ */
+function proseRow (name, field, text, upstreamRef, foundInTree) {
+  const row = {
+    name,
+    field,
+    class: classify.CLASSES.REVIEW,
+    content_hash: classify.contentHash(name, text)
+  }
+  if (upstreamRef !== undefined) row.upstream_ref = upstreamRef
+  if (foundInTree === false) {
+    row.note = 'Command not found in the extracted rpk tree; the override may be stale. TODO: rpk source comparison not implemented yet.'
+  } else {
+    row.note = 'TODO: rpk source comparison not implemented yet (needs a raw pre-override --print-tree snapshot and the formatDescription() pipeline).'
+  }
+  return row
+}
+
+/**
+ * Run the audit for the rpk surface (structural pass).
+ *
+ * @param {Object} args - { overridesPath, extractedPath }.
+ * @returns {Object} { surface, manifest, summary }.
+ */
+function audit ({ overridesPath, extractedPath }) {
+  const overridesDoc = loadJson(overridesPath, 'rpk overrides')
+  const commands = overridesDoc.commands
+  if (!commands || typeof commands !== 'object') {
+    throw new Error(`rpk overrides file ${overridesPath} has no top-level "commands" object`)
+  }
+
+  let tree = null
+  if (extractedPath) {
+    const extractedDoc = loadJson(extractedPath, 'extracted rpk tree')
+    tree = extractedDoc.raw_tree || extractedDoc.tree || null
+  }
+
+  const manifest = []
+  for (const [commandName, entry] of Object.entries(commands)) {
+    if (typeof entry !== 'object' || entry === null) continue
+
+    const node = tree ? findCommandNode(tree, commandName) : null
+    const foundInTree = tree ? node !== null : null
+
+    for (const [field, value] of Object.entries(entry)) {
+      if (field === 'description') {
+        manifest.push(proseRow(commandName, 'description', value, entry.upstream_ref, foundInTree))
+      } else if (field === 'flags' && value && typeof value === 'object') {
+        for (const [flagName, flagEntry] of Object.entries(value)) {
+          if (flagEntry && typeof flagEntry.description === 'string') {
+            manifest.push(proseRow(
+              `${commandName} --${flagName}`,
+              'flags.description',
+              flagEntry.description,
+              flagEntry.upstream_ref,
+              foundInTree
+            ))
+          }
+        }
+      } else if (field === 'upstream_ref' || field === '_comment') {
+        // Meta fields; upstream_ref is carried onto the prose rows above.
+      } else if (KEEP_BY_DESIGN_FIELDS.includes(field)) {
+        manifest.push({
+          name: commandName,
+          field,
+          class: classify.CLASSES.KEEP,
+          note: 'Docs-site structure; stays in the rpk override file by design.'
+        })
+      } else {
+        manifest.push({
+          name: commandName,
+          field,
+          class: classify.CLASSES.KEEP,
+          note: `Unrecognized rpk override field '${field}'; kept, verify it against docs-data/rpk-overrides.schema.json.`
+        })
+      }
+    }
+  }
+
+  // Shared flag definitions referenced via $refs also carry descriptions.
+  // Shape: definitions.<def-name>.<flag-name>.description
+  const definitions = overridesDoc.definitions
+  if (definitions && typeof definitions === 'object') {
+    for (const [defName, flags] of Object.entries(definitions)) {
+      if (!flags || typeof flags !== 'object') continue
+      for (const [flagName, flagEntry] of Object.entries(flags)) {
+        if (flagEntry && typeof flagEntry.description === 'string') {
+          manifest.push(proseRow(
+            `definitions/${defName} --${flagName}`,
+            'flags.description',
+            flagEntry.description,
+            flagEntry.upstream_ref,
+            null
+          ))
+        }
+      }
+    }
+  }
+
+  return {
+    surface: 'rpk',
+    overrides_file: overridesPath,
+    extracted_file: extractedPath || null,
+    manifest,
+    summary: classify.summarize(manifest)
+  }
+}
+
+module.exports = { audit, findCommandNode, NON_COMMAND_KEYS }