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

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

@@ -0,0 +1,57 @@
+// Package v1alpha2 is a lint-strings test fixture mirroring the operator
+// API type shapes. It only needs to parse as Go text for the scanner.
+package v1alpha2
+
+import (
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+// WidgetSpec defines the configuration of a fixture widget.
+type WidgetSpec struct {
+	// ClusterSource is a reference to the cluster hosting the widget.
+	// It leads with the Go field name, which users never type.
+	// +required
+	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="ClusterSource is immutable"
+	ClusterSource *ClusterSource `json:"cluster"`
+	// Text is the actual unescaped text of a widget. The Go name matches
+	// the json name (case only), so this conforms.
+	// +required
+	Text string `json:"text,omitempty"`
+	// Specifies how many replicas to run. Conforming: describes behavior,
+	// never names the field.
+	// +kubebuilder:default=3
+	Replicas *int `json:"replicas,omitempty"`
+	// +hidefromdoc
+	// Internal knob hidden from the docs; never linted.
+	HiddenKnob string `json:"hiddenKnob,omitempty"`
+	NotSerialized string `json:"-"`
+}
+
+// WidgetReference is a way for one widget to reference another. Its fields
+// are undocumented on purpose (the known-bad this fixture exists for).
+type WidgetReference struct {
+	Name    string `json:"name"`
+	Subject string `json:"subject"`
+	Version int    `json:"version"`
+}
+
+// WidgetList is ignored via the config's ignoreTypes ('List$').
+type WidgetList struct {
+	metav1.TypeMeta `json:",inline"`
+	UndocumentedButIgnored string `json:"items"`
+}
+
+// DeprecatedWidget matches ignoreTypes ('Deprecated.*$').
+type DeprecatedWidget struct {
+	Old string `json:"old"`
+}
+
+// +hidefromdoc
+// HiddenStruct is hidden from the docs wholesale.
+type HiddenStruct struct {
+	Anything string `json:"anything"`
+}
+
+func (w *WidgetSpec) helper() bool { // functions between types must not confuse the parser
+	return w != nil && len(w.Text) > 0
+}

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

@@ -0,0 +1,47 @@
+# lint-strings test fixture: helm-docs conventions with known-bads and
+# conforming counterparts.
+
+# -- Enable or disable the thing entirely. This description conforms.
+enabled: true
+
+# -- Image settings for the fixture chart.
+image:
+  # -- The container image repository to pull from.
+  repository: docker.redpanda.com/redpandadata/redpanda
+  tag: latest
+
+# -- Service settings that were commented out wholesale. The nested markers
+# below are dead: no pipeline can attach them.
+# service:
+#   -- set service.name to override the default service name
+#   name: redpanda
+#   -- internal Service settings
+#   internal:
+#     annotations: {}
+
+
+# A marker separated from any key by a blank line is dead too:
+# -- This orphaned description attaches to nothing.
+
+# @doc external.domain -- Optional domain advertised to external clients.
+# @default -- `nil`
+
+resources:
+  # -- Requested CPU cores. Commented-out key documented in place:
+  # cpu: 1
+
+# @ignored
+internalHiddenKey: {}
+
+undocumentedTopLevel:
+  child: value
+
+config: |
+  # -- inside a block scalar this marker is content, not documentation
+  some: content
+
+# -- External access settings.
+external:
+  # -- Optional domain advertised to external clients. Hyphenated key names
+  # must survive both the generator and the linter.
+  # my-domain: local

package/tools/lint-strings/fixtures/metrics/lint_probe.cc

@@ -0,0 +1,41 @@
+// Fixture source for lint-strings metrics-scanner tests. Mirrors the shapes
+// in redpanda's src/v/cluster/partition_probe.cc: single-literal and
+// clang-format-wrapped adjacent-literal sm::description() arguments, plus a
+// non-literal argument that must stay unverifiable (info-level, never error).
+// Tests assert both rule ids and line spans, located by marker strings.
+#include "cluster/lint_probe.h"
+
+namespace cluster {
+
+void lint_probe::setup_metrics() {
+    namespace sm = ss::metrics;
+
+    _metrics.add_group(
+      prometheus_sanitize::metrics_name("cluster:partition"),
+      {
+        sm::make_gauge(
+          "start_offset",
+          [this] { return _start_offset; },
+          sm::description("start offset"),
+          labels),
+        sm::make_gauge(
+          "committed_offset",
+          [this] { return _committed_offset; },
+          sm::description(
+            "Partition commited offset. i.e. safely persisted on "
+            "majority of replicas."),
+          labels),
+        sm::make_counter(
+          "records_produced",
+          [this] { return _records_produced; },
+          sm::description("Total number of records produced"),
+          labels),
+        sm::make_gauge(
+          "buffer_size",
+          [this] { return _buffer_size; },
+          sm::description(fmt::format("Size of {} buffer", _name)),
+          labels),
+      });
+}
+
+} // namespace cluster

package/tools/lint-strings/fixtures/properties/lint_fixture.cc

@@ -0,0 +1,51 @@
+// Fixture source for lint-strings tests. Member-initializer entries mirror
+// redpanda's src/v/config/configuration.cc, including clang-format-wrapped
+// adjacent string literals. Tests assert both rule ids and line spans, so
+// edit with care: spans are located by searching for the marker strings.
+#include "lint_fixture.h"
+
+namespace config {
+
+lint_fixture_config::lint_fixture_config()
+  : compaction_ctrl_update_interval_ms(
+      *this,
+      "compaction_ctrl_update_interval_ms",
+      "",
+      {.needs_restart = needs_restart::no, .visibility = visibility::tunable},
+      30s)
+  , cloud_storage_credentials_source(
+      *this,
+      "cloud_storage_credentials_source",
+      "The source of credentials used to connect to cloud services. "
+      "Accepted values: `config_file`, `aws_instance_metadata`, `sts, "
+      "`gcp_instance_metadata`.",
+      {.needs_restart = needs_restart::yes, .visibility = visibility::user},
+      std::nullopt)
+  , cloud_storage_upload_ctrl_p_coeff(
+      *this,
+      "cloud_storage_upload_ctrl_p_coeff",
+      "proportional coefficient for upload PID controller",
+      {.needs_restart = needs_restart::yes, .visibility = visibility::tunable},
+      -2.0)
+  , cluster_id(
+      *this,
+      "cluster_id",
+      "Cluster identifier.",
+      {.needs_restart = needs_restart::no, .visibility = visibility::user},
+      std::nullopt)
+  , write_caching_default_bytes(
+      *this,
+      "write_caching_default_bytes",
+      "recomended default",
+      {.needs_restart = needs_restart::no, .visibility = visibility::tunable},
+      1024)
+  , kafka_batch_max_bytes(
+      *this,
+      "kafka_batch_max_bytes",
+      "Maximum size of a batch processed by the server. If the batch is "
+      "compressed, the limit applies to the compressed batch size. Default "
+      "is 1048576 bytes.",
+      {.needs_restart = needs_restart::no, .visibility = visibility::user},
+      1048576) {}
+
+} // namespace config

package/tools/lint-strings/fixtures/properties/lint_fixture.h

@@ -0,0 +1,33 @@
+// Fixture header for lint-strings tests. The declarations mirror the shapes
+// in redpanda's src/v/config/configuration.h so the real property extractor
+// can parse the matching .cc file.
+#pragma once
+
+#include "config/property.h"
+
+namespace config {
+
+struct lint_fixture_config {
+    // Known-bad: empty description (mirrors configuration.cc
+    // compaction_ctrl_update_interval_ms)
+    property<std::chrono::milliseconds> compaction_ctrl_update_interval_ms;
+
+    // Known-bad: unbalanced backticks (mirrors configuration.cc
+    // cloud_storage_credentials_source)
+    enum_property<ss::sstring> cloud_storage_credentials_source;
+
+    // Known-bad: lowercase-start fragment, no terminal period
+    property<double> cloud_storage_upload_ctrl_p_coeff;
+
+    // Known-bad: tautology (description just restates the name)
+    property<std::optional<ss::sstring>> cluster_id;
+
+    // Known-bad: "recomended" typo string. Typo detection is NOT a lint rule;
+    // this doubles as the lowercase-start + under-20-chars example.
+    property<int32_t> write_caching_default_bytes;
+
+    // Conforming counterpart: must produce zero findings.
+    property<int32_t> kafka_batch_max_bytes;
+};
+
+} // namespace config

package/tools/lint-strings/fixtures/rpk/lint_cmd.go

@@ -0,0 +1,69 @@
+// Package lintfixture is a lint-strings test fixture: known-bad rpk
+// declarations with conforming counterparts. It only needs to parse as Go
+// text for the scanner; it is never compiled.
+package lintfixture
+
+import (
+	"github.com/spf13/afero"
+	"github.com/spf13/cobra"
+)
+
+// cobra.Command mentioned in a comment must never match: cobra.Command{Use: "fake"}.
+
+func newLowercaseShortCommand(fs afero.Fs) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "badshort",
+		Short: "queries cluster for health overview.",
+		Long: `Query the cluster.
+
+USAGE DETAILS
+
+This section heading above is intended.
+
+Some detail text here that is not a heading.
+====
+
+The ==== line above breaks the generated page.
+`,
+		Run: func(cmd *cobra.Command, _ []string) {
+			// A paren ) and brace } in a string: "don't break (the) scanner".
+		},
+	}
+	cmd.Flags().BoolVarP(&watch, "watch", "w", false, "Blocks and writes out all changes")
+	cmd.Flags().StringVar(&dest, "trailing-period", "", "Writes the output to the given path.")
+	cmd.Flags().String("verbose-output", "", "verbose output")
+	return cmd
+}
+
+const conformingLong = `Manage widgets.
+
+This is a conforming Long description with no heading-shaped lines,
+resolved through a package-level constant.
+`
+
+func newConformingCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "widget [NAME]",
+		Aliases: []string{"widgets"},
+		Short:   "Manage widgets in the cluster",
+		Long:    conformingLong,
+	}
+	f := cmd.Flags()
+	f.IntVar(&count, "retries", 3, "Number of retries before giving up")
+	f.DurationVar(&timeout, "timeout", 0, "How long to wait for the cluster to respond, for example 30s")
+	cmd.Flags().StringP("format", "f", "text", "Output format, one of text or json")
+	// Dynamic usage strings stay unverifiable, never errors:
+	cmd.Flags().BoolP("help", "h", false, "Help for "+cmd.Name())
+	return cmd
+}
+
+// A multiline Short: the rpk convention is a one-line Short, so this is the
+// known-bad counterpart for the rpk-short-multiline rule. Everything else
+// about it conforms, so it isolates that one rule.
+func newMultilineShortCommand() *cobra.Command {
+	return &cobra.Command{
+		Use: "multiline",
+		Short: `Manage the widget cache
+and everything attached to it`,
+	}
+}

