@redpanda-data/docs-extensions-and-macros 5.49.0 → 5.50.0

package/package.json

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

package/tools/lint-strings/index.js

@@ -116,7 +116,16 @@ function lintStrings (options) {
       // still exists at HEAD, in any touched file, was edited or moved, not
       // removed.
       const removedFiles = removedBySurface[surfaceName] ? [...removedBySurface[surfaceName].keys()] : []
-      const head = surface.extract({ repo: repoPath, files: new Set([...files.keys(), ...removedFiles]), log })
+      const touchedFiles = new Set([...files.keys(), ...removedFiles])
+      // A surface whose extraction covers the whole surface anyway (the
+      // properties extractor parses every config file on each run) supplies
+      // context from all of it, so a property in an untouched file that
+      // names, or is named by, a changed one is still on its page. Review
+      // scope stays the touched files either way.
+      const everything = surface.contextScope === 'surface' ? surface.extract({ repo: repoPath, log }) : null
+      const head = everything
+        ? everything.filter((d) => touchedFiles.has(d.file))
+        : surface.extract({ repo: repoPath, files: touchedFiles, log })
       headBySurface[surfaceName] = head
       const declarations = []
       for (const decl of head) {
@@ -128,7 +137,7 @@ function lintStrings (options) {
           continue
         }
         declarations.push(decl)
-        pending.push(pendingEntry(decl))
+        pending.push({ ...pendingEntry(decl), context: pageContext(decl, everything || head) })
       }
       results.push(runRules(declarations, rulesFor(surface), { skipRules, onlyRules }))
     }
@@ -186,6 +195,59 @@ function touches (decl, lineSet) {
   return spansOf(decl).some(([start, end]) => spanIntersects(start, end, lineSet))
 }
 
