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

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

@@ -0,0 +1,239 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const yaml = require('js-yaml')
+
+const { SourceCache } = require('../source-text')
+const { collectGoFiles } = require('../go-source')
+
+/**
+ * CRD surface: Go doc comments above struct fields in the operator API
+ * types (operator/api/redpanda/...). These comments ship verbatim to the
+ * generated CRD reference on docs.redpanda.com AND to `kubectl explain`.
+ *
+ * User-facing filtering mirrors crd-ref-docs: the surface reads
+ * operator/crd-ref-docs-config.yaml for the `hidefromdoc` custom marker and
+ * the processor ignoreTypes/ignoreFields regexes, so fields the generator
+ * never documents are never linted.
+ *
+ * Marker lines (+kubebuilder:..., +optional, +required, +genclient, and any
+ * other +directive) are stripped before the prose is judged.
+ *
+ * The signature bad pattern here is a description that leads with the Go
+ * field identifier ("ClusterSource is a reference to...") when users type
+ * the json key ("cluster") - the docs and kubectl explain both show the
+ * json name, so the Go name means nothing to readers.
+ */
+
+const CONVENTION = {
+  case: 'sentence',
+  terminal_period: true,
+  verbatim_asciidoc: true
+}
+
+const API_ROOT = path.join('operator', 'api', 'redpanda')
+const CONFIG_PATH = path.join('operator', 'crd-ref-docs-config.yaml')
+
+/**
+ * Compile a list of regex source strings, skipping (with a warning) any
+ * pattern that isn't valid JS regex syntax instead of throwing. The config
+ * file is written for a Go tool (crd-ref-docs), so it can legally contain
+ * Go/RE2-only constructs like `(?i)` or `(?P<name>...)` that JS's RegExp
+ * rejects - one such pattern must not abort the entire lint run.
+ */
+function compilePatterns (patterns, configKey) {
+  const compiled = []
+  for (const p of patterns) {
+    try {
+      compiled.push(new RegExp(p))
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.warn(`lint-strings: skipping invalid ${configKey} pattern in ${CONFIG_PATH} (${JSON.stringify(p)}): ${err.message}`)
+    }
+  }
+  return compiled
+}
+
+/** Load ignore rules from crd-ref-docs-config.yaml (absent file = no rules). */
+function loadConfig (repo) {
+  const configPath = path.join(repo, CONFIG_PATH)
+  const config = { ignoreTypes: [], ignoreFields: [], hiddenMarker: 'hidefromdoc' }
+  if (!fs.existsSync(configPath)) return config
+  const parsed = yaml.load(fs.readFileSync(configPath, 'utf8')) || {}
+  const processor = parsed.processor || {}
+  config.ignoreTypes = compilePatterns(processor.ignoreTypes || [], 'processor.ignoreTypes')
+  config.ignoreFields = compilePatterns(processor.ignoreFields || [], 'processor.ignoreFields')
+  return config
+}
+
+function matchesAny (patterns, ...candidates) {
+  return patterns.some((pattern) => candidates.some((c) => pattern.test(c)))
+}
+
+/**
+ * Parse one Go file's struct fields. Exported for tests.
+ *
+ * @param {string} content - File content
+ * @param {string} file - Repo-relative path
+ * @param {Object} config - From loadConfig
+ * @returns {Array} declarations (without declaration_text)
+ */
+function scanFile (content, file, config = { ignoreTypes: [], ignoreFields: [], hiddenMarker: 'hidefromdoc' }) {
+  const declarations = []
+  const lines = content.split('\n')
+  const packageMatch = content.match(/^package\s+(\w+)/m)
+  const pkg = packageMatch ? packageMatch[1] : ''
+
+  let comment = [] // pending comment lines: { line (0-indexed), text }
+  let struct = null // { name, hidden } while inside a struct body
+  let depth = 0
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const trimmed = line.trim()
+
+    if (struct === null) {
+      if (/^\s*\/\//.test(line)) {
+        comment.push({ line: i, text: trimmed.replace(/^\/\/\s?/, '') })
+        continue
+      }
+      const typeMatch = line.match(/^type\s+([A-Za-z0-9_]+)\s+struct\s*\{/)
+      if (typeMatch) {
+        const name = typeMatch[1]
+        const hidden = comment.some((c) => c.text.trim().startsWith(`+${config.hiddenMarker}`)) ||
+          matchesAny(config.ignoreTypes, name, `${pkg}.${name}`)
+        struct = { name, hidden, exported: /^[A-Z]/.test(name) }
+        depth = 1
+        comment = []
+        continue
+      }
+      if (trimmed !== '') comment = []
+      continue
+    }
+
+    // Inside a struct body.
+    if (/^\s*\/\//.test(line)) {
+      comment.push({ line: i, text: trimmed.replace(/^\/\/\s?/, '') })
+      continue
+    }
+    if (trimmed === '') {
+      comment = []
+      continue
+    }
+
+    // Track nested braces (anonymous struct fields) without leaving the type.
+    const opens = (trimmed.match(/\{/g) || []).length
+    const closes = (trimmed.match(/\}/g) || []).length
+    const fieldMatch = line.match(/^\s*([A-Z][A-Za-z0-9_]*)\s+\S/)
+    if (fieldMatch && depth === 1 && !struct.hidden && struct.exported) {
+      const goName = fieldMatch[1]
+      const tagMatch = line.match(/`[^`]*json:"([^",]*)[^`]*`/)
+      const jsonName = tagMatch ? tagMatch[1] : null
+      const hiddenField = comment.some((c) => c.text.trim().startsWith(`+${config.hiddenMarker}`))
+      // Only json-serialized, non-inline, non-ignored fields ship to users.
+      if (jsonName && jsonName !== '-' && !hiddenField &&
+          !matchesAny(config.ignoreFields, goName, goName.toLowerCase(), jsonName)) {
+        const prose = comment
+          .filter((c) => !c.text.trim().startsWith('+'))
+          .map((c) => c.text)
+          .join('\n')
+          .trim()
+        declarations.push({
+          surface: 'crd',
+          name: jsonName,
+          file,
+          line_start: (comment.length > 0 ? comment[0].line : i) + 1,
+          line_end: i + 1,
+          string: prose || null,
+          declaration_text: null,
+          convention: CONVENTION,
+          meta: {
+            kind: 'field',
+            struct: struct.name,
+            go_name: goName,
+            json_name: jsonName
+          }
+        })
+      }
+    }
+    comment = []
+    depth += opens - closes
+    if (depth <= 0) struct = null
+  }
+
+  return declarations
+}
+
+/**
+ * Extract CRD field declarations.
+ *
+ * @param {Object} options - { repo, files (Set of repo-relative paths, diff
+ *   mode; when omitted, scans operator/api/redpanda), log }
+ */
+function extract ({ repo, files = null }) {
+  const config = loadConfig(repo)
+  let fileList
+  if (files) {
+    fileList = [...files].filter((f) => f.endsWith('.go') && !f.endsWith('_test.go') && !path.basename(f).startsWith('zz_generated'))
+  } else {
+    fileList = collectGoFiles(path.join(repo, API_ROOT))
+      .filter((f) => !path.basename(f).startsWith('zz_generated'))
+      .map((f) => path.join(API_ROOT, f))
+  }
+
+  const cache = new SourceCache(repo)
+  const declarations = []
+  for (const file of fileList) {
+    const absPath = path.isAbsolute(file) ? file : path.join(repo, file)
+    if (!fs.existsSync(absPath)) continue
+    const content = fs.readFileSync(absPath, 'utf8')
+    if (!content.includes('struct')) continue
+    for (const decl of scanFile(content, file, config)) {
+      decl.declaration_text = cache.span(file, decl.line_start, decl.line_end)
+      declarations.push(decl)
+    }
+  }
+  return declarations
+}
+
+/** Surface-specific convention rules. */
+const RULES = [
+  {
+    name: 'undocumented-field',
+    description: 'Exported user-facing field with no doc comment',
+    severity: 'warning',
+    check: (decl) => {
+      if (decl.string !== null) return []
+      return [{ message: `Field "${decl.meta.go_name}" (json: "${decl.name}") in ${decl.meta.struct} has no doc comment. It ships blank in the CRD reference and in kubectl explain.` }]
+    }
+  },
+  {
+    name: 'go-field-name-first',
+    description: 'Description leads with the Go field name instead of the YAML key',
+    severity: 'warning',
+    check: (decl) => {
+      const text = (decl.string || '').trim()
+      if (!text) return []
+      const firstWord = (text.match(/^[A-Za-z0-9_]+/) || [null])[0]
+      if (!firstWord) return []
+      if (firstWord === decl.meta.go_name &&
+          decl.meta.go_name.toLowerCase() !== decl.meta.json_name.toLowerCase()) {
+        return [{ message: `Description starts with the Go field name "${decl.meta.go_name}", but users type "${decl.meta.json_name}" in YAML. Describe the json key: "${decl.meta.json_name}" (or start with what the field does).` }]
+      }
+      return []
+    }
+  }
+]
+
+module.exports = {
+  name: 'crd',
+  convention: CONVENTION,
+  extract,
+  scanFile,
+  loadConfig,
+  rules: RULES,
+  // Missing prose is surfaced by the crd-specific undocumented-field rule
+  // (warning, per the docs contract) instead of the generic error.
+  skipRules: ['empty-description']
+}

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

