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

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

@@ -0,0 +1,233 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+const { SourceCache } = require('../source-text')
+const {
+  maskComments,
+  findBalancedClose,
+  splitTopLevelArgs,
+  collectStringConsts,
+  evalStringExpr,
+  lineOf,
+  collectGoFiles
+} = require('../go-source')
+
+/**
+ * Connect surface: service.NewConfigSpec() Summary/Description strings and
+ * service.NewXField(name).Description(...) chains in internal/impl.
+ *
+ * These strings are AsciiDoc page bodies (connect docs are generated from
+ * them directly), so AsciiDoc constructs are LEGITIMATE here: `==` headings,
+ * links, code fences, and the `raw + "`literal`" + raw` backtick
+ * concatenation idiom all appear in healthy descriptions. The scanner
+ * evaluates Go string concatenation (raw strings, interpreted strings, and
+ * same-file constants) so those idioms resolve to the exact shipped text.
+ * Descriptions built from calls or cross-file values are skipped silently -
+ * suggest-only posture means silence beats guessing.
+ *
+ * Because a connect description IS the page body (not a table cell), the
+ * verbatim raw-pipe rule is skipped: a bare `|` is valid AsciiDoc table
+ * syntax in this position.
+ */
+
+const CONVENTION = {
+  case: 'sentence',
+  terminal_period: true,
+  verbatim_asciidoc: true
+}
+
+// Field constructors that ship with NO built-in documentation: a chain on
+// one of these without .Description() publishes an empty field description.
+// Composite helpers (NewTLSToggledField, NewAutoRetryNacksToggleField,
+// NewBatchPolicyField, ...) carry their own docs and are exempt.
+const BARE_FIELD_CTORS = new Set([
+  'NewStringField', 'NewStringListField', 'NewStringMapField',
+  'NewStringEnumField', 'NewStringAnnotatedEnumField',
+  'NewIntField', 'NewIntListField', 'NewIntMapField',
+  'NewFloatField', 'NewBoolField', 'NewDurationField',
+  'NewInterpolatedStringField', 'NewInterpolatedStringListField',
+  'NewInterpolatedStringMapField', 'NewInterpolatedStringEnumField',
+  'NewBloblangField', 'NewAnyField', 'NewAnyListField', 'NewAnyMapField',
+  'NewObjectField', 'NewObjectListField', 'NewURLField'
+])
+
+const FIELD_CTOR = /\bNew([A-Z][A-Za-z0-9]*)Field\s*\(/g
+const CONFIG_SPEC = /\bNewConfigSpec\s*\(\s*\)/g
+const REGISTER_NAME = /\b(?:Must)?Register\w*\(\s*(?:"([^"]+)"|`([^`]+)`)\s*,/
+
+/**
+ * Follow a builder chain starting right after `startIndex` (the index just
+ * past a closing paren): repeated `.Method(args)`. Returns
+ * [{ method, args, openIndex, closeIndex }] and the chain end offset.
+ */
+function readChain (masked, startIndex) {
+  const calls = []
+  let i = startIndex
+  for (;;) {
+    const rest = masked.slice(i)
+    const m = rest.match(/^\s*\.\s*([A-Za-z0-9_]+)\s*\(/)
+    if (!m) break
+    const openIndex = i + m[0].length - 1
+    const closeIndex = findBalancedClose(masked, openIndex)
+    if (closeIndex === -1) break
+    calls.push({
+      method: m[1],
+      args: masked.slice(openIndex + 1, closeIndex),
+      openIndex,
+      closeIndex
+    })
+    i = closeIndex + 1
+  }
+  return { calls, end: i }
+}
+
+/**
+ * Scan one file's content for connect declarations. Exported for tests.
+ */
+function scanFile (content, file) {
+  const declarations = []
+  const masked = maskComments(content)
+  const consts = collectStringConsts(masked)
+
+  // Component name: the registration literal, when the file has exactly one.
+  const registerMatches = [...masked.matchAll(new RegExp(REGISTER_NAME.source, 'g'))]
+  const componentName = registerMatches.length === 1
+    ? (registerMatches[0][1] || registerMatches[0][2])
+    : null
+
+  // ConfigSpec chains -> Summary / Description declarations.
+  CONFIG_SPEC.lastIndex = 0
+  let match
+  while ((match = CONFIG_SPEC.exec(masked)) !== null) {
+    const { calls } = readChain(masked, match.index + match[0].length)
+    for (const call of calls) {
+      if (call.method !== 'Summary' && call.method !== 'Description') continue
+      const result = evalStringExpr(call.args, consts)
+      if (!result.verifiable) continue // built dynamically; skip silently
+      declarations.push({
+        surface: 'connect',
+        name: componentName,
+        file,
+        line_start: lineOf(masked, call.openIndex),
+        line_end: lineOf(masked, call.closeIndex),
+        string: result.value.trim() === '' ? null : result.value.trim(),
+        declaration_text: null,
+        convention: CONVENTION,
+        meta: { kind: call.method.toLowerCase() }
+      })
+    }
+  }
+
+  // Field constructor chains -> field description declarations.
+  FIELD_CTOR.lastIndex = 0
+  while ((match = FIELD_CTOR.exec(masked)) !== null) {
+    const ctor = `New${match[1]}Field`
+    const openIndex = match.index + match[0].length - 1
+    const closeIndex = findBalancedClose(masked, openIndex)
+    if (closeIndex === -1) continue
+
+    const ctorArgs = splitTopLevelArgs(masked.slice(openIndex + 1, closeIndex))
+    const nameResult = ctorArgs.length > 0 ? evalStringExpr(ctorArgs[0], consts) : { verifiable: false, value: null }
+    const fieldName = nameResult.verifiable ? nameResult.value : null
+
+    const { calls, end } = readChain(masked, closeIndex + 1)
+    const descriptionCall = calls.find((c) => c.method === 'Description')
+
+    if (descriptionCall) {
+      const result = evalStringExpr(descriptionCall.args, consts)
+      if (result.verifiable) {
+        declarations.push({
+          surface: 'connect',
+          name: fieldName,
+          file,
+          line_start: lineOf(masked, match.index),
+          line_end: lineOf(masked, descriptionCall.closeIndex),
+          string: result.value.trim() === '' ? null : result.value.trim(),
+          declaration_text: null,
+          convention: CONVENTION,
+          meta: { kind: 'field', ctor }
+        })
+      }
+      // Unverifiable description: skip silently (cross-file constant or call).
+    } else if (BARE_FIELD_CTORS.has(ctor) && !calls.some((c) => c.method === 'Deprecated')) {
+      // Deprecated fields are not part of the user-facing docs contract.
+      // A bare constructor with no Description() anywhere in its chain
+      // ships an empty field description.
+      declarations.push({
+        surface: 'connect',
+        name: fieldName,
+        file,
+        line_start: lineOf(masked, match.index),
+        line_end: lineOf(masked, Math.max(closeIndex, end - 1)),
+        string: null,
+        declaration_text: null,
+        convention: CONVENTION,
+        meta: { kind: 'field', ctor, missing_description: true }
+      })
+    }
+    // Resume INSIDE the constructor args: object fields nest child field
+    // constructors (NewObjectField("x", NewStringField("y")...)).
+    FIELD_CTOR.lastIndex = openIndex + 1
+  }
+
+  return declarations
+}
+
+/**
+ * Extract connect declarations.
+ *
+ * @param {Object} options - { repo, files (Set of repo-relative paths, diff
+ *   mode; when omitted, scans internal/impl), log }
+ */
+function extract ({ repo, files = null }) {
+  const IMPL_ROOT = path.join('internal', 'impl')
+  let fileList
+  if (files) {
+    fileList = [...files].filter((f) => f.endsWith('.go') && !f.endsWith('_test.go'))
+  } else {
+    fileList = collectGoFiles(path.join(repo, IMPL_ROOT)).map((f) => path.join(IMPL_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('Field(') && !content.includes('NewConfigSpec')) continue
+    for (const decl of scanFile(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: 'missing-field-description',
+    description: 'Config field constructed with no .Description()',
+    severity: 'warning',
+    check: (decl) => {
+      if (decl.meta.kind !== 'field' || !decl.meta.missing_description) return []
+      return [{ message: `Field ${decl.name ? `"${decl.name}" ` : ''}(${decl.meta.ctor}) has no .Description(). It ships as an undocumented field on the connector page.` }]
+    }
+  }
+]
+
+module.exports = {
+  name: 'connect',
+  convention: CONVENTION,
+  extract,
+  scanFile,
+  rules: RULES,
+  // A connect description is the AsciiDoc page body, not a table cell:
+  // bare | is legitimate table syntax there, and missing prose is handled
+  // by the connect-specific missing-field-description warning. Brace
+  // placeholders ({endpoint}, {my-domain}) are the established URL-template
+  // idiom in connect descriptions, so the unknown-attribute check is noise.
+  skipRules: ['raw-pipe', 'empty-description', 'unknown-attribute']
+}

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
+}