@redpanda-data/docs-extensions-and-macros 5.22.4 → 5.29.0

package/extensions/REFERENCE.adoc

@@ -574,9 +574,35 @@ Responses are classified as follows:
 * 401/403/429: unverifiable — logged at info level, because bot-walled or rate-limited sites are not broken
 * Other statuses, network errors, and timeouts (after one retry): unverifiable — logged as a warning
 
+=== What is not checked
+
+The extension runs at `contentClassified`, on raw AsciiDoc, before Asciidoctor converts anything. Three kinds of URL are therefore left alone, because checking them reports a broken link where the published page has no link at all:
+
+Code blocks::
+URLs inside a listing (`----`), literal (`....`), passthrough (`++++`) or fenced (`+```+`) block. A fenced block counts as one even when the opening delimiter carries a language info string, such as `+```bash+` or `+```yml+`.
+
+Comments::
+URLs on a line comment (`//`) or inside a comment block (`////`). Asciidoctor drops these before rendering, so a generator's provenance note, a Doc Detective test step, or a writer's editorial aside never becomes a link.
+
+Unresolved attribute references::
+A URL still holding a literal `{name}` reference, such as `+https://github.com/{project-github}/issues+`. Attributes are substituted after this hook runs, so the real target is unknown here while the published URL is usually fine. These are logged at info level with the pages that reference them, and counted separately, so a genuinely undefined attribute is still visible.
+
+=== Report attribution
+
+Each finding names the repository, branch, and path the URL was found in, for example:
+
+----
+Broken external link https://example.com/gone (HTTP 404) referenced in: redpanda-data/docs@main:modules/manage/pages/x.adoc
+----
+
+An aggregated site builds the same Antora-relative path from several repositories and many version branches, so a path on its own does not identify a file well enough to act on.
+
 === Environment variables
 
-This extension does not require any environment variables.
+LINK_CHECK::
+Set to `true` to check links. Without it the extension registers and does nothing, so it can live in a playbook that preview builds also use without those builds making network requests.
++
+This is an environment variable rather than a configuration option for two reasons: Antora does not interpolate environment variables into playbook values, and Antora consumes a playbook entry's own `enabled` key itself, before the config reaches the extension, so that name is not available.
 
 === Configuration options
 
@@ -589,6 +615,11 @@ List of regular expressions. When set, only URLs matching at least one pattern a
 exclude (optional)::
 List of regular expressions. URLs matching any pattern are skipped.
 
+versions (optional)::
+Which component versions to check. `latest` checks only each component's latest version, plus every unversioned component; `all` checks every version in the build. Default: `latest`.
++
+A site that publishes many versions of a component republishes the same dead link once per branch, and those older branches are frozen content that nobody edits, so checking them fills the report with findings that cannot be acted on.
+
 concurrency (optional)::
 Number of simultaneous requests. Default: `10`.
 
@@ -598,6 +629,9 @@ Per-request timeout in milliseconds. Default: `10000`.
 fail_on_broken (optional)::
 Log broken links at error level so a build run with `--log-failure-level=error` fails. Default: `false`.
 
+report_file (optional)::
+Path to write a machine-readable JSON report to. Unset by default, in which case no report is written. Written every time the checker runs, including when there is nothing to say, so a consumer polling for this file can tell a clean run apart from one where the checker never ran at all. The report holds `counts`, a `results` array sorted broken-first, and `unresolvedAttributeReferences`; each result carries the URL, its classification and status, and a `refs` array of `{repo, refname, component, version, path}`. Intended for automation that has to act on the findings rather than read them.
+
 === Registration
 
 Register the `external-link-checker` extension in the Antora playbook under the `antora.extensions` key like so:
@@ -607,9 +641,18 @@ Register the `external-link-checker` extension in the Antora playbook under the
 antora:
   extensions:
     - require: '@redpanda-data/docs-extensions-and-macros/extensions/external-link-checker'
+      versions: latest
+      report_file: link-check.json
       fail_on_broken: false
 ----
 
+That registration is inert on every build except one run with `LINK_CHECK=true`:
+
+[source,bash]
+----
+LINK_CHECK=true npx antora --fetch antora-playbook.yml
+----
+
 == Validate attributes
 
 This extension ensures the consistency and validity of page attributes, focusing on validating page categories against a predefined list of valid categories and subcategories. It automatically adds missing parent categories for any specified subcategories and removes any specified categories that are invalid. Additionally, it processes specific environment attributes, setting corresponding page-level attributes when environment conditions are met.

package/extensions/external-link-checker.js

@@ -1,5 +1,8 @@
 'use strict'
 
+const fs = require('fs')
+const path = require('path')
+
 const { scanContentUrls } = require('./util/scan-content-urls')
 const { raiseListenerLimit } = require('./util/raise-listener-limit')
 
@@ -20,16 +23,34 @@ const { raiseListenerLimit } = require('./util/raise-listener-limit')
  *       # internal_hostnames: ['docs.redpanda.com']  hosts to skip (default)
  *       # include: []          regex allowlist; when set, only matching URLs are checked
  *       # exclude: []          regex denylist
+ *       # versions: 'latest'   'latest' checks only each component's latest
+ *       #                      version (plus unversioned components); 'all'
+ *       #                      checks every version in the build
  *       # concurrency: 10      simultaneous requests
  *       # timeout: 10000       per-request timeout in ms
  *       # fail_on_broken: false  log broken links at error level so a build
  *       #                        run with --log-failure-level=error fails
+ *       # report_file: ''      path to write a machine-readable JSON report to
+ *
+ * Checking only happens when LINK_CHECK=true is set in the environment, so one
+ * playbook can serve both a scheduled link-check build and ordinary preview
+ * builds, which must not make network requests. It is an environment variable
+ * rather than a config option because Antora does not interpolate environment
+ * variables into playbook values, and because Antora consumes the playbook's
+ * own `enabled` key itself (generator-context.js strips it before the config
+ * reaches an extension), so that name is not available here.
  *
  * Classification:
  * - 2xx/3xx: ok
  * - 404/410: broken (warn, or error with fail_on_broken)
- * - 401/403/429: unverifiable (info) — bot-walled or rate-limited, not broken
+ * - 401/403/429: unverifiable (info) - bot-walled or rate-limited, not broken
  * - other statuses, network errors, timeouts (after one retry): unverifiable (warn)
+ *
+ * Why 'latest' is the default for versions: a site that publishes many
+ * versions of the same component republishes the same dead link once per
+ * branch, and the older branches are frozen content that nobody is going to
+ * edit. Checking them turns the report into a list of findings that cannot be
+ * acted on. Set versions: 'all' to see them anyway.
  */
 
 const USER_AGENT = 'redpanda-docs-link-checker'
@@ -37,59 +58,186 @@ const USER_AGENT = 'redpanda-docs-link-checker'
 module.exports.register = function ({ config = {} }) {
   raiseListenerLimit(this)
   const logger = this.getLogger('external-link-checker-extension')
+  // Inert unless asked for, so this can be registered in a playbook that
+  // preview builds also use. See the note above on why this is an environment
+  // variable and not a config option.
+  if (process.env.LINK_CHECK !== 'true') return
   const internalHostnames = new Set(config.internalHostnames || ['docs.redpanda.com'])
   const include = (config.include || []).map((pattern) => new RegExp(pattern))
   const exclude = (config.exclude || []).map((pattern) => new RegExp(pattern))
+  const versions = config.versions || 'latest'
   const concurrency = config.concurrency || 10
   const timeout = config.timeout || 10000
   const failOnBroken = Boolean(config.failOnBroken)
+  const reportFile = config.reportFile || null
 
   this.on('contentClassified', async ({ contentCatalog }) => {
-    const urlReferences = collectExternalUrls(contentCatalog, { internalHostnames, include, exclude })
-    if (!urlReferences.size) return
-    const counts = { ok: 0, broken: 0, unverifiable: 0 }
-    await runWithConcurrency([...urlReferences.keys()], concurrency, async (url) => {
-      const verdict = await checkUrl(url, { timeout })
-      counts[verdict.classification]++
-      const pages = [...urlReferences.get(url)].join(', ')
-      if (verdict.classification === 'broken') {
-        const message = `Broken external link ${url} (HTTP ${verdict.status}) referenced in: ${pages}`
-        failOnBroken ? logger.error(message) : logger.warn(message)
-      } else if (verdict.classification === 'unverifiable') {
-        const reason = verdict.status ? `HTTP ${verdict.status}` : verdict.reason
-        const log = verdict.status && [401, 403, 429].includes(verdict.status) ? 'info' : 'warn'
-        logger[log](`Could not verify external link ${url} (${reason}) referenced in: ${pages}`)
-      }
+    const { urlReferences, unresolved } = collectExternalUrls(contentCatalog, {
+      internalHostnames,
+      include,
+      exclude,
+      versions,
     })
-    logger.info(
-      `Checked ${urlReferences.size} external links: ${counts.ok} ok, ${counts.broken} broken, ` +
-        `${counts.unverifiable} unverifiable`
-    )
+    // An unresolved attribute reference is not a broken link. This hook runs
+    // before Asciidoctor substitutes attributes, so {latest-operator-version}
+    // is still literal here while the published URL is fine. Report the count
+    // so a genuinely undefined attribute is still visible, but never fetch.
+    if (unresolved.size) {
+      logger.info(
+        `Skipped ${unresolved.size} URL(s) holding an unresolved attribute reference ` +
+          '(attributes are substituted after this hook runs)'
+      )
+      for (const [url, refs] of unresolved) {
+        logger.info(`Unchecked external link ${url} (unresolved attribute) referenced in: ${formatRefs(refs)}`)
+      }
+    }
+    const counts = { ok: 0, broken: 0, unverifiable: 0 }
+    const results = []
+    // Nothing to fetch when every URL was internal, excluded, or an
+    // unresolved attribute reference. Still fall through to writeReport
+    // below: a consumer polling for report_file (the fixer workflow) cannot
+    // tell a clean, nothing-to-check build apart from one where the checker
+    // never ran unless the file always exists when configured.
+    if (urlReferences.size) {
+      await runWithConcurrency([...urlReferences.keys()], concurrency, async (url) => {
+        const verdict = await checkUrl(url, { timeout })
+        counts[verdict.classification]++
+        const refs = urlReferences.get(url)
+        results.push({
+          url,
+          classification: verdict.classification,
+          status: verdict.status ?? null,
+          reason: verdict.reason ?? null,
+          refs: [...refs.values()],
+        })
+        const pages = formatRefs(refs)
+        if (verdict.classification === 'broken') {
+          const message = `Broken external link ${url} (HTTP ${verdict.status}) referenced in: ${pages}`
+          failOnBroken ? logger.error(message) : logger.warn(message)
+        } else if (verdict.classification === 'unverifiable') {
+          const reason = verdict.status ? `HTTP ${verdict.status}` : verdict.reason
+          const log = verdict.status && [401, 403, 429].includes(verdict.status) ? 'info' : 'warn'
+          logger[log](`Could not verify external link ${url} (${reason}) referenced in: ${pages}`)
+        }
+      })
+      logger.info(
+        `Checked ${urlReferences.size} external links: ${counts.ok} ok, ${counts.broken} broken, ` +
+          `${counts.unverifiable} unverifiable`
+      )
+    }
+    if (reportFile) writeReport(reportFile, { results, unresolved, counts, logger })
   })
 }
 
-function collectExternalUrls (contentCatalog, { internalHostnames, include, exclude }) {
+/**
+ * Where a URL was found, in enough detail to act on it: which repository,
+ * which branch, and the path within that repository. A report line carrying
+ * only the Antora-relative path ('modules/reference/pages/x.adoc') is
+ * ambiguous across the several repositories and many version branches an
+ * aggregated site builds from, which makes it unusable for anything that has
+ * to open a pull request against the right one.
+ */
+function fileReference (file) {
+  const src = file.src || {}
+  const origin = src.origin || {}
+  const repo = repoSlug(origin.url)
+  const startPath = origin.startPath || ''
+  const repoPath = startPath ? `${startPath}/${file.path}` : file.path
+  const refname = origin.refname || origin.branch || origin.tag || ''
+  const ref = {
+    repo,
+    refname,
+    component: src.component || '',
+    version: src.version || '',
+    path: repoPath,
+  }
+  // Without origin metadata (a synthetic catalog, or a local content source
+  // with no git remote) the path is all there is to report.
+  const label = repo ? `${repo}${refname ? `@${refname}` : ''}:${repoPath}` : repoPath
+  return { label, ref }
+}
+
+/** 'https://github.com/redpanda-data/docs.git' -> 'redpanda-data/docs' */
+function repoSlug (url) {
+  if (!url || typeof url !== 'string') return ''
+  const match = url.match(/[/:]([^/:]+)\/([^/]+?)(?:\.git)?\/?$/)
+  return match ? `${match[1]}/${match[2]}` : ''
+}
+
+function formatRefs (refs) {
+  return [...refs.keys()].join(', ')
+}
+
+/**
+ * Maps each component to its latest version, so non-latest content can be
+ * skipped. Catalogs without getComponents (unit-test doubles) fall back to
+ * checking everything.
+ */
+function latestVersions (contentCatalog) {
+  if (typeof contentCatalog.getComponents !== 'function') return null
+  const latest = new Map()
+  for (const component of contentCatalog.getComponents()) {
+    latest.set(component.name, component.latest ? component.latest.version : '')
+  }
+  return latest
+}
+
+function collectExternalUrls (contentCatalog, { internalHostnames, include, exclude, versions = 'all' }) {
   const urlReferences = new Map()
+  const unresolved = new Map()
+  const latest = versions === 'latest' ? latestVersions(contentCatalog) : null
   const files = contentCatalog
     .getPages((page) => page.out)
     .concat(contentCatalog.findBy({ family: 'partial' }))
   for (const file of files) {
     if (!file.contents) continue
+    const src = file.src || {}
+    // An unversioned component has an empty version and is always current.
+    if (latest && src.version && latest.has(src.component) && latest.get(src.component) !== src.version) continue
+    const { label, ref } = fileReference(file)
     for (const match of scanContentUrls(file.contents.toString())) {
-      let url
-      try {
-        url = new URL(match.url)
-      } catch {
-        continue
+      const target = match.hasAttributeReference ? unresolved : urlReferences
+      if (!match.hasAttributeReference) {
+        let url
+        try {
+          url = new URL(match.url)
+        } catch {
+          continue
+        }
+        if (internalHostnames.has(url.hostname)) continue
+        if (include.length && !include.some((pattern) => pattern.test(match.url))) continue
+        if (exclude.some((pattern) => pattern.test(match.url))) continue
       }
-      if (internalHostnames.has(url.hostname)) continue
-      if (include.length && !include.some((pattern) => pattern.test(match.url))) continue
-      if (exclude.some((pattern) => pattern.test(match.url))) continue
-      if (!urlReferences.has(match.url)) urlReferences.set(match.url, new Set())
-      urlReferences.get(match.url).add(file.path)
+      if (!target.has(match.url)) target.set(match.url, new Map())
+      target.get(match.url).set(label, ref)
     }
   }
-  return urlReferences
+  return { urlReferences, unresolved }
+}
+
+function writeReport (reportFile, { results, unresolved, counts, logger }) {
+  const report = {
+    generatedAt: new Date().toISOString(),
+    counts,
+    // Broken first, then unverifiable, so a consumer reading the head of the
+    // list gets the actionable findings.
+    results: results.sort((a, b) => rank(a.classification) - rank(b.classification) || a.url.localeCompare(b.url)),
+    unresolvedAttributeReferences: [...unresolved].map(([url, refs]) => ({ url, refs: [...refs.values()] })),
+  }
+  try {
+    const dir = path.dirname(reportFile)
+    if (dir && dir !== '.') fs.mkdirSync(dir, { recursive: true })
+    fs.writeFileSync(reportFile, `${JSON.stringify(report, null, 2)}\n`)
+    logger.info(`Wrote link check report to ${reportFile}`)
+  } catch (error) {
+    // The report is an aid for downstream automation; failing the build over
+    // it would hide the link findings the build just produced.
+    logger.warn(`Could not write link check report to ${reportFile}: ${error.message}`)
+  }
+}
+
+function rank (classification) {
+  return classification === 'broken' ? 0 : classification === 'unverifiable' ? 1 : 2
 }
 
 async function checkUrl (url, { timeout, fetchFn = module.exports._fetch }) {
@@ -130,3 +278,4 @@ async function runWithConcurrency (items, limit, task) {
 module.exports._fetch = (...args) => fetch(...args)
 module.exports.checkUrl = checkUrl
 module.exports.collectExternalUrls = collectExternalUrls
+module.exports.repoSlug = repoSlug

package/extensions/url-to-xref.js

@@ -483,6 +483,11 @@ function convertContent (content, resolverContext) {
       continue
     }
     if (!hostnames.has(url.hostname) || match.inAttributeEntry || match.inAttributeValue) continue
+    // The path still holds a literal {attribute} reference: attributes are
+    // substituted after this hook, so the real target is unknown here. It
+    // cannot be looked up in the catalog, and reporting it as unmatched would
+    // be wrong when the substituted URL resolves fine.
+    if (match.hasAttributeReference) continue
     if (ignore.some((pattern) => pattern.test(url.pathname))) continue
     // An xref target cannot carry a query string, and dropping one would
     // change the link: the docs UI reads parameters such as

package/extensions/util/scan-content-urls.js

@@ -2,12 +2,26 @@
 
 /**
  * Scans AsciiDoc content for http(s) URLs that appear in prose, skipping
- * URLs inside code contexts where rewriting or checking them would be wrong:
+ * URLs that never reach a rendered page, or that live in a code context where
+ * rewriting or checking them would be wrong:
  *
- * - delimited listing (----), literal (....), fenced (```), and passthrough
- *   (++++) blocks
+ * - delimited listing (----), literal (....), passthrough (++++) and comment
+ *   (////) blocks
+ * - fenced blocks (```), including a language info string (```bash, ```yml).
+ *   Asciidoctor treats the info string as part of the delimiter, so a fence
+ *   opened as ```bash still closes on a bare ``` line
+ *
+ * A block closes only on a delimiter of the same length as the one that opened
+ * it; a longer run, such as the row of dashes in a rendered table, is content.
+ * - line comments (//), which Asciidoctor drops entirely
  * - inline code spans (`...`)
  *
+ * URLs holding an unresolved attribute reference (https://github.com/{project-github}/...)
+ * are returned with hasAttributeReference set, because a caller cannot check
+ * or rewrite one: this scanner runs at contentClassified, before Asciidoctor
+ * substitutes attributes, so the braces are still literal here even though the
+ * published URL is fine.
+ *
  * Each match records enough position information for a caller to splice a
  * replacement into the original content.
  *
@@ -26,6 +40,8 @@
  *   example image:d.png[alt,link=https://...]); rewriting one of these to an
  *   xref macro would corrupt the surrounding macro, but the URL is still a
  *   real link target worth checking
+ * - hasAttributeReference: true when the URL contains a {name} attribute
+ *   reference that has not been substituted yet
  */
 
 const URL_RX = /(link:)?(https?:\/\/[^\s\][)"'<>]+)(\[[^\]]*\])?/g
@@ -34,16 +50,62 @@ const URL_RX = /(link:)?(https?:\/\/[^\s\][)"'<>]+)(\[[^\]]*\])?/g
 // is not part of the URL.
 const TRAILING_PUNCT_RX = /[.,;:!?*_]+$/
 const ATTRIBUTE_ENTRY_RX = /^:!?[a-zA-Z0-9_][a-zA-Z0-9_-]*!?:(?:\s|$)/
+// A line comment. Asciidoctor drops these before rendering, so any URL on one
+// is not a link on the published page: generator provenance notes, Doc
+// Detective test steps, and writers' editorial asides all live here.
+const LINE_COMMENT_RX = /^\s*\/\//
+// An attribute reference that substitution has not resolved yet.
+const ATTRIBUTE_REFERENCE_RX = /\{[a-zA-Z0-9_][a-zA-Z0-9_-]*\}/
 // Cap on how far a wrapped label may run, so an unmatched bracket somewhere in
 // prose cannot swallow the rest of the document.
 const MAX_WRAPPED_LABEL_LENGTH = 500
 
+// A delimiter run, plus the info string a fence may carry. Comment blocks
+// (////) come first in the alternation so a //// line is not mistaken for the
+// start of a line comment.
+// A markdown-style fence is exactly three backticks: Asciidoctor does not
+// recognise four or more, it reads them as a paragraph. The other
+// delimiters take four or more.
+const BLOCK_DELIMITER_RX = /^(\/{4,}|-{4,}|\.{4,}|`{3}(?!`)|\+{4,})(\S*)$/
+
+/**
+ * Parses a block delimiter line, or returns null when the line is not one.
+ *
+ * Two details of Asciidoctor's rules matter here, and both were verified
+ * against @asciidoctor/core rather than assumed:
+ *
+ * - A fenced block may carry a language info string (```bash, ```yml) on its
+ *   opening line. Matching only bare backticks meant every annotated code
+ *   block was scanned as prose, which is where the config defaults
+ *   (https://api.openai.com/v1) and the truncated shell examples
+ *   (.../releases/download/v, cut at its <version> placeholder) in the weekly
+ *   report came from. No other delimiter takes an info string.
+ * - A block closes only on a delimiter of the SAME LENGTH. A longer run is
+ *   content. Treating any run of four or more as a delimiter inverted the
+ *   open/closed state for the rest of the file whenever a listing block held
+ *   a line of dashes, which is how command output renders a table rule:
+ *
+ *     [source,sql]
+ *     ----
+ *     SELECT ...
+ *     ----------------------   <- content, not a close
+ *      row
+ *     ----                     <- the actual close
+ *
+ *   Everything after such a block was then read with the state flipped, so
+ *   prose was skipped and code was scanned. That is why the example URL in
+ *   cloud-docs' regexp_match reference was reported as a broken link.
+ */
 function blockDelimiter (line) {
-  if (/^-{4,}$/.test(line)) return '-'
-  if (/^\.{4,}$/.test(line)) return '.'
-  if (/^`{3,}$/.test(line)) return '`'
-  if (/^\+{4,}$/.test(line)) return '+'
-  return null
+  const match = BLOCK_DELIMITER_RX.exec(line)
+  if (!match) return null
+  const [, run, info] = match
+  if (info && run[0] !== '`') return null
+  return { char: run[0], length: run.length, info }
+}
+
+function closesBlock (delimiter, open) {
+  return delimiter.char === open.char && delimiter.length === open.length && !delimiter.info
 }
 
 function scanContentUrls (content) {
@@ -54,10 +116,13 @@ function scanContentUrls (content) {
   for (const rawLine of lines) {
     const line = rawLine.endsWith('\r') ? rawLine.slice(0, -1) : rawLine
     const delimiter = blockDelimiter(line)
-    if (delimiter) {
-      if (openDelimiter === delimiter) openDelimiter = null
-      else if (!openDelimiter) openDelimiter = delimiter
-    } else if (!openDelimiter) {
+    if (openDelimiter) {
+      // Inside a block, only its own matching delimiter gets out. Anything
+      // else on this line is content and is never scanned.
+      if (delimiter && closesBlock(delimiter, openDelimiter)) openDelimiter = null
+    } else if (delimiter) {
+      openDelimiter = delimiter
+    } else if (!LINE_COMMENT_RX.test(line)) {
       scanLine(line, offset, matches, content)
     }
     offset += rawLine.length + 1
@@ -114,6 +179,7 @@ function scanLine (line, offset, matches, content) {
       hasLinkPrefix: Boolean(linkPrefix),
       inAttributeEntry,
       inAttributeValue: /[\w-]=["']?$/.test(before),
+      hasAttributeReference: ATTRIBUTE_REFERENCE_RX.test(url),
     })
   }
 }

package/extensions/version-fetcher/set-latest-version.js

@@ -218,10 +218,15 @@ module.exports.register = function ({ config }) {
     return version.replace(/^v/, '');
   }
 
-  // Helper function to update multiple attributes based on a list of mappings
+  // Helper function to update multiple attributes based on a list of mappings.
+  // Gated on the value, not just the condition: gating on the enclosing object
+  // alone assigned `undefined` whenever the fetch returned an object without
+  // the field, and that clobbered the antora.yml fallback instead of falling
+  // back to it. The visible symptom was a literal {latest-operator-version} in
+  // the published release-notes pages.
   function updateAttributes(asciidoc, mappings) {
     mappings.forEach(({ condition, key, value }) => {
-      if (condition) {
+      if (condition && value) {
         asciidoc.attributes[key] = value;
         setShortVersionAttribute(asciidoc, key, value);
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "5.22.4",
+  "version": "5.29.0",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",

package/tools/lint-strings/diff.js

@@ -50,6 +50,13 @@ function routeFile (file) {
  * @returns {Map<string, Set<number>>}
  */
 function getChangedLines (repo, base) {
+  return parseUnifiedDiff(runGitDiff(repo, base))
+}
+
+/**
+ * Run `git diff <base>...HEAD` and return the raw text.
+ */
+function runGitDiff (repo, base) {
   const result = spawnSync(
     'git',
     ['diff', '--unified=0', '--no-color', `${base}...HEAD`],
@@ -59,7 +66,17 @@ function getChangedLines (repo, base) {
   if (result.status !== 0) {
     throw new Error(`git diff ${base}...HEAD failed in ${repo}: ${result.stderr || result.stdout}`)
   }
-  return parseUnifiedDiff(result.stdout)
+  return result.stdout
+}
+
+/**
+ * Both sides of the diff from a single git invocation.
+ *
+ * @returns {{ changed: Map<string, Set<number>>, removed: Map<string, Set<number>> }}
+ */
+function getDiffLines (repo, base) {
+  const diffText = runGitDiff(repo, base)
+  return { changed: parseUnifiedDiff(diffText), removed: parseUnifiedDiffRemovals(diffText) }
 }
 
 /**
@@ -98,6 +115,53 @@ function parseUnifiedDiff (diffText) {
   return changed
 }
 
+/**
+ * Parse unified diff text into file -> Set(deleted PRE-image line numbers),
+ * keyed by the old path. This is the half parseUnifiedDiff deliberately throws
+ * away, and on its own it is what keeps a deletion-only PR visible.
+ *
+ * Why it is needed: declarations are extracted from HEAD, so a removed
+ * property, metric or command cannot be extracted at all, and a pure-deletion
+ * hunk contributes no post-image lines to anchor on. Without the old side, a
+ * PR that only deletes doc-string declarations reports zero declarations and
+ * every downstream review step skips, precisely when a removed public surface
+ * is the most doc-relevant change a PR can make.
+ *
+ * These line numbers are a signal that a doc-string surface lost content, not
+ * an extraction: naming them as declarations would overstate what a diff alone
+ * can tell us.
+ */
+function parseUnifiedDiffRemovals (diffText) {
+  const removed = new Map()
+  const lines = diffText.split('\n')
+  let oldFile = null
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    // git always emits the ---/+++ header pair on consecutive lines, so
+    // requiring the partner keeps a deleted source line that happens to start
+    // with "-- " from being misread as a header (the mirror of the "++ "
+    // hazard noted in parseUnifiedDiff).
+    if (line.startsWith('--- ') && (lines[i + 1] || '').startsWith('+++ ')) {
+      oldFile = line.startsWith('--- a/') ? line.slice(6).trim() : null
+      continue
+    }
+    if (!line.startsWith('@@') || oldFile === null) continue
+
+    const hunk = line.match(/^@@ -(\d+)(?:,(\d+))? \+\d+(?:,\d+)? @@/)
+    if (!hunk) continue
+    const start = parseInt(hunk[1], 10)
+    const count = hunk[2] === undefined ? 1 : parseInt(hunk[2], 10)
+    if (count === 0) continue // pure addition: nothing removed
+
+    if (!removed.has(oldFile)) removed.set(oldFile, new Set())
+    const lineSet = removed.get(oldFile)
+    for (let i2 = 0; i2 < count; i2++) lineSet.add(start + i2)
+  }
+
+  return removed
+}
+
 /**
  * Group changed files by surface.
  *
@@ -131,7 +195,9 @@ module.exports = {
   SURFACE_ROUTES,
   routeFile,
   getChangedLines,
+  getDiffLines,
   parseUnifiedDiff,
+  parseUnifiedDiffRemovals,
   classifyDiff,
   spanIntersects
 }

package/tools/lint-strings/engine.js

@@ -99,6 +99,12 @@ function emptySummary () {
   return {
     totalDeclarations: 0,
     flaggedDeclarations: 0,
+    // Deletions on the old side of the diff, in files that route to a
+    // doc-string surface. Only populated in diff mode. See
+    // parseUnifiedDiffRemovals in ./diff.js for why a removed declaration
+    // cannot be counted in totalDeclarations.
+    removedSurfaceLines: 0,
+    removedSurfaceFiles: [],
     errors: 0,
     warnings: 0,
     info: 0,

package/tools/lint-strings/index.js

@@ -4,7 +4,7 @@ const fs = require('fs')
 const path = require('path')
 
 const { runRules, mergeResults } = require('./engine')
-const { getChangedLines, classifyDiff, spanIntersects, SURFACE_ROUTES } = require('./diff')
+const { getDiffLines, classifyDiff, spanIntersects, SURFACE_ROUTES } = require('./diff')
 const { COMMON_RULES } = require('./rules/common')
 const { VERBATIM_ASCIIDOC_RULES } = require('./rules/verbatim-asciidoc')
 
@@ -82,10 +82,12 @@ function lintStrings (options) {
 
   const results = []
   const unsupportedSurfaces = []
+  let removedSurfaceFiles = []
 
   if (diffBase) {
-    const changed = getChangedLines(repoPath, diffBase)
+    const { changed, removed } = getDiffLines(repoPath, diffBase)
     const classified = classifyDiff(changed)
+    removedSurfaceFiles = collectRemovals(removed, surfaces)
 
     for (const [surfaceName, files] of Object.entries(classified)) {
       if (!SURFACES[surfaceName]) {
@@ -119,9 +121,33 @@ function lintStrings (options) {
   merged.findings.sort((a, b) =>
     a.surface.localeCompare(b.surface) || a.file.localeCompare(b.file) || (a.line_start || 0) - (b.line_start || 0))
   merged.unsupported_surfaces = unsupportedSurfaces
+  merged.summary.removedSurfaceFiles = removedSurfaceFiles
+  merged.summary.removedSurfaceLines = removedSurfaceFiles.reduce((sum, entry) => sum + entry.lines, 0)
   return merged
 }
 
+/**
+ * Deletions in files that route to a doc-string surface, so a deletion-only PR
+ * still registers as touching a surface. Reported separately from
+ * totalDeclarations because a removed declaration is absent from HEAD and
+ * therefore cannot be extracted or linted.
+ *
+ * Surfaces routed without a registered extractor are included: the gate cares
+ * that documented content went away, not whether we can lint what replaced it.
+ *
+ * @param {Map<string, Set<number>>} removed - From getDiffLines().removed
+ * @param {string[]|null} surfaces - Explicit --surface narrowing, if any
+ */
+function collectRemovals (removed, surfaces) {
+  const only = surfaces && surfaces.length > 0 ? new Set(surfaces) : null
+  const entries = []
+  for (const [surface, files] of Object.entries(classifyDiff(removed))) {
+    if (only && !only.has(surface)) continue
+    for (const [file, lines] of files) entries.push({ surface, file, lines: lines.size })
+  }
+  return entries.sort((a, b) => a.surface.localeCompare(b.surface) || a.file.localeCompare(b.file))
+}
+
 /**
  * Human-readable report (the default --format).
  */
@@ -148,6 +174,10 @@ function formatHuman (result) {
   lines.push('='.repeat(60))
   lines.push(`Declarations checked: ${summary.totalDeclarations}`)
   lines.push(`Declarations flagged: ${summary.flaggedDeclarations}`)
+  if (summary.removedSurfaceLines) {
+    lines.push(`Lines deleted from doc-string surfaces: ${summary.removedSurfaceLines} ` +
+      `(${summary.removedSurfaceFiles.length} file(s); removed declarations cannot be extracted from HEAD)`)
+  }
   lines.push(`Errors: ${summary.errors}  Warnings: ${summary.warnings}  Info: ${summary.info}`)
   if (Object.keys(summary.byRule).length > 0) {
     lines.push('\nBy rule:')

package/tools/property-extractor/property_extractor.py

@@ -1117,6 +1117,49 @@ def apply_property_overrides(properties, overrides, overrides_file_path=None):
     return properties
 
 
+ADMONITION_TYPES = {"note", "tip", "important", "warning", "caution"}
+
+
+def _normalize_admonitions(admonitions):
+    """Validate an admonitions override and normalize each entry's `type`
+    to the uppercase form AsciiDoc's admonition block syntax expects
+    (`[NOTE]`, not `[note]`). Returns None (logging a warning) if the
+    override isn't shaped as a list of {type, text} entries, so a malformed
+    override doesn't silently render as nothing instead of surfacing the
+    mistake.
+    """
+    if not isinstance(admonitions, list):
+        logger.warning("admonitions for property must be an array")
+        return None
+    normalized = []
+    for entry in admonitions:
+        if (
+            not isinstance(entry, dict)
+            or not isinstance(entry.get("type"), str)
+            or not isinstance(entry.get("text"), str)
+        ):
+            logger.warning(
+                f"admonitions entry must contain string type and text values, got: {entry!r}"
+            )
+            continue
+        entry_type = str(entry["type"]).strip().lower()
+        if entry_type not in ADMONITION_TYPES:
+            logger.warning(
+                f"admonitions entry has unknown type '{entry['type']}', "
+                f"expected one of {sorted(ADMONITION_TYPES)}"
+            )
+            continue
+        normalized_entry = {"type": entry_type.upper(), "text": entry["text"]}
+        if "title" in entry:
+            if not isinstance(entry["title"], str):
+                logger.warning(f"admonitions entry title must be a string, got: {entry!r}")
+                continue
+            if entry["title"]:
+                normalized_entry["title"] = entry["title"]
+        normalized.append(normalized_entry)
+    return normalized
+
+
 def _apply_override_to_existing_property(property_dict, override, overrides_file_path):
     """Apply overrides to an existing property."""
     # Apply description override
@@ -1178,6 +1221,16 @@ def _apply_override_to_existing_property(property_dict, override, overrides_file
         else:
             logger.warning(f"accepted_values for property must be an array")
 
+    # Apply admonitions override - structured NOTE/TIP/IMPORTANT/WARNING/CAUTION
+    # callouts, rendered as real AsciiDoc admonition blocks by property.hbs/
+    # topic-property.hbs. Exists so a callout never has to be hand-written as
+    # markup mixed into the description text -- see minimize-overrides
+    # guidance: an admonition is structured data, not embedded prose markup.
+    if "admonitions" in override:
+        normalized = _normalize_admonitions(override["admonitions"])
+        if normalized is not None:
+            property_dict["admonitions"] = normalized
+
 
 def _create_property_from_override(prop_name, override, overrides_file_path):
     """Create a new property from override specification."""
@@ -1222,7 +1275,7 @@ def _create_property_from_override(prop_name, override, overrides_file_path):
         if key not in ["description", "type", "default", "config_scope", "version",
                        "example", "example_file", "example_yaml", "related_topics",
                        "see_also", "is_deprecated", "visibility", "exclude_from_docs",
-                       "category", "accepted_values", "_comment"]:
+                       "category", "accepted_values", "admonitions", "_comment"]:
             new_property[key] = value
 
     # Add exclude_from_docs if specified
@@ -1240,6 +1293,14 @@ def _create_property_from_override(prop_name, override, overrides_file_path):
         else:
             logger.warning(f"accepted_values for property '{prop_name}' must be an array")
 
+    # Add admonitions if specified - run through the same validation/normalization
+    # as the existing-property path so a malformed entry is dropped with a warning
+    # rather than silently rendering as an unstyled, lowercase-typed block.
+    if "admonitions" in override:
+        normalized = _normalize_admonitions(override["admonitions"])
+        if normalized is not None:
+            new_property["admonitions"] = normalized
+
     return new_property
 
 

package/tools/property-extractor/templates/property.hbs

@@ -27,6 +27,18 @@ endif::[]
 
 No description available.
 
+{{/if}}
+{{#if admonitions}}
+{{#each admonitions}}
+
+{{#if title}}
+.{{{title}}}
+{{/if}}
+[{{type}}]
+====
+{{{text}}}
+====
+{{/each}}
 {{/if}}
 {{#if is_enterprise}}
 

package/tools/property-extractor/templates/topic-property.hbs

@@ -25,6 +25,18 @@
 
 No description available.
 
+{{/if}}
+{{#if admonitions}}
+{{#each admonitions}}
+
+{{#if title}}
+.{{{title}}}
+{{/if}}
+[{{type}}]
+====
+{{{text}}}
+====
+{{/each}}
 {{/if}}
 {{#if is_enterprise}}