@@ -0,0 +1,159 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+const { SourceCache } = require('../source-text')
+const { parseValuesFile: parseSharedValuesFile } = require('../../../cli-utils/helm-commented-values')
+
+/**
+ * Helm surface: helm-docs description comments in chart values.yaml files
+ * (charts/<name>/chart/values.yaml, plus charts/<name>/values.yaml for
+ * charts without the chart/ subdir).
+ *
+ * Documentation conventions - the union of what actually ships:
+ * - helm-docs: `# -- description` (with plain `# ...` continuation lines)
+ *   attaches to the real key DIRECTLY below the comment block; `# @default
+ *   -- text`, `# @raw`, and `# @ignored` annotate it.
+ * - doc-tools helm-spec (cli-utils/helm-commented-values.js): a `# --`
+ *   block directly above a COMMENTED-OUT key documents that key, and
+ *   `# @doc full.path -- description` documents any path explicitly.
+ *
+ * Both conventions are decided by ONE walk, cli-utils/helm-commented-values
+ * `parseValuesFile`, which this surface calls with attachRealKeys so it also
+ * models helm-docs' own real-key attachment. This file used to hold a
+ * byte-identical copy of that module's nine regexes and a near-copy of its
+ * state machine, on the stated grounds that "the linter never calls a marker
+ * dead that the generator in this repo renders" - which nothing enforced.
+ * Sharing the walk is what actually enforces it.
+ *
+ * A DEAD marker is a `# --` block neither pipeline can attach: one buried
+ * inside another commented-out key's subtree (the classic commented-out
+ * example block), or one separated from any key by a blank line. Its
+ * description silently never ships - that is the error this surface exists
+ * to catch.
+ *
+ * helm-docs output is markdown converted via pandoc, not verbatim AsciiDoc,
+ * so the verbatim escaping rules do not apply. Terminal periods are
+ * optional prose style here; only capitalization is enforced (via the
+ * common starts-lowercase rule).
+ */
+
+const CONVENTION = {
+  case: 'sentence',
+  terminal_period: 'optional',
+  verbatim_asciidoc: false
+}
+
+/**
+ * Parse one values.yaml into lint declarations. Exported for tests.
+ *
+ * The attachment decisions and the line spans both come from the shared walk;
+ * this function only reshapes its records into the linter's declaration form.
+ *
+ * @param {string} content - File content
+ * @param {string} file - Repo-relative path
+ * @returns {Array} declarations (without declaration_text)
+ */
+function parseValuesFile (content, file) {
+  return parseSharedValuesFile(content, { attachRealKeys: true }).map((r) => {
+    // The generator keeps newlines in a description; helm-docs renders one
+    // paragraph, and the rules read one string, so flatten here.
+    const string = r.descLines.map((l) => l.trim()).filter(Boolean).join(' ') || null
+    let meta
+    if (r.kind === 'dead-marker') {
+      meta = { kind: 'dead-marker', unverifiable: true }
+    } else if (r.undocumented) {
+      // Nothing to lint for content: the rule fires on the absence itself.
+      meta = { kind: 'key', top_level: true, undocumented: true, unverifiable: true }
+    } else if (r.commentedOut) {
+      meta = { kind: 'key', commented_out: true, top_level: r.topLevel, default_annotation: r.default || null }
+    } else {
+      meta = { kind: 'key', top_level: r.topLevel, raw: Boolean(r.annotations.raw), default_annotation: r.default || null }
+    }
+    return {
+      surface: 'helm',
+      name: r.kind === 'dead-marker' ? null : r.path,
+      file,
+      line_start: r.lineStart + 1, // 0-indexed -> 1-indexed
+      line_end: r.lineEnd + 1,
+      string: r.undocumented ? null : string,
+      declaration_text: null,
+      convention: CONVENTION,
+      meta
+    }
+  })
+}
+
+/**
+ * Extract helm declarations.
+ *
+ * @param {Object} options - { repo, files (Set of repo-relative paths, diff
+ *   mode; when omitted, scans charts/<*>/chart/values.yaml and
+ *   charts/<*>/values.yaml), log }
+ */
+function extract ({ repo, files = null }) {
+  let fileList
+  if (files) {
+    fileList = [...files]
+  } else {
+    fileList = []
+    const chartsRoot = path.join(repo, 'charts')
+    if (fs.existsSync(chartsRoot)) {
+      for (const entry of fs.readdirSync(chartsRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue
+        for (const candidate of [
+          path.join('charts', entry.name, 'chart', 'values.yaml'),
+          path.join('charts', entry.name, 'values.yaml')
+        ]) {
+          if (fs.existsSync(path.join(repo, candidate))) fileList.push(candidate)
+        }
+      }
+    }
+  }
+
+  const cache = new SourceCache(repo)
+  const declarations = []
+  for (const file of fileList) {
+    const absPath = path.isAbsolute(file) ? file : path.join(repo, file)
+    if (!fs.existsSync(absPath)) continue
+    const content = fs.readFileSync(absPath, 'utf8')
+    for (const decl of parseValuesFile(content, file)) {
+      decl.declaration_text = cache.span(file, decl.line_start, decl.line_end)
+      declarations.push(decl)
+    }
+  }
+  return declarations
+}
+
+/** Surface-specific convention rules. */
+const RULES = [
+  {
+    name: 'dead-marker',
+    description: 'A # -- marker no docs pipeline can attach to any key',
+    severity: 'error',
+    runOnUnverifiable: true,
+    check: (decl) => {
+      if (decl.meta.kind !== 'dead-marker') return []
+      return [{ message: 'This "# --" description is buried where neither helm-docs nor the helm-spec commented-values pass can attach it (inside another commented-out key\'s subtree, or separated from any key), so it silently never ships. Move it directly above the key it documents, use "# @doc full.path -- ...", or delete it.' }]
+    }
+  },
+  {
+    name: 'undocumented-top-level-key',
+    description: 'Top-level user-visible key with no # -- description',
+    severity: 'info',
+    runOnUnverifiable: true,
+    check: (decl) => {
+      if (decl.meta.kind !== 'key' || !decl.meta.undocumented) return []
+      return [{ message: `Top-level key "${decl.name}" has no "# --" description, so helm-docs ships it undocumented. Add a marker comment directly above it (or "# @ignored" if it is not user-facing).` }]
+    }
+  }
+]
+
+module.exports = {
+  name: 'helm',
+  convention: CONVENTION,
+  extract,
+  parseValuesFile,
+  rules: RULES
+}