@redpanda-data/docs-extensions-and-macros 5.31.0 → 5.35.0

package/bin/doc-tools-mcp.js

@@ -446,7 +446,7 @@ const tools = [
         },
         surface: {
           type: 'string',
-          description: 'Comma-separated surfaces to lint: properties, metrics, rpk, helm, crd, connect (optional, defaults to all)'
+          description: `Comma-separated surfaces to lint: ${Object.keys(require('../tools/lint-strings').SURFACES).join(', ')} (optional, defaults to all)`
         },
         diff: {
           type: 'string',

package/bin/doc-tools.js

@@ -2622,7 +2622,9 @@ programCli
   .command('lint-strings')
   .description('Lint user-facing doc strings embedded in engineering source code (properties, metrics, ...)')
   .requiredOption('--repo <path>', 'Path to an existing engineering checkout (for example, a local redpanda clone). Nothing is cloned.')
-  .option('--surface <list>', 'Comma-separated surfaces to lint (default: all registered). Registered: properties, metrics, rpk, helm, crd, connect')
+  // Read off the registry rather than restated here: a hardcoded list silently
+  // went stale the moment a surface was added.
+  .option('--surface <list>', `Comma-separated surfaces to lint (default: all registered). Registered: ${Object.keys(require('../tools/lint-strings').SURFACES).join(', ')}`)
   .option('--diff <base>', 'Declaration-anchored diff mode: lint only declarations whose full span intersects lines changed in <base>...HEAD')
   .option('--format <format>', 'Output format: human or json', 'human')
   .option('--skip-rules <list>', 'Comma-separated rule ids to skip')

package/bin/mcp-tools/lint-doc-strings.js

@@ -16,7 +16,8 @@ const DOC_TOOLS_BIN = path.resolve(__dirname, '..', 'doc-tools.js');
  * Lint user-facing doc strings embedded in engineering source code
  * @param {Object} args - Arguments
  * @param {string} args.repo - Path to the engineering checkout (required)
- * @param {string} [args.surface] - Comma-separated surfaces (properties, metrics, rpk, helm, crd, connect)
+ * @param {string} [args.surface] - Comma-separated surfaces; see the SURFACES
+ *   registry in tools/lint-strings/index.js for the current list
  * @param {string} [args.diff] - Base ref for declaration-anchored diff mode
  * @param {string} [args.skip_rules] - Comma-separated rule ids to skip
  * @param {string} [args.only_rules] - Comma-separated rule ids to run exclusively

package/package.json

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

package/tools/lint-strings/diff.js

@@ -26,7 +26,21 @@ const SURFACE_ROUTES = [
   // console) and charts/<name>/values.yaml (connectors).
   { surface: 'helm', pattern: /^charts\/[^/]+\/(chart\/)?values\.yaml$/ },
   { surface: 'crd', pattern: /^operator\/api\// },
-  { surface: 'connect', pattern: /^internal\/impl\// }
+  { surface: 'connect', pattern: /^internal\/impl\// },
+  // API protos, whose comments and openapiv2 option strings reach readers as
+  // OpenAPI descriptions. console holds the data plane and Console APIs under
+  // proto/redpanda/api/; cloudv2's control plane lives under proto/public/.
+  // Anchored on the api/ segment so cloudv2's proto/descriptors/ tree (private
+  // and internal) and every vendored proto/public/**/wellknown/ path stay out.
+  { surface: 'api', pattern: /^proto\/(?:redpanda\/api|public\/[^/]+\/redpanda\/api)\/.*\.proto$/ },
+  // Admin API v2, in the redpanda/streaming-enterprise repo. A different
+  // generator (protoc-gen-connect-openapi) and a third string form; see
+  // surfaces/api.js. These two directories are exactly what the api-docs
+  // bundler feeds into the published spec (tools/bundle-openapi.js):
+  // `admin/internal` and `core/testing` are excluded by that repo's buf.yaml
+  // and generate nothing, and `core/rest` generates a fragment that is never
+  // bundled, so none of them reach readers.
+  { surface: 'api', pattern: /^proto\/redpanda\/core\/(?:admin\/v2|common)\/.*\.proto$/ }
 ]
 
 /**

package/tools/lint-strings/fixtures/api/lint_admin_v2.proto

@@ -0,0 +1,114 @@
+// Copyright 2026 Redpanda Data, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+//
+// A license header is a leading comment on nothing. It must not attach itself
+// to the first declaration in the file.
+
+syntax = "proto3";
+
+package redpanda.core.admin.v2;
+
+import "proto/redpanda/core/pbgen/rpc.proto";
+
+option (pbgen.cpp_namespace) = "proto::fixture";
+
+service FixtureService {
+    // GetFixture
+    //
+    // Returns a single fixture.
+    rpc GetFixture(GetFixtureRequest) returns (GetFixtureResponse) {
+        option (pbgen.rpc) = {
+            authz: SUPERUSER
+        };
+    }
+
+    // CreateFixture
+    //
+    // Creates a fixture. The description can run over several comment
+    // lines, and the resolved prose joins them.
+    //
+    // A blank comment line inside the description is a paragraph break and
+    // stays part of the description.
+    rpc CreateFixture(CreateFixtureRequest)
+        returns (CreateFixtureResponse) {
+        option (pbgen.rpc) = {
+            authz: SUPERUSER
+        };
+    }
+
+    // Reports the collapsed case: with no blank line the generator uses this
+    // whole comment as BOTH the summary and the description, so the API
+    // reference's nav item becomes a paragraph.
+    rpc CollapsedFixture(CollapsedFixtureRequest)
+        returns (CollapsedFixtureResponse) {
+        option (pbgen.rpc) = {
+            authz: SUPERUSER
+        };
+    }
+
+    // DeleteFixture.
+    //
+    // Deletes a fixture.
+    rpc DeleteFixture(DeleteFixtureRequest) returns (DeleteFixtureResponse) {
+        option (pbgen.rpc) = {
+            authz: SUPERUSER
+        };
+    }
+
+    // ListFixtures
+    // over two lines
+    //
+    // Lists every fixture.
+    rpc ListFixtures(ListFixturesRequest) returns (ListFixturesResponse) {
+        option (pbgen.rpc) = {
+            authz: SUPERUSER
+        };
+    }
+
+    // BodylessFixture
+    //
+    // A body-less rpc opens no block, so it must not swallow the
+    // declarations that follow it.
+    rpc BodylessFixture(BodylessFixtureRequest) returns (BodylessFixtureResponse);
+
+    // WatchFixture
+    //
+    // Confirms the rpc after a body-less one is still found.
+    rpc WatchFixture(WatchFixtureRequest) returns (WatchFixtureResponse) {
+        option (pbgen.rpc) = {
+            authz: SUPERUSER
+        };
+    }
+}
+
+// The request for a single fixture.
+message GetFixtureRequest {
+    // The node ID for the fixture. If unset, the broker handling the RPC
+    // returns information about itself.
+    optional int32 node_id = 1;
+
+    // Fixture name
+    string name = 2;
+
+    int32 undocumented = 3;
+
+    // Partition ID
+    int32 partition_id = 4;
+
+    // The protocol versions the fixture supports. See
+    // https://kafka.apache.org/protocol.html#protocol_compatibility
+    repeated int32 api_versions = 5;
+}
+
+// Fixture mode
+//
+// - Not specified
+// - Runs fast
+enum FixtureMode {
+    FIXTURE_MODE_UNSPECIFIED = 0;
+    // Per-value comments are discarded by protoc-gen-connect-openapi, so they
+    // are not extracted and must not be reported as declarations.
+    FIXTURE_MODE_FAST = 1;
+}

package/tools/lint-strings/fixtures/api/lint_api.proto

@@ -0,0 +1,123 @@
+syntax = "proto3";
+
+package redpanda.api.fixture.v1;
+
+import "google/protobuf/descriptor.proto";
+import "protoc-gen-openapiv2/options/annotations.proto";
+
+// Extension fields are wire metadata, never published schema. The field
+// inside this block must not be extracted.
+extend google.protobuf.MethodOptions {
+  string fixture_extension = 60002;
+}
+
+// FixtureMode selects how the fixture behaves.
+enum FixtureMode {
+  FIXTURE_MODE_UNSPECIFIED = 0;
+  FIXTURE_MODE_FAST = 1;
+}
+
+// A fixture topic.
+message FixtureTopic {
+  // A topic-level config key (e.g. `segment.bytes`).
+  string name = 1;
+
+  // Whether the config is read-only, or is dynamic and can be altered.
+  bool read_only = 2;
+
+  // Wrapped option lists must be covered by the declaration span, so a
+  // suggestion block can replace the whole statement.
+  string wrapped = 3 [
+    (buf.validate.field).string.min_len = 1,
+    (buf.validate.field).string.max_len = 255
+  ];
+
+  // Sets default_topic_partitions when the topic is created.
+  int32 partitions = 4;
+
+  // A comment can wrap over several lines, and the resolved prose joins them
+  // rather than keeping only the first.
+  string wrapped_comment = 5;
+
+  string undocumented = 6;
+
+  // An openapiv2_field description OVERRIDES this comment, so the comment is
+  // dead text and the option's string is what must be linted.
+  string option_documented = 9 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      description: "The string the generator actually publishes."
+      example: "\"ignored\""
+    }
+  ];
+
+  /*
+   * A field documented ONLY by an openapiv2_field option is not an
+   * undocumented field. 73 of console's fields are this shape and every one
+   * of them used to be reported as having no description.
+   *
+   * This note is a detached block comment, separated by a blank line, so that
+   * option_only genuinely has no leading comment of its own.
+   */
+
+  string option_only = 10 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      description: "Documented by the option alone."
+    }
+  ];
+
+  // A oneof moves the brace depth without opening a message. Matching a bare
+  // closing brace here popped FixtureTopic and reported the sibling message
+  // below as nested inside it.
+  oneof selector {
+    // Selects by name.
+    string by_name = 7;
+    // Selects by id.
+    string by_id = 8;
+  }
+
+  // Nested messages are genuinely nested and should report a dotted path.
+  message Nested {
+    // The nested value.
+    string value = 1;
+  }
+}
+
+// A sibling of FixtureTopic, not a child of it.
+message FixtureSibling {
+  // The sibling name.
+  string name = 1;
+}
+
+service FixtureService {
+  rpc CreateFixture(FixtureTopic) returns (FixtureTopic) {
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      summary: "Create fixture."
+      description: "Create a [fixture](https://docs.redpanda.com/fixture/) with a `{prefix}` path."
+      responses: {
+        key: "200"
+        value: {description: "OK"}
+      }
+      responses: {
+        key: "201"
+        value: {description: "Fixture created"}
+      }
+    };
+  }
+
+  rpc ListFixtures(FixtureTopic) returns (FixtureTopic) {
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      summary: "List fixtures"
+      description: "Short one"
+    };
+  }
+
+  rpc JoinFixtures(FixtureTopic) returns (FixtureTopic) {
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      summary: "Join fixtures"
+      // Proto concatenates adjacent string literals like C++, so the resolved
+      // description is both halves, not just the first.
+      description: "Joins two fixtures together "
+                   "and returns the result."
+    };
+  }
+}

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