package/tools/lint-strings/go-source.js

@@ -0,0 +1,327 @@
+'use strict'
+
+/**
+ * Shared Go source scanning helpers for the rpk, crd, and connect surfaces.
+ *
+ * Same philosophy as the metrics scanner (surfaces/metrics.js): a
+ * comment-masked regex/paren scanner over real source text, never a compiler.
+ * Go adds two string shapes the C++ scanner does not have: raw strings
+ * (`...` backticks, no escapes, literal newlines) and rune literals ('x').
+ * All helpers preserve offsets and newlines so line numbers stay exact.
+ */
+
+/**
+ * Replace // and /* *\/ comments with spaces, preserving every offset and
+ * newline. String and rune literal contents are left untouched, so a "//"
+ * inside a string never masks anything.
+ */
+function maskComments (content) {
+  const out = content.split('')
+  let i = 0
+  while (i < content.length) {
+    const ch = content[i]
+    if (ch === '"' || ch === '`' || ch === "'") {
+      i = skipString(content, i)
+      continue
+    }
+    if (ch === '/' && content[i + 1] === '/') {
+      while (i < content.length && content[i] !== '\n') out[i++] = ' '
+      continue
+    }
+    if (ch === '/' && content[i + 1] === '*') {
+      const end = content.indexOf('*/', i + 2)
+      const stop = end === -1 ? content.length : end + 2
+      while (i < stop) {
+        if (content[i] !== '\n') out[i] = ' '
+        i++
+      }
+      continue
+    }
+    i++
+  }
+  return out.join('')
+}
+
+/**
+ * Skip a Go string/rune literal starting at index; returns the index after
+ * it. Interpreted strings ("...") and runes ('x') honor backslash escapes;
+ * raw strings (`...`) have no escapes and may span lines.
+ */
+function skipString (content, start) {
+  const quote = content[start]
+  let i = start + 1
+  if (quote === '`') {
+    while (i < content.length && content[i] !== '`') i++
+    return Math.min(i + 1, content.length)
+  }
+  while (i < content.length) {
+    if (content[i] === '\\') {
+      i += 2
+      continue
+    }
+    if (content[i] === quote) return i + 1
+    i++
+  }
+  return content.length
+}
+
+/**
+ * Walk forward from an opening delimiter and return the index of its
+ * balanced closing delimiter, skipping string/rune literals. Assumes
+ * comment-masked content. Returns -1 when unbalanced.
+ */
+function findBalancedClose (content, openIndex, open = '(', close = ')') {
+  let depth = 0
+  let i = openIndex
+  while (i < content.length) {
+    const ch = content[i]
+    if (ch === '"' || ch === '`' || ch === "'") {
+      i = skipString(content, i)
+      continue
+    }
+    if (ch === open) depth++
+    if (ch === close) {
+      depth--
+      if (depth === 0) return i
+    }
+    i++
+  }
+  return -1
+}
+
+/** Decode a Go interpreted-string body (the text between the quotes). */
+function unescapeGo (text) {
+  return text.replace(/\\(.)/g, (whole, ch) => {
+    if (ch === 'n') return '\n'
+    if (ch === 't') return '\t'
+    if (ch === 'r') return '\r'
+    return ch
+  })
+}
+
+/**
+ * Split argument text on top-level commas (string, paren, brace, and
+ * bracket aware). Assumes comment-masked content.
+ */
+function splitTopLevelArgs (argText) {
+  const args = []
+  let start = 0
+  let depth = 0
+  let i = 0
+  while (i < argText.length) {
+    const ch = argText[i]
+    if (ch === '"' || ch === '`' || ch === "'") {
+      i = skipString(argText, i)
+      continue
+    }
+    if (ch === '(' || ch === '{' || ch === '[') depth++
+    if (ch === ')' || ch === '}' || ch === ']') depth--
+    if (ch === ',' && depth === 0) {
+      args.push(argText.slice(start, i))
+      start = i + 1
+    }
+    i++
+  }
+  const last = argText.slice(start)
+  if (last.trim() !== '' || args.length > 0) args.push(last)
+  return args
+}
+
+/**
+ * Collect same-file string constants: `const x = "..."` and const blocks.
+ * Only constants whose value is purely (concatenated) string literals are
+ * recorded - anything else stays unresolvable so it can never fake a
+ * verifiable description.
+ *
+ * @param {string} masked - Comment-masked file content
+ * @returns {Map<string, string>} identifier -> string value
+ */
+function collectStringConsts (masked) {
+  const consts = new Map()
+  const pattern = /\bconst\b/g
+  let match
+  while ((match = pattern.exec(masked)) !== null) {
+    let i = match.index + match[0].length
+    while (i < masked.length && /[ \t]/.test(masked[i])) i++
+    if (masked[i] === '(') {
+      const close = findBalancedClose(masked, i)
+      if (close === -1) continue
+      collectConstEntries(masked.slice(i + 1, close), consts)
+      pattern.lastIndex = close + 1
+    } else {
+      // Single-const form: the statement ends at the first newline OUTSIDE
+      // a string (a raw-string value may span lines), unless that newline
+      // follows a `+` continuation - Go allows a string concatenation to
+      // wrap across lines with no surrounding parens.
+      let j = i
+      while (j < masked.length) {
+        if (masked[j] === '"' || masked[j] === '`' || masked[j] === "'") {
+          j = skipString(masked, j)
+          continue
+        }
+        if (masked[j] === '\n') {
+          let k = j - 1
+          while (k >= i && /[ \t\r]/.test(masked[k])) k--
+          if (k >= i && masked[k] === '+') {
+            j++
+            continue
+          }
+          break
+        }
+        j++
+      }
+      collectConstEntries(masked.slice(i, j), consts)
+      pattern.lastIndex = j
+    }
+  }
+  return consts
+}
+
+/** Parse `name [type] = <string expr>` lines inside a const region. */
+function collectConstEntries (regionText, consts) {
+  // Split on newlines OUTSIDE strings (raw strings may span lines), unless
+  // the newline follows a `+` continuation - a string concatenation may
+  // wrap across lines with no surrounding parens, and must stay one entry.
+  const lines = []
+  let start = 0
+  let i = 0
+  while (i < regionText.length) {
+    const ch = regionText[i]
+    if (ch === '"' || ch === '`' || ch === "'") {
+      i = skipString(regionText, i)
+      continue
+    }
+    if (ch === '\n') {
+      let k = i - 1
+      while (k >= start && /[ \t\r]/.test(regionText[k])) k--
+      if (k >= start && regionText[k] === '+') {
+        i++
+        continue
+      }
+      lines.push(regionText.slice(start, i))
+      start = i + 1
+    }
+    i++
+  }
+  lines.push(regionText.slice(start))
+
+  for (const line of lines) {
+    const m = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*(?:[A-Za-z_][A-Za-z0-9_.]*\s*)?=\s*(.+)$/s)
+    if (!m) continue
+    const { verifiable, value } = evalStringExpr(m[2], consts)
+    if (verifiable) consts.set(m[1], value)
+  }
+}
+
+/**
+ * Evaluate a Go expression expected to produce a string: a sequence of
+ * string literals and known identifiers joined by `+`. Anything else
+ * (function calls, fmt.Sprintf, selectors, unknown identifiers) makes the
+ * result unverifiable - the caller reports it, never guesses.
+ *
+ * @param {string} exprText - Comment-masked expression text
+ * @param {Map<string, string>} [consts] - Same-file string constants
+ * @returns {{ verifiable: boolean, value: string|null, sawString: boolean }}
+ */
+function evalStringExpr (exprText, consts = new Map()) {
+  const parts = []
+  let verifiable = true
+  let sawString = false
+  let i = 0
+  while (i < exprText.length) {
+    const ch = exprText[i]
+    if (/\s/.test(ch) || ch === '+') {
+      i++
+      continue
+    }
+    if (ch === '"') {
+      const end = skipString(exprText, i)
+      parts.push(unescapeGo(exprText.slice(i + 1, end - 1)))
+      sawString = true
+      i = end
+      continue
+    }
+    if (ch === '`') {
+      const end = skipString(exprText, i)
+      parts.push(exprText.slice(i + 1, end - 1))
+      sawString = true
+      i = end
+      continue
+    }
+    if (/[A-Za-z_]/.test(ch)) {
+      let j = i
+      while (j < exprText.length && /[A-Za-z0-9_.]/.test(exprText[j])) j++
+      const ident = exprText.slice(i, j)
+      // A following "(" means a call - unverifiable.
+      let k = j
+      while (k < exprText.length && /\s/.test(exprText[k])) k++
+      if (exprText[k] === '(') {
+        verifiable = false
+        const close = findBalancedClose(exprText, k)
+        i = close === -1 ? exprText.length : close + 1
+        continue
+      }
+      if (consts.has(ident)) {
+        parts.push(consts.get(ident))
+        sawString = true
+      } else {
+        verifiable = false
+      }
+      i = j
+      continue
+    }
+    // Any other token (&, numbers, composite literals, ...) is not a string.
+    verifiable = false
+    if (ch === '(' || ch === '{' || ch === '[') {
+      const close = findBalancedClose(exprText, i, ch, ch === '(' ? ')' : ch === '{' ? '}' : ']')
+      i = close === -1 ? exprText.length : close + 1
+      continue
+    }
+    i++
+  }
+  if (!sawString) return { verifiable: false, value: null, sawString }
+  return { verifiable, value: verifiable ? parts.join('') : null, sawString }
+}
+
+/** 1-indexed line number of a character offset. */
+function lineOf (content, index) {
+  let line = 1
+  for (let i = 0; i < index; i++) {
+    if (content[i] === '\n') line++
+  }
+  return line
+}
+
+const fs = require('fs')
+const path = require('path')
+
+/**
+ * Recursively collect .go files under root (repo-relative paths), skipping
+ * _test.go files, testdata/fuzzing dirs, and hidden dirs.
+ */
+function collectGoFiles (root, base = root, out = []) {
+  if (!fs.existsSync(root)) return out
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    if (entry.name.startsWith('.')) continue
+    const fullPath = path.join(root, entry.name)
+    if (entry.isDirectory()) {
+      if (entry.name === 'testdata' || entry.name === 'fuzzing' || entry.name === 'node_modules') continue
+      collectGoFiles(fullPath, base, out)
+    } else if (entry.name.endsWith('.go') && !entry.name.endsWith('_test.go')) {
+      out.push(path.relative(base, fullPath))
+    }
+  }
+  return out
+}
+
+module.exports = {
+  maskComments,
+  skipString,
+  findBalancedClose,
+  unescapeGo,
+  splitTopLevelArgs,
+  collectStringConsts,
+  evalStringExpr,
+  lineOf,
+  collectGoFiles
+}