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

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 }