@redpanda-data/docs-extensions-and-macros 5.23.0 → 5.30.0

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

@@ -16,7 +16,12 @@ module.exports.register = function ({ config }) {
   const token = getGitHubToken();
 
   if (!token) {
-    logger.warn('GitHub token not set (REDPANDA_GITHUB_TOKEN, GITHUB_TOKEN, or GH_TOKEN). Attempting unauthenticated request.');
+    // Unauthenticated requests still work for the public repos this
+    // extension queries (connect, redpanda-operator), but the Redpanda
+    // version now comes from the private streaming-enterprise repo, whose
+    // API 404s without a token -- the latest-redpanda-* attributes are then
+    // left unset and pages fall back to their antora.yml values.
+    logger.warn('GitHub token not set (GIT_CREDENTIALS, REDPANDA_GITHUB_TOKEN, GITHUB_TOKEN, or GH_TOKEN). The Redpanda version lookup against the private streaming-enterprise repo will fail and leave latest-redpanda-* attributes unset; other lookups proceed unauthenticated.');
   }
 
   this.on('contentClassified', async ({ contentCatalog }) => {
@@ -41,7 +46,11 @@ module.exports.register = function ({ config }) {
         latestOperatorResult,
         latestConnectResult,
       ] = await Promise.allSettled([
-        GetLatestRedpandaVersion(github, owner, 'redpanda', logger),
+        // streaming-enterprise, not the frozen public 'redpanda' repo: the public
+        // repo still answers API calls but stopped receiving releases on
+        // 2026-08-20, so resolving from it silently pins the docs to the last
+        // pre-freeze version forever.
+        GetLatestRedpandaVersion(github, owner, 'streaming-enterprise', logger),
         GetLatestDockerTag(dockerNamespace, 'console', logger),
         GetLatestDockerTag(dockerNamespace, 'redpanda-operator', logger),
         GetLatestConnectVersion(github, owner, 'connect', logger),
@@ -218,10 +227,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/mcp/CLI_INTERFACE.adoc

@@ -43,7 +43,7 @@ npx doc-tools get-redpanda-version [--beta]
 ----
 REDPANDA_VERSION=v25.3.1
 REDPANDA_DOCKER_TAG=docker.redpanda.com/redpandadata/redpanda:v25.3.1
-REDPANDA_RELEASE_NOTES=https://github.com/redpanda-data/redpanda/releases/tag/v25.3.1
+REDPANDA_RELEASE_NOTES=https://github.com/redpanda-data/streaming-enterprise/releases/tag/v25.3.1
 ----
 
 *Flags:*

package/mcp/USER_GUIDE.adoc

@@ -571,7 +571,7 @@ NOTE: Stack traces are only included when `NODE_ENV=development` for security re
   "version": "v25.3.1",
   "docker_tag": "docker.redpanda.com/redpandadata/redpanda:v25.3.1",
   "is_beta": false,
-  "notes_url": "https://github.com/redpanda-data/redpanda/releases/tag/v25.3.1"
+  "notes_url": "https://github.com/redpanda-data/streaming-enterprise/releases/tag/v25.3.1"
 }
 ----
 
@@ -592,7 +592,7 @@ notes_url:: GitHub release notes URL
   "version": "v25.4.1-rc1",
   "docker_tag": "docker.redpanda.com/redpandadata/redpanda-unstable:v25.4.1-rc1",
   "is_beta": true,
-  "notes_url": "https://github.com/redpanda-data/redpanda/releases/tag/v25.4.1-rc1"
+  "notes_url": "https://github.com/redpanda-data/streaming-enterprise/releases/tag/v25.4.1-rc1"
 }
 ----
 
@@ -857,7 +857,7 @@ Claude: *uses get_redpanda_version MCP tool*
 The latest Redpanda version is v25.3.1, released on January 15, 2024.
 
 Docker tag: docker.redpanda.com/redpandadata/redpanda:v25.3.1
-Release notes: https://github.com/redpanda-data/redpanda/releases/tag/v25.3.1
+Release notes: https://github.com/redpanda-data/streaming-enterprise/releases/tag/v25.3.1
 ----
 
 ----
@@ -969,7 +969,7 @@ Claude: *uses generate_property_docs MCP tool*
 ❌ Generation failed: Tag v99.9.9 not found in Redpanda repository
 
 Suggestion: Check that the version exists in the Redpanda repository. You can find available versions at:
-https://github.com/redpanda-data/redpanda/releases
+https://github.com/redpanda-data/streaming-enterprise/releases
 ----
 
 === Example 7: Property documentation updates (with prompt)

package/package.json

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

package/tools/bundle-openapi.js

@@ -2,7 +2,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { execSync, spawnSync } = require('child_process');
+const { execSync, execFileSync, spawnSync } = require('child_process');
 const yaml = require('yaml');
 const { getMajorMinor } = require('../cli-utils/version');
 
@@ -585,7 +585,7 @@ function postProcessBundle(filePath, options, quiet = false) {
  * @param {string} [options.output] - Standalone output file path; when provided, used for the single output file.
  * @param {string} [options.outAdmin] - Output path for the admin API when integrating with doc-tools mode.
  * @param {string} [options.outConnect] - Output path for the connect API when integrating with doc-tools mode.
- * @param {string} [options.repo] - Repository URL to clone (defaults to https://github.com/redpanda-data/redpanda.git).
+ * @param {string} [options.repo] - Repository URL to clone (defaults to https://github.com/redpanda-data/streaming-enterprise.git, a private repo that requires a GitHub token).
  * @param {string} [options.adminMajor] - Admin API major version string used for metadata (for example, 'v2.0.0').
  * @param {boolean} [options.useAdminMajorVersion] - When true and processing the admin surface, use `adminMajor` for the bundle info.version.
  * @param {boolean} [options.quiet=false] - Suppress logging to stdout/stderr when true.
@@ -649,24 +649,42 @@ async function bundleOpenAPI(options) {
   try {
     // Clone repository (only once for all surfaces)
     if (!quiet) {
-      console.log('📥 Cloning redpanda repository...');
+      console.log('📥 Cloning streaming-enterprise repository...');
     }
 
-    const { getAuthenticatedGitHubUrl, hasGitHubToken } = require('../cli-utils/github-token');
+    const { getGitHubToken } = require('../cli-utils/github-token');
 
-    let repositoryUrl = repo || 'https://github.com/redpanda-data/redpanda.git';
+    const repositoryUrl = repo || 'https://github.com/redpanda-data/streaming-enterprise.git';
+    const usingDefaultRepo = !repo;
+    const token = getGitHubToken();
 
-    // Use token if available for better rate limits and reliability
-    if (hasGitHubToken() && repositoryUrl.includes('github.com')) {
-      repositoryUrl = getAuthenticatedGitHubUrl(repositoryUrl);
+    if (usingDefaultRepo && !token) {
+      throw new Error('redpanda-data/streaming-enterprise is a private repository: set GH_TOKEN, GITHUB_TOKEN, or REDPANDA_GITHUB_TOKEN so the clone can authenticate.');
+    }
+
+    // Auth travels via a credential helper registered through GIT_CONFIG_*
+    // environment variables, never as a git -c argument, so the token
+    // cannot appear in this process's argv (visible to anything that can
+    // list processes) or get embedded in an exec error's command-line
+    // message. It's also never embedded in the remote URL or persisted in
+    // the clone's .git/config.
+    const gitEnv = { ...process.env };
+    if (token && repositoryUrl.includes('github.com')) {
       if (!quiet) {
         console.log('🔑 Using authenticated clone (token provided)');
       }
+      gitEnv.BUNDLE_OPENAPI_CLONE_TOKEN = token;
+      gitEnv.GIT_CONFIG_COUNT = '2';
+      gitEnv.GIT_CONFIG_KEY_0 = 'credential.helper';
+      gitEnv.GIT_CONFIG_VALUE_0 = '';
+      gitEnv.GIT_CONFIG_KEY_1 = 'credential.https://github.com.helper';
+      gitEnv.GIT_CONFIG_VALUE_1 = '!f() { echo "username=x-access-token"; echo "password=$BUNDLE_OPENAPI_CLONE_TOKEN"; }; f';
     }
 
     try {
-      execSync(`git clone --depth 1 --branch ${tag} ${repositoryUrl} redpanda`, {
+      execFileSync('git', ['clone', '--depth', '1', '--branch', tag, repositoryUrl, 'redpanda'], {
         cwd: tempDir,
+        env: gitEnv,
         stdio: quiet ? 'ignore' : 'inherit',
         timeout: 60000 // 1 minute timeout
       });
@@ -825,7 +843,7 @@ if (require.main === module) {
     .option('-o, --output <path>', 'Output file path (defaults: admin/redpanda-admin-api.yaml or connect/redpanda-connect-api.yaml)')
     .option('--out-admin <path>', 'Output path for admin API', 'admin/redpanda-admin-api.yaml')
     .option('--out-connect <path>', 'Output path for connect API', 'connect/redpanda-connect-api.yaml')
-    .option('--repo <url>', 'Repository URL', 'https://github.com/redpanda-data/redpanda.git')
+    .option('--repo <url>', 'Repository URL. The default is a private repo, so requires a GitHub token (GH_TOKEN, GITHUB_TOKEN, or REDPANDA_GITHUB_TOKEN)', 'https://github.com/redpanda-data/streaming-enterprise.git')
     .option('--admin-major <string>', 'Admin API major version', 'v2.0.0')
     .option('--use-admin-major-version', 'Use admin major version for info.version instead of git tag', false)
     .option('-q, --quiet', 'Suppress output', false)

package/tools/get-redpanda-version.js

@@ -2,6 +2,7 @@
 
 const GetLatestRedpandaVersion = require('../extensions/version-fetcher/get-latest-redpanda-version.js');
 const { getPrereleaseFromAntora } = require('../cli-utils/antora-utils.js');
+const { getGitHubToken } = require('../cli-utils/github-token');
 
 /**
  * Fetches and prints the latest Redpanda version and Docker repository.
@@ -10,8 +11,20 @@ const { getPrereleaseFromAntora } = require('../cli-utils/antora-utils.js');
  * @param {boolean} options.fromAntora - Whether to derive beta flag from antora.yml
  */
 module.exports = async function getRedpandaVersion({ beta = false, fromAntora = false }) {
+  // streaming-enterprise, not the old public redpanda repo: the public repo
+  // still answers API requests but froze at its 2026-08-20 state when the
+  // source moved, so resolving "latest" from it silently pins to the last
+  // pre-freeze release forever. streaming-enterprise is private, and
+  // unauthenticated release listings 404 rather than fail loudly, so refuse
+  // to guess without a token instead of quietly resolving nothing.
   const owner = 'redpanda-data';
-  const repo = 'redpanda';
+  const repo = 'streaming-enterprise';
+
+  if (!getGitHubToken()) {
+    console.error(`❌ redpanda-data/${repo} is a private repository.`);
+    console.error('   Set GH_TOKEN, REDPANDA_GITHUB_TOKEN, or GITHUB_TOKEN to a token with access.');
+    process.exit(1);
+  }
 
   // Determine whether to treat this as a beta (RC) release
   let useBeta = beta;

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:')