+const CONTEXT_LIMIT = 15
+const CONTEXT_STRING_LIMIT = 600
+
+/**
+ * The other strings a reader sees alongside this one, so a review can judge
+ * a string against its page rather than on its own: a flag's usage next to
+ * its command's Long text and examples, a property that names another
+ * property, the fields around an API field.
+ *
+ * - rpk: every other string declared in the same file, which is the
+ *   command's Short, Long and flags (rpk keeps one command per file).
+ * - api: the declarations nearest by line, which are the enclosing message
+ *   or rpc and its neighbors.
+ * - properties and metrics: declarations whose string names this one, or
+ *   that this string names, plus (metrics) its neighbors in the same group.
+ *
+ * Drawn from declarations already extracted for the diff, so it costs no
+ * extra extraction. Deterministic, capped, and order-stable.
+ */
+function pageContext (decl, all) {
+  const others = all.filter((d) => d !== decl && d.string != null)
+  const byDistance = (d) => Math.abs((d.line_start || 0) - (decl.line_start || 0))
+  const sameFile = others.filter((d) => d.file === decl.file)
+  let picked
+  if (decl.surface === 'rpk') {
+    // The command's Short and Long always, then the flags nearest this
+    // declaration, so a changed flag late in a long command keeps its
+    // neighbors when the cap applies. Shown in source order.
+    const isText = (d) => d.meta && (d.meta.kind === 'short' || d.meta.kind === 'long')
+    const text = sameFile.filter(isText)
+    const flags = sameFile.filter((d) => !isText(d)).sort((a, b) => byDistance(a) - byDistance(b))
+    picked = [...text, ...flags].slice(0, CONTEXT_LIMIT)
+      .sort((a, b) => (a.line_start || 0) - (b.line_start || 0))
+  } else if (decl.surface === 'api') {
+    picked = sameFile.sort((a, b) => byDistance(a) - byDistance(b)).slice(0, 6)
+  } else {
+    const mentions = (text, name) => Boolean(text && name) &&
+      new RegExp(`(^|[^A-Za-z0-9_])${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}($|[^A-Za-z0-9_])`).test(text)
+    const related = others.filter((d) => mentions(d.string, decl.name) || mentions(decl.string, d.name))
+    const neighbors = decl.surface === 'metrics'
+      ? sameFile.filter((d) => !related.includes(d)).sort((a, b) => byDistance(a) - byDistance(b)).slice(0, 2)
+      : []
+    picked = [...related, ...neighbors]
+  }
+  return picked.slice(0, CONTEXT_LIMIT).map((d) => ({
+    name: d.name,
+    kind: (d.meta && d.meta.kind) || d.surface,
+    file: d.file,
+    line_start: d.line_start,
+    string: d.string.length > CONTEXT_STRING_LIMIT ? `${d.string.slice(0, CONTEXT_STRING_LIMIT)}...` : d.string
+  }))
+}
+
 /**
  * Stable identity for one version of one doc string. A PR review records the
  * fingerprints it has seen, and a later push skips any declaration whose
@@ -467,7 +529,7 @@ function runCli (options) {
   process.exitCode = options.strict && result.summary.errors > 0 ? 1 : 0
 }
 
-module.exports = { lintStrings, formatHuman, runCli, SURFACES, rulesFor, fingerprint, readFingerprints }
+module.exports = { lintStrings, formatHuman, runCli, SURFACES, rulesFor, fingerprint, readFingerprints, pageContext }
 
 // Direct usage: node tools/lint-strings --repo <path> [--surface a,b]
 //   [--diff <base>] [--format json|human] [--strict]

package/tools/lint-strings/rules/common.js

@@ -100,7 +100,9 @@ function maskNonProse (text) {
 const CODE_TOKEN_PATTERNS = Object.freeze([
   { id: 'identifier', re: /\b[a-z][a-z0-9]*(?:_[a-z0-9]+)+\b/g },
   { id: 'flag', re: /(?<![\w-])--[a-z][a-z0-9]*(?:-[a-z0-9]+)*\b/g },
-  { id: 'path', re: /(?<![\w/])\/[a-z][a-zA-Z0-9_.-]*(?:\/[a-zA-Z0-9_.{}-]+)+\/?/g }
+  // A path may not end in a period, so "served from /v1/brokers." reports
+  // `/v1/brokers`, not the sentence's full stop with it.
+  { id: 'path', re: /(?<![\w/])\/[a-z][a-zA-Z0-9_.-]*(?:\/[a-zA-Z0-9_.{}-]*[a-zA-Z0-9_{}-])+\/?/g }
 ])
 
 /**
@@ -276,7 +278,12 @@ const COMMON_RULES = [
     description: 'Code value or field name in prose without inline code',
     severity: 'warning',
     check: (decl) => {
-      const bare = findBareCodeTokens(decl.string, decl.name)
+      // A surface whose generator formats some code values itself declares
+      // which (convention.auto_inline_code); those are not findings there.
+      const auto = (decl.convention && decl.convention.auto_inline_code) || null
+      const bare = findBareCodeTokens(decl.string, decl.name).filter((b) => !auto ||
+        !((auto.kinds || []).includes(b.kind) ||
+          (b.kind === 'path' && (auto.path_prefixes || []).some((prefix) => b.token.startsWith(prefix)))))
       if (bare.length === 0) return []
       const list = bare.map((b) => `\`${b.token}\``).join(', ')
       return [{

package/tools/lint-strings/surfaces/properties.js

@@ -245,6 +245,9 @@ module.exports = {
   // The extractor pairs each .cc with its .h, so a merge-base extraction needs
   // the whole directory, not only the files that lost lines.
   baseScope: 'directory',
+  // extract() runs the extractor over the whole repo and filters after, so
+  // page context can use every property at no extra cost.
+  contextScope: 'surface',
   convention: CONVENTION,
   extract,
   mapExtractorJson,

package/tools/lint-strings/surfaces/rpk.js

@@ -37,7 +37,15 @@ const CONVENTION = {
   case: 'sentence',
   terminal_period: false,
   verbatim_asciidoc: false,
-  transformer: 'formatDescription'
+  transformer: 'formatDescription',
+  // Code values formatDescription wraps in inline code by itself, so a bare
+  // one in the source is not a finding. Long is a Go raw string and cannot
+  // hold a backtick at all, which is why the generator does this. Keep in
+  // step with the auto-backtick passes in tools/rpk-docs/generate-rpk-docs.js.
+  auto_inline_code: {
+    kinds: ['flag'],
+    path_prefixes: ['/etc/', '/var/', '/usr/', '/home/', '/tmp/', '~/.']
+  }
 }
 
 // Composite literal only: gofmt writes `cobra.Command{` with no space, while

package/tools/property-extractor/README.adoc

@@ -1231,7 +1231,12 @@ breaks. Two files feed it, both mirrors of the `docs` repo:
 fields the rendering and link layers read. `cloud_supported` is the point: it is what
 makes the "no Cloud link to a property Cloud does not publish" assertion real rather
 than assumed. Descriptions are deliberately absent, because the corpus test drives prose from
-the overrides file, and a full copy would be 695 KB of text that rots.
+the overrides file, and a full copy would be 695 KB of text that rots. The exceptions are
+overrides that act on the source description instead of replacing it: links with no prose of
+their own, which apply to the source description, and includes with no description of their
+own, which the generator appends to it. The snapshot keeps the source description for those
+properties. `.github/scripts/derive-property-snapshot.js` makes that call from the overrides
+file, and both the recipe below and `property-corpus-drift.sh` use it.
 
 Keep the overrides copy a faithful mirror. It previously doubled as
 `property-docs-overrides.test.js`'s fixture, someone hand-edited an `admin` entry into
@@ -1264,17 +1269,13 @@ TAG="$(git -C "$DOCS" ls-tree origin/main --name-only -- modules/reference/attac
 echo "Refreshing against $TAG"
 
 git -C "$DOCS" show "origin/main:modules/reference/attachments/redpanda-properties-${TAG}.json" \
+  > /tmp/redpanda-properties.json
+node .github/scripts/derive-property-snapshot.js /tmp/redpanda-properties.json \
+  __tests__/docs-data/property-overrides.json \
   | node -e '
     const fs = require("fs");
-    const src = JSON.parse(fs.readFileSync(0, "utf8"));
-    const keep = ["name","config_scope","type","cloud_supported","cloud_editable",
-                  "cloud_readonly","cloud_byoc_only","is_deprecated","nullable"];
-    const properties = {};
-    for (const [k, v] of Object.entries(src.properties || {})) {
-      properties[k] = Object.fromEntries(keep.filter((f) => f in v).map((f) => [f, v[f]]));
-    }
     const out = JSON.parse(fs.readFileSync("__tests__/docs-data/property-snapshot.json", "utf8"));
-    out.properties = properties;
+    out.properties = JSON.parse(fs.readFileSync(0, "utf8"));
     out.source_tag = process.argv[1];
     fs.writeFileSync("__tests__/docs-data/property-snapshot.json", JSON.stringify(out, null, 1) + "\n");
   ' "$TAG"

package/tools/rpk-docs/generate-rpk-docs.js

@@ -1569,6 +1569,26 @@ function formatDescription(desc, customTransformations = null, options = {}) {
     return placeholder
   })
 
+  // Bare URLs become inline code: endpoints (http://localhost:9644) and links
+  // alike are code values, and an unformatted URL in help prose reads as
+  // broken markup. Not trailing sentence punctuation, and not a URL that is
+  // already an AsciiDoc link macro (url[text]), which backticks would break.
+  //
+  // Protected as a placeholder straight away, before any other pass runs.
+  // Every later pass matches inside a URL it does not know is one: the path
+  // passes backticked /tmp/file out of https://host/tmp/file, the short-flag
+  // pass took -a out of /foo-a/, and the issue-reference pass rewrote #NNNN
+  // anchors into link macros.
+  protectedDesc = protectedDesc.replace(/(?<![`\w/]|\]\()https?:\/\/[^\s`<>"'()[\]]+/g, (url, offset, whole) => {
+    if (whole[offset + url.length] === '[') return url // AsciiDoc link macro
+    const trail = url.match(/[.,;:!?]+$/)
+    const core = trail ? url.slice(0, -trail[0].length) : url
+    if (core.length <= 'https://'.length) return url
+    const placeholder = `__INLINE_CODE_${inlineCode.length}__`
+    inlineCode.push(`\`${decodeHtmlEntities(core)}\``)
+    return placeholder + (trail ? trail[0] : '')
+  })
+
   // Known top-level rpk subcommands (for accurate command detection)
   const rpkSubcommands = new Set([
     'ai', 'check', 'cloud', 'cluster', 'connect', 'container', 'debug',
@@ -1713,6 +1733,17 @@ function formatDescription(desc, customTransformations = null, options = {}) {
   }).join('`')
   result = result.replace(/(?<!`|-)(-[a-zA-Z])(?![a-zA-Z-])/g, '`$1`')
 
+  // A bare command followed by its flags ("run rpk topic list -r") is one
+  // command, but the passes above wrap the command path and each flag
+  // separately. Merge flag spans into the command span before them:
+  // `rpk topic list` `-r` -> `rpk topic list -r`. The quoted form never
+  // splits, because its whole span is protected before flags are wrapped.
+  let merged
+  do {
+    merged = result
+    result = result.replace(/`(rpk(?: [a-z][-a-z0-9]*)+(?: -{1,2}[a-zA-Z][-a-zA-Z0-9]*)*)` `(-{1,2}[a-zA-Z][-a-zA-Z0-9]*)`/g, '`$1 $2`')
+  } while (result !== merged)
+
   // Add backticks around environment variables
   result = result.replace(/(?<!`)(\$[A-Z_][A-Z0-9_]*)/g, '`$1`')
 
@@ -1729,12 +1760,15 @@ function formatDescription(desc, customTransformations = null, options = {}) {
   result = result.replace(/`(\$[A-Z_][A-Z0-9_]*)`(\/(?:[^\s`]*[^\s`).,;:!?])?)/g, '`$1$2`')
 
   // Add backticks around file paths (but not if already backticked)
-  // Must check both the slash and the path aren't already inside backticks
-  result = result.replace(/(?<![`/])(\/(?:etc|var|usr|home|tmp)\/[^\s,)`]+)/g, '`$1`')
-  result = result.replace(/(?<![`/])((?:etc|var|usr|home|tmp)\/[^\s,)`]+)/g, '`$1`')
+  // Must check both the slash and the path aren't already inside backticks.
+  // Like the $HOME merge above, a path may not END in sentence punctuation,
+  // so "...in ~/.config/rpk/rpk.yaml." puts the period outside the span
+  // instead of publishing `~/.config/rpk/rpk.yaml.`.
+  result = result.replace(/(?<![`/])(\/(?:etc|var|usr|home|tmp)\/(?:[^\s,)`]*[^\s,)`.;:!?])?)/g, '`$1`')
+  result = result.replace(/(?<![`/])((?:etc|var|usr|home|tmp)\/(?:[^\s,)`]*[^\s,)`.;:!?])?)/g, '`$1`')
 
   // Add backticks around home directory paths (~/.bashrc, ~/.zshrc, ~/.config/...)
-  result = result.replace(/(?<![`\w])(~\/\.[^\s,;:)`]+)/g, '`$1`')
+  result = result.replace(/(?<![`\w])(~\/\.(?:[^\s,;:)`]*[^\s,;:)`.!?])?)/g, '`$1`')
 
   // Add backticks around common package names
   result = result.replace(/(?<![`\w-])(bash-completion)(?![`\w-])/g, '`$1`')