@redpanda-data/docs-extensions-and-macros 5.51.2 → 5.52.0

package/tools/lint-strings/index.js

@@ -94,6 +94,8 @@ function lintStrings (options) {
   const pending = []
   let alreadyReviewed = 0
   let removal = { rawFiles: [], declarations: [] }
+  const skipped = []
+  let unverifiable = 0
 
   if (diffBase) {
     const { changed, removed } = getDiffLines(repoPath, diffBase)
@@ -137,9 +139,18 @@ function lintStrings (options) {
           continue
         }
         declarations.push(decl)
-        pending.push({ ...pendingEntry(decl), context: pageContext(decl, everything || head) })
+        if (decl.meta && decl.meta.unverifiable) unverifiable++
+        const detail = surface.reviewContext ? surface.reviewContext(decl) : null
+        pending.push({ ...pendingEntry(decl), ...(detail ? { detail } : {}), context: pageContext(decl, everything || head) })
       }
       results.push(runRules(declarations, rulesFor(surface), { skipRules, onlyRules }))
+      // Doc-method calls the extractor saw but could not trace, in the
+      // lines this diff changed. Reported so a gap is never silent.
+      const skippedHere = (everything ? everything.skipped : head.skipped) || []
+      for (const entry of skippedHere) {
+        const lines = files.get(entry.file)
+        if (lines && lines.has(entry.line)) skipped.push(entry)
+      }
     }
 
     removal = collectRemovals({ repoPath, diffBase, removed: removedBySurface, surfaces, requested, headBySurface, log })
@@ -151,7 +162,11 @@ function lintStrings (options) {
       const surface = SURFACES[surfaceName]
       log(`[${surfaceName}] extracting declarations from ${repoPath}...`)
       const declarations = surface.extract({ repo: repoPath, log })
-      for (const decl of declarations) decl.in_pr_diff = false
+      for (const decl of declarations) {
+        decl.in_pr_diff = false
+        if (decl.meta && decl.meta.unverifiable) unverifiable++
+      }
+      skipped.push(...(declarations.skipped || []))
       results.push(runRules(declarations, rulesFor(surface), { skipRules, onlyRules }))
     }
   }
@@ -168,6 +183,11 @@ function lintStrings (options) {
     merged.summary.alreadyReviewed = alreadyReviewed
   }
   merged.summary.removedDeclarations = removal.declarations.map(pendingEntry)
+  // Declarations whose text has gaps the extractor could not evaluate
+  // (rules that judge exact text skip them), and doc-method calls it could
+  // not attribute at all. Both are counted so a gap is never silent.
+  merged.summary.unverifiableDeclarations = unverifiable
+  merged.summary.skippedDeclarations = skipped
   const removedSurfaceFiles = [...removal.rawFiles, ...removedFilesFor(removal.declarations)]
     .sort((a, b) => a.surface.localeCompare(b.surface) || a.file.localeCompare(b.file))
   merged.summary.removedSurfaceFiles = removedSurfaceFiles
@@ -455,6 +475,12 @@ function formatHuman (result) {
     lines.push(`Lines deleted from doc-string surfaces: ${summary.removedSurfaceLines} ` +
       `(${summary.removedSurfaceFiles.length} file(s) with no extractor, so every deleted line counts)`)
   }
+  if (summary.unverifiableDeclarations) {
+    lines.push(`Declarations with text the extractor could not fully evaluate: ${summary.unverifiableDeclarations} (exact-text rules skipped)`)
+  }
+  for (const entry of summary.skippedDeclarations || []) {
+    lines.push(`Not extracted: ${entry.file}:${entry.line} .${entry.method}() (${entry.surface}): ${entry.reason}`)
+  }
   lines.push(`Errors: ${summary.errors}  Warnings: ${summary.warnings}  Info: ${summary.info}`)
   if (Object.keys(summary.byRule).length > 0) {
     lines.push('\nBy rule:')

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

@@ -59,8 +59,9 @@ function isNameEcho (name, description) {
  * 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;
+ *   * URLs, Markdown link targets, and AsciiDoc macro targets and anchor
+ *     ids - 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.
@@ -74,6 +75,13 @@ function maskNonProse (text) {
   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)
+  // AsciiDoc macro targets and anchor ids: xref:components:processors/
+  // schema_registry_encode.adoc[...] names a page, <<avro_raw_json,...>>
+  // and [[field_paths]] name an anchor. Backticking either breaks the link.
+  // The label in brackets stays prose.
+  out = out.replace(/\b(?:xref|link|image|include|glossterm|config_ref|anchor):[^\s[]*(?=\[)/g, blank)
+  out = out.replace(/<<[^,>]*/g, blank)
+  out = out.replace(/\[\[[^\]]*\]\]|\[#[^\]]*\]/g, blank)
   return out
 }