@@ -28,7 +28,7 @@ This fixture exercises the ` + "`raw` + interpreted + `raw`" + ` concatenation i
 This heading and the table below are legitimate AsciiDoc:
 
 |===
-| kafka_key | The record key
+| `+"`kafka_key`"+` | The record key
 |===
 `).
 		Fields(fixtureConfigFields()...)

package/tools/lint-strings/fixtures/crd/lint_types.go

@@ -4,6 +4,7 @@ package v1alpha2
 
 import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/runtime"
 )
 
 // WidgetSpec defines the configuration of a fixture widget.
@@ -35,6 +36,75 @@ type WidgetReference struct {
 	Version int    `json:"version"`
 }
 
+// EmptyOnOneLine opens and closes on a single line. Assuming it opened a
+// struct body left the parser inside a type that had already ended, which
+// dropped every declaration below it in the file.
+type EmptyOnOneLine struct{}
+
+// ValueSource represents where a value can be pulled from.
+type ValueSource struct {
+	// The literal value.
+	Value string `json:"value,omitempty"`
+}
+
+// UndocumentedType has no doc comment of its own, so a field referencing it
+// has nothing to inherit and genuinely ships blank.
+type undocumentedTypeMarker int
+
+type UndocumentedTarget struct {
+	// The only field.
+	Only string `json:"only,omitempty"`
+}
+
+// InlinedValues is +hidefromdoc, but it is embedded with `json:",inline"`
+// below, so crd-ref-docs flattens its fields into the embedding type and
+// publishes every one of them. The marker suppresses this type's own section,
+// not its fields.
+// +hidefromdoc
+type InlinedValues struct {
+	ReplicaCount *int32 `json:"replicaCount,omitempty"`
+}
+
+// HiddenNotInlined is +hidefromdoc and embedded nowhere, so nothing it
+// declares is ever published.
+// +hidefromdoc
+type HiddenNotInlined struct {
+	NeverPublished string `json:"neverPublished,omitempty"`
+}
+
+// EmbeddingSpec inlines a hidden type.
+type EmbeddingSpec struct {
+	InlinedValues `json:",inline"`
+	// The name of the thing.
+	Name string `json:"name,omitempty"`
+}
+
+// StructuralSpec covers external types that controller-gen publishes with no
+// description of their own.
+type StructuralSpec struct {
+	// +optional
+	Config *runtime.RawExtension `json:"config,omitempty"`
+	// +optional
+	Expiration *metav1.Time `json:"expiration,omitempty"`
+}
+
+// FallbackSpec covers what an uncommented field actually publishes.
+type FallbackSpec struct {
+	// +optional
+	Inherited *ValueSource `json:"inherited,omitempty"`
+	// +optional
+	FromUndocumented *UndocumentedTarget `json:"fromUndocumented,omitempty"`
+	// +optional
+	Primitive string `json:"primitive,omitempty"`
+	// +optional
+	SliceOfDocumented []ValueSource `json:"sliceOfDocumented,omitempty"`
+	// +optional
+	External *metav1.Duration `json:"external,omitempty"`
+	// How long to wait before giving up on the widget.
+	// +optional
+	Both *ValueSource `json:"both,omitempty"`
+}
+
 // WidgetList is ignored via the config's ignoreTypes ('List$').
 type WidgetList struct {
 	metav1.TypeMeta `json:",inline"`

package/tools/lint-strings/fixtures/helm/lint_values.yaml

@@ -11,7 +11,8 @@ image:
   tag: latest
 
 # -- Service settings that were commented out wholesale. The nested markers
-# below are dead: no pipeline can attach them.
+# below are dead: they use the indented `#   -- ` form, which helm-docs does
+# not recognize as a marker at all, so no pipeline can attach them.
 # service:
 #   -- set service.name to override the default service name
 #   name: redpanda
@@ -20,8 +21,9 @@ image:
 #     annotations: {}
 
 
-# A marker separated from any key by a blank line is dead too:
-# -- This orphaned description attaches to nothing.
+# A marker separated from the next key by blank lines is NOT dead: helm-docs
+# ignores the gap and hands it to the next real key below, which is `resources`.
+# -- Orphaned marker; helm-docs attaches this to the next real key.
 
 # @doc external.domain -- Optional domain advertised to external clients.
 # @default -- `nil`
@@ -33,6 +35,17 @@ resources:
 # @ignored
 internalHiddenKey: {}
 
+misattached:
+  # -- Written for the commented-out key below, but with no blank line and no
+  # later marker, helm-docs hands this text to realKeyBelow instead.
+  # optionalKey:
+  realKeyBelow: value
+  # -- Written for the commented-out key below. The real key that follows has
+  # its own marker, so helm-docs uses that one and nothing is misattached.
+  # anotherOptional:
+  # -- The guarded key's own description.
+  guarded: value
+
 undocumentedTopLevel:
   child: value
 

package/tools/lint-strings/index.js

@@ -25,7 +25,8 @@ const SURFACES = {
   rpk: require('./surfaces/rpk'),
   helm: require('./surfaces/helm'),
   crd: require('./surfaces/crd'),
-  connect: require('./surfaces/connect')
+  connect: require('./surfaces/connect'),
+  api: require('./surfaces/api')
 }
 
 /**

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

@@ -54,6 +54,79 @@ function isNameEcho (name, description) {
   return true
 }
 
+/**
+ * Blank out the spans of a description where a code-ish token is expected to
+ * appear bare, so the inline-code rule only sees prose:
+ *
+ *   * backticked spans - already marked up, which is the whole point;
+ *   * URLs and Markdown link targets - a path inside a link is part of the
+ *     link, and backticking it would break the link;
+ *   * anything the declaration is named after, which name-echo owns.
+ *
+ * Replaced with spaces rather than removed so match indices stay meaningful.
+ */
+function maskNonProse (text) {
+  let out = text
+  const blank = (m) => ' '.repeat(m.length)
+  // Backticked spans first: a URL inside backticks is already marked up.
+  out = out.replace(/`[^`]*`/g, blank)
+  // Markdown links: mask the whole construct, target included.
+  out = out.replace(/\[[^\]]*\]\([^)]*\)/g, blank)
+  // Bare URLs, and AsciiDoc's url[text] form.
+  out = out.replace(/\b[a-z][a-z0-9+.-]*:\/\/\S+/gi, blank)
+  return out
+}
+
+/**
+ * Tokens that are code and read as code, so they belong in inline code.
+ * Backticks are the portable choice: a single-backtick span is inline code in
+ * both AsciiDoc and Markdown, so one rule covers every surface regardless of
+ * which format the generator emits.
+ *
+ * Deliberately narrow. This rule posts inline suggestions on engineering PRs,
+ * so a false positive costs more than a miss:
+ *
+ *   * snake_case with at least two segments - in this domain that is always an
+ *     identifier (`default_topic_partitions`), never prose;
+ *   * long flags (`--tolerate-data-loss`);
+ *   * absolute paths with at least two segments (`/etc/redpanda/redpanda.yaml`,
+ *     `/v1/topics`).
+ *
+ * Not included, on purpose: dotted keys (`segment.bytes`) collide with
+ * sentence boundaries and abbreviations; bare `true`/`false` and numbers
+ * appear in ordinary prose; single-segment lowercase words are unrecoverable
+ * from prose without a symbol table.
+ */
+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 }
+])
+
+/**
+ * Code-ish tokens in a description that are not inside inline code.
+ * Exported for tests and for the surfaces that scope the rule differently.
+ */
+function findBareCodeTokens (text, name = null) {
+  const masked = maskNonProse(String(text || ''))
+  const found = []
+  const seen = new Set()
+  for (const { id, re } of CODE_TOKEN_PATTERNS) {
+    re.lastIndex = 0
+    let match
+    while ((match = re.exec(masked)) !== null) {
+      const token = match[0]
+      // The declaration's own name restating itself is name-echo's finding,
+      // not a markup one.
+      if (name && token === name) continue
+      if (seen.has(token)) continue
+      seen.add(token)
+      found.push({ token, kind: id })
+    }
+  }
+  return found
+}
+
 const COMMON_RULES = [
   {
     name: 'empty-description',
@@ -142,7 +215,20 @@ const COMMON_RULES = [
       }
       return []
     }
+  },
+  {
+    name: 'missing-inline-code',
+    description: 'Code value or field name in prose without inline code',
+    severity: 'warning',
+    check: (decl) => {
+      const bare = findBareCodeTokens(decl.string, decl.name)
+      if (bare.length === 0) return []
+      const list = bare.map((b) => `\`${b.token}\``).join(', ')
+      return [{
+        message: `Code values and field names belong in inline code: ${list}. Wrap each in backticks, which render as inline code in both AsciiDoc and Markdown.`
+      }]
+    }
   }
 ]
 
-module.exports = { COMMON_RULES, JARGON_TERMS, isNameEcho, tokenize }
+module.exports = { COMMON_RULES, JARGON_TERMS, isNameEcho, tokenize, findBareCodeTokens, maskNonProse }