@redpanda-data/docs-extensions-and-macros 5.44.0 → 5.45.0

package/bin/doc-tools.js

@@ -2748,6 +2748,55 @@ programCli
     runCli(options)
   })
 
+/**
+ * lint-screenshots
+ *
+ * @description
+ * Deterministic checks from the docs screenshot standard, run against the
+ * .adoc pages under modules/ in a docs repo: every image macro (block and
+ * inline) has alt text, the alt text is at most 125 characters, does not
+ * start with "screenshot of" / "image of" / "picture of", and has no
+ * unquoted comma (Asciidoctor would split it into width/height); the
+ * referenced image file exists and is at most 100KB. Those are errors and
+ * exit 1. Warnings (exit 0 unless --warnings-as-errors) cover the rest of
+ * the standard: images above the 50KB target, JPEG/WebP where PNG or SVG
+ * belongs, captures wider than 1920px, and - in --files mode - changed
+ * images nothing references. Commented-out macros are skipped.
+ *
+ * @why
+ * cloud-docs enforced these rules on every PR and its daily screenshot cron
+ * with a repo-local script; the other docs repos had nothing. One command
+ * in doc-tools lets every docs repo and the shared PR review pipeline run
+ * the same checks, so no two jobs disagree about the same 100KB limit.
+ *
+ * @example
+ * # Whole repo (from the docs repo root): what the cloud-docs PR check runs
+ * npx doc-tools lint-screenshots
+ *
+ * # PR mode: only pages changed in the PR, plus pages that use a changed image
+ * gh pr diff 123 --name-only > changed.txt
+ * npx doc-tools lint-screenshots --files changed.txt --format json --output review-output/screenshot-lint.json
+ *
+ * # Adopt the stricter items as blocking
+ * npx doc-tools lint-screenshots --warnings-as-errors
+ */
+programCli
+  .command('lint-screenshots')
+  .description('Lint image macros and image files in a docs repo against the screenshot standard (alt text, size, format, width)')
+  .option('--root <path>', 'Docs repo root, the directory that holds modules/ (default: current directory)')
+  .option('--files <path>', 'Changed-files list (one repo-relative path per line, for example from `gh pr diff --name-only`): lint only listed .adoc files and pages that reference a listed image')
+  .option('--format <format>', 'Output format: human or json', 'human')
+  .option('--output <path>', 'Also write the JSON result to this file')
+  .option('--max-alt-length <n>', 'Alt text character limit', String(require('../tools/lint-screenshots').DEFAULTS.maxAltLength))
+  .option('--max-bytes <n>', 'Image size ceiling in bytes (error above this)', String(require('../tools/lint-screenshots').DEFAULTS.maxBytes))
+  .option('--target-bytes <n>', 'Image size target in bytes (warning above this)', String(require('../tools/lint-screenshots').DEFAULTS.targetBytes))
+  .option('--max-width <n>', 'Intrinsic image width limit in pixels (warning above this)', String(require('../tools/lint-screenshots').DEFAULTS.maxWidth))
+  .option('--warnings-as-errors', 'Exit 1 on warnings too')
+  .action((options) => {
+    const { runCli } = require('../tools/lint-screenshots')
+    runCli(options)
+  })
+
 /**
  * preview-string
  *

package/cli-utils/git-credential-env.js

@@ -0,0 +1,84 @@
+'use strict'
+
+/**
+ * Git credential helper environment
+ *
+ * Every doc-tools code path that clones or fetches a private Redpanda repo
+ * with the git CLI needs the same thing: hand git a GitHub token without the
+ * token ever becoming visible outside the process. This module is the single
+ * implementation of that.
+ *
+ * The token travels through a per-invocation credential helper registered
+ * with GIT_CONFIG_* environment variables, so:
+ *
+ * - It is never a `git -c` argument or part of the remote URL, so it cannot
+ *   be read out of argv (`ps`, /proc/<pid>/cmdline) for the length of a
+ *   multi-minute clone, and git cannot echo it back in an error message.
+ * - It is never written into the clone's .git/config, where it would sit
+ *   readable on disk for every later step that reads the checkout.
+ * - Nothing goes through a shell the caller has to quote for.
+ *
+ * Use getGitHubToken() from ./github-token to resolve the token, then pass
+ * the result here. Pair it with redactCredentials() on any git stderr that
+ * reaches an Error message or a CI log.
+ */
+
+// The variable the helper reads the token from at callback time. Only the
+// name appears in the (static, secret-free) helper command string.
+const TOKEN_ENV_VAR = 'DOC_TOOLS_GIT_CREDENTIAL_TOKEN'
+
+/**
+ * Environment for a git subprocess that must authenticate to github.com.
+ *
+ * With no token, `baseEnv` is returned unchanged rather than half-configured:
+ * git then falls back to the host's own credential helpers, which is what a
+ * local run relies on and all a public repo needs. Callers that require a
+ * token should check for one and fail with their own message first.
+ *
+ * The helper is scoped to `credential.https://github.com.helper`, so no other
+ * host is ever offered the token, and entry 0 clears inherited helpers so a
+ * system credential manager cannot intercept (or prompt) before ours answers.
+ * Any GIT_CONFIG_* entries already in `baseEnv` are replaced.
+ *
+ * @param {string|null|undefined} token - GitHub token, or falsy for no auth
+ * @param {NodeJS.ProcessEnv} [baseEnv=process.env] - Environment to extend
+ * @returns {NodeJS.ProcessEnv} Environment to pass as a spawn/exec `env`
+ */
+function gitAuthEnv(token, baseEnv = process.env) {
+  if (!token) return baseEnv
+  return {
+    ...baseEnv,
+    [TOKEN_ENV_VAR]: token,
+    GIT_CONFIG_COUNT: '2',
+    GIT_CONFIG_KEY_0: 'credential.helper',
+    GIT_CONFIG_VALUE_0: '',
+    GIT_CONFIG_KEY_1: 'credential.https://github.com.helper',
+    GIT_CONFIG_VALUE_1: `!f() { echo "username=x-access-token"; echo "password=$${TOKEN_ENV_VAR}"; }; f`
+  }
+}
+
+/**
+ * Strip anything credential-shaped out of text before it is surfaced
+ * anywhere that gets logged -- an Error message ends up in plain CI logs.
+ *
+ * Covers a credential in a remote URL's userinfo (https://<token>@github.com/...),
+ * which git echoes back verbatim on common failures (a private repo it cannot
+ * see, a bad ref), and a Basic-auth header in case git ever echoes failing
+ * config back. Defense in depth: gitAuthEnv() already keeps the token out of
+ * argv and URLs, so this covers credentials that came from somewhere else,
+ * such as a URL the caller was handed.
+ *
+ * @param {string} text - Text to scrub (nullish becomes '')
+ * @returns {string} Text with credentials replaced by ***
+ */
+function redactCredentials(text) {
+  return String(text || '')
+    .replace(/\/\/[^/@\s]+@/g, '//***@')
+    .replace(/(authorization:\s*basic\s+)\S+/gi, '$1***')
+}
+
+module.exports = {
+  gitAuthEnv,
+  redactCredentials,
+  TOKEN_ENV_VAR
+}

package/extensions/git-full-clone.js

@@ -6,6 +6,7 @@ const { execSync } = require('child_process')
 const fs = require('fs')
 const path = require('path')
 const { getGitHubToken } = require('../cli-utils/github-token')
+const { gitAuthEnv, redactCredentials } = require('../cli-utils/git-credential-env')
 
 /**
  * Configure Antora to use full git clones instead of shallow clones.
@@ -72,27 +73,21 @@ module.exports.register = function ({ config, playbook }) {
 
     // Private repos need credentials: the git CLI does not share Antora's
     // built-in credential manager, so resolve a token (GIT_CREDENTIALS first,
-    // then the common token env vars) and hand it to git through a credential
-    // helper. Both the config and the token travel via environment variables
-    // (GIT_CONFIG_* and GIT_FULL_CLONE_TOKEN), so nothing touches the command
-    // line, the remote URL, or the cached .git/config, and there is no shell
-    // quoting to break on other platforms. Config entry 0 clears any inherited
-    // helpers; entry 1 registers a helper scoped to github.com so no other
-    // host is ever offered the token.
+    // then the common token env vars) and hand it to git through gitAuthEnv's
+    // credential helper. Both the config and the token travel via environment
+    // variables, so nothing touches the command line, the remote URL, or the
+    // cached .git/config, and there is no shell quoting to break on other
+    // platforms.
     const token = getGitHubToken()
     const gitCommand = 'git fetch --unshallow'
-    const gitEnv = { ...process.env, GIT_TERMINAL_PROMPT: '0' }
     if (token) {
       logger.info('  → Using GitHub token for unshallow fetches')
-      gitEnv.GIT_FULL_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=$GIT_FULL_CLONE_TOKEN"; }; f'
     } else {
       logger.info('  → No GitHub token found; unshallow may fail for private repos')
     }
+    // GIT_TERMINAL_PROMPT=0 in both cases: a prompt in a build has no one to
+    // answer it, so fail fast instead of hanging.
+    const gitEnv = gitAuthEnv(token, { ...process.env, GIT_TERMINAL_PROMPT: '0' })
 
     for (const aggregate of contentAggregate) {
       for (const origin of aggregate.origins || []) {
@@ -123,7 +118,7 @@ module.exports.register = function ({ config, playbook }) {
             if (err.killed) {
               logger.warn(`    ✗ Unshallow timeout after ${duration}ms for ${path.basename(gitdir)} (increase unshallowTimeout if needed)`)
             } else {
-              logger.warn(`    ✗ Failed to unshallow ${path.basename(gitdir)}: ${err.message}`)
+              logger.warn(`    ✗ Failed to unshallow ${path.basename(gitdir)}: ${redactCredentials(err.message)}`)
             }
             logger.warn(`    ⚠️  Git dates may be inaccurate for this repo - consider using a pre-cloned cache`)
           }

package/package.json

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

package/tools/bundle-openapi.js

@@ -5,6 +5,7 @@ const path = require('path');
 const { execSync, execFileSync, spawnSync } = require('child_process');
 const yaml = require('yaml');
 const { getMajorMinor } = require('../cli-utils/version');
+const { gitAuthEnv, redactCredentials } = require('../cli-utils/git-credential-env');
 
 /**
  * Normalize a Git tag into a semantic version string.
@@ -662,24 +663,16 @@ async function bundleOpenAPI(options) {
       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';
+    // gitAuthEnv hands the token to git through a credential helper carried
+    // in the subprocess environment, so it cannot appear in this process's
+    // argv (visible to anything that can list processes) or in an exec
+    // error's command line, and is never embedded in the remote URL or
+    // persisted in the clone's .git/config.
+    const useToken = Boolean(token) && repositoryUrl.includes('github.com');
+    if (useToken && !quiet) {
+      console.log('🔑 Using authenticated clone (token provided)');
     }
+    const gitEnv = gitAuthEnv(useToken ? token : null, { ...process.env });
 
     try {
       execFileSync('git', ['clone', '--depth', '1', '--branch', tag, repositoryUrl, 'redpanda'], {
@@ -689,7 +682,7 @@ async function bundleOpenAPI(options) {
         timeout: 60000 // 1 minute timeout
       });
     } catch (cloneError) {
-      throw new Error(`Failed to clone repository: ${cloneError.message}`);
+      throw new Error(`Failed to clone repository: ${redactCredentials(cloneError.message)}`);
     }
 
     const repoDir = path.join(tempDir, 'redpanda');

package/tools/lint-screenshots/index.js

@@ -0,0 +1,383 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+/**
+ * doc-tools lint-screenshots: deterministic checks from the docs screenshot
+ * standard that need no browser and no model - alt text and image macro
+ * correctness, plus the image file facts (existence, size, format, capture
+ * width) that a PR reviewer would otherwise measure by hand.
+ *
+ * Promoted from cloud-docs' tests/doc-detective/lint-screenshots.js so every
+ * docs repo runs ONE implementation. The error-severity rules are exactly the
+ * rules that script enforced (its findings were already blocking cloud-docs
+ * PRs); the stricter items from the screenshot standard that no repo enforced
+ * before are warnings, so adopting the command never turns a previously green
+ * repo red on day one.
+ *
+ * This does NOT judge the "purpose test" (whether an image should exist at
+ * all), annotation style, PII overlays, or alt-text accuracy. Those need a
+ * human or a vision pass.
+ */
+
+const DEFAULTS = Object.freeze({
+  maxAltLength: 125,
+  maxBytes: 100 * 1024,
+  targetBytes: 50 * 1024,
+  maxWidth: 1920, // 2x capture of a <=960px display width
+  bannedAltPrefixes: ['screenshot of', 'image of', 'picture of']
+})
+
+const IMAGE_EXT_RE = /\.(png|svg|jpe?g|gif|webp|avif)$/i
+
+// Block macro: image::target[attrs]. Same shape the cloud-docs linter
+// matched, so its existing findings carry over unchanged.
+const BLOCK_MACRO_RE = /image::([^\[\]]+)\[([^\]]*)\]/g
+// Inline macro: image:target[attrs] - single colon, not preceded by a word
+// character (that would be another macro name) or a colon (the block form).
+const INLINE_MACRO_RE = /(?<![\w:])image:(?!:)([^\[\]\s]+)\[([^\]]*)\]/g
+
+// A comma after unquoted alt text is only legitimate when every segment that
+// follows is itself a recognized image attribute (width=100, role=foo, or a
+// bare numeric width/height). Any other trailing segment means the comma split
+// real alt-text content, which Asciidoctor then reads as width/height.
+const NAMED_ATTR_RE = /^[a-zA-Z_:][a-zA-Z0-9_-]*\s*=/
+const BARE_DIMENSION_RE = /^\d+$/
+
+function parseAltText (attrs) {
+  const trimmed = attrs.trim()
+  if (trimmed.startsWith('"')) {
+    const closingIdx = trimmed.indexOf('"', 1)
+    if (closingIdx !== -1) {
+      return { altText: trimmed.slice(1, closingIdx), hasUnquotedComma: false }
+    }
+  }
+  const segments = trimmed.split(',').map((s) => s.trim())
+  const [altText, ...rest] = segments
+  const allRestAreAttrs = rest.every((s) => NAMED_ATTR_RE.test(s) || BARE_DIMENSION_RE.test(s))
+  return { altText, hasUnquotedComma: rest.length > 0 && !allRestAreAttrs }
+}
+
+function findAdocFiles (dir, out = []) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory()) findAdocFiles(full, out)
+    else if (entry.name.endsWith('.adoc')) out.push(full)
+  }
+  return out
+}
+
+/** Antora module a page belongs to, from its path under modules/. */
+function moduleOf (modulesDir, filePath) {
+  const rel = path.relative(modulesDir, filePath)
+  if (rel.startsWith('..')) return null
+  return rel.split(path.sep)[0]
+}
+
+/**
+ * Resolve an image macro target to a file under modules/, the way Antora
+ * does for the two forms that resolve inside one component:
+ *   "shared:file.png"  -> modules/shared/images/file.png
+ *   "file.png"         -> modules/<page's module>/images/file.png
+ * Returns null when the target cannot be checked locally: remote URLs,
+ * attribute references ({imagesdir}/x.png), and component-qualified IDs
+ * (other-component:module:file.png).
+ */
+function resolveImage (target, adocFile, modulesDir) {
+  const ref = target.trim()
+  if (/^https?:\/\//.test(ref) || ref.includes('{')) return null
+  const parts = ref.split(':')
+  if (parts.length > 2) return null
+  if (parts.length === 2 && /^[a-zA-Z0-9_.-]+$/.test(parts[0])) {
+    return path.join(modulesDir, parts[0], 'images', parts[1])
+  }
+  const mod = moduleOf(modulesDir, adocFile)
+  if (!mod) return null
+  return path.join(modulesDir, mod, 'images', ref)
+}
+
+/** Intrinsic pixel width from the file header; null when unknown. */
+function imageWidth (filePath) {
+  let fd
+  try {
+    fd = fs.openSync(filePath, 'r')
+    const buf = Buffer.alloc(32)
+    const read = fs.readSync(fd, buf, 0, 32, 0)
+    if (read >= 24 && buf.readUInt32BE(0) === 0x89504e47 && buf.toString('ascii', 12, 16) === 'IHDR') {
+      return buf.readUInt32BE(16)
+    }
+    if (read >= 10 && buf.toString('ascii', 0, 4) === 'GIF8') {
+      return buf.readUInt16LE(6)
+    }
+    return null
+  } catch (err) {
+    return null
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd)
+  }
+}
+
+function kb (bytes) {
+  return `${Math.round(bytes / 1024)}KB`
+}
+
+/**
+ * Collect every image macro reference from one page. Comment lines and
+ * comment blocks are skipped: a commented-out macro is not published.
+ */
+function collectReferences (adocFile, modulesDir, root) {
+  const content = fs.readFileSync(adocFile, 'utf8')
+  const relPath = path.relative(root, adocFile)
+  const refs = []
+  let inCommentBlock = false
+  const lines = content.split('\n')
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (line.trim() === '////') { inCommentBlock = !inCommentBlock; continue }
+    if (inCommentBlock || line.trimStart().startsWith('//')) continue
+    for (const [re, form] of [[BLOCK_MACRO_RE, 'block'], [INLINE_MACRO_RE, 'inline']]) {
+      re.lastIndex = 0
+      let m
+      while ((m = re.exec(line)) !== null) {
+        const [, target, attrs] = m
+        refs.push({
+          adocFile,
+          relPath,
+          line: i + 1,
+          form,
+          target: target.trim(),
+          attrs,
+          resolved: resolveImage(target, adocFile, modulesDir)
+        })
+      }
+    }
+  }
+  return refs
+}
+
+/**
+ * Run the linter.
+ *
+ * @param {Object} options
+ * @param {string} options.root - Docs repo root (the directory holding modules/)
+ * @param {string[]} [options.files] - Changed-files scope (repo-relative paths, for
+ *   example from `gh pr diff --name-only`). When set, only .adoc files in the
+ *   list and .adoc files that reference an image in the list are linted, and
+ *   listed images nothing references are reported. When omitted, every .adoc
+ *   under modules/ is linted.
+ * @param {number} [options.maxAltLength]
+ * @param {number} [options.maxBytes]
+ * @param {number} [options.targetBytes]
+ * @param {number} [options.maxWidth]
+ * @param {string[]} [options.bannedAltPrefixes]
+ * @returns {Object} { findings, summary, scope }
+ */
+function lintScreenshots (options) {
+  // Explicit undefined wins a spread, and intOption() returns undefined for
+  // an option nobody passed, so a plain `{ ...DEFAULTS, ...options }` lets a
+  // programmatic caller silently erase a threshold: every `size > undefined`
+  // is then false and the size rules vanish without a word. Drop undefined
+  // keys so an omitted threshold means "the default", not "no limit".
+  const provided = Object.fromEntries(
+    Object.entries(options || {}).filter(([, value]) => value !== undefined))
+  const opts = { ...DEFAULTS, ...provided }
+  if (!opts.root) throw new Error('lint-screenshots requires a root directory')
+  const root = path.resolve(opts.root)
+  const modulesDir = path.join(root, 'modules')
+  if (!fs.existsSync(modulesDir)) {
+    throw new Error(`No modules/ directory under ${root} - point --root at an Antora docs repo`)
+  }
+
+  const scoped = Array.isArray(opts.files)
+  const changedAdoc = new Set()
+  const changedImages = new Set()
+  // Deleted images stay in scope. Skipping a path that no longer exists would
+  // drop the pages that still reference it out of the scoped pass, so a PR
+  // that deletes a screenshot still referenced by a page would report nothing
+  // in --files mode while a whole-repo run reports image-missing. They are
+  // tracked separately so the orphaned-image rule can skip them: a file that
+  // is gone cannot be orphaned.
+  const deletedImages = new Set()
+  if (scoped) {
+    for (const f of opts.files) {
+      const abs = path.resolve(root, f)
+      const exists = fs.existsSync(abs)
+      if (f.endsWith('.adoc')) {
+        if (exists) changedAdoc.add(abs)
+      } else if (IMAGE_EXT_RE.test(f)) {
+        changedImages.add(abs)
+        if (!exists) deletedImages.add(abs)
+      }
+    }
+  }
+
+  const adocFiles = findAdocFiles(modulesDir)
+  const allRefs = adocFiles.flatMap((f) => collectReferences(f, modulesDir, root))
+  const refs = scoped
+    ? allRefs.filter((r) => changedAdoc.has(r.adocFile) || (r.resolved && changedImages.has(r.resolved)))
+    : allRefs
+
+  const findings = []
+  const add = (rule, severity, ref, message, file) => {
+    findings.push({
+      rule,
+      severity,
+      file: file || ref.relPath,
+      line: ref ? ref.line : null,
+      image: ref ? ref.target : null,
+      message
+    })
+  }
+
+  const seenImages = new Set()
+  for (const ref of refs) {
+    const { altText, hasUnquotedComma } = parseAltText(ref.attrs)
+
+    if (!altText) {
+      add('alt-missing', 'error', ref, 'Missing alt text')
+    } else {
+      if (hasUnquotedComma) {
+        add('alt-unquoted-comma', 'error', ref,
+          `Unquoted alt text contains a comma, which Asciidoctor splits into separate width/height attributes at render time. Wrap the alt text in double quotes or remove the comma: "${altText}"`)
+      }
+      if (altText.length > opts.maxAltLength) {
+        add('alt-too-long', 'error', ref, `Alt text is ${altText.length} chars (max ${opts.maxAltLength}): "${altText}"`)
+      }
+      const lowerAlt = altText.toLowerCase()
+      if (opts.bannedAltPrefixes.some((p) => lowerAlt.startsWith(p))) {
+        add('alt-banned-prefix', 'error', ref, `Alt text starts with a banned prefix: "${altText}"`)
+      }
+    }
+
+    if (!ref.resolved) continue
+    if (!fs.existsSync(ref.resolved)) {
+      add('image-missing', 'error', ref, `Referenced image not found: ${path.relative(root, ref.resolved)}`)
+      continue
+    }
+    // Image-file facts are reported once per image, on its first reference,
+    // so a shared image on five pages is one finding, not five.
+    if (seenImages.has(ref.resolved)) continue
+    seenImages.add(ref.resolved)
+
+    const size = fs.statSync(ref.resolved).size
+    if (size > opts.maxBytes) {
+      add('image-too-large', 'error', ref, `Image is ${kb(size)}, over the ${kb(opts.maxBytes)} ceiling`)
+    } else if (size > opts.targetBytes) {
+      add('image-above-target', 'warning', ref, `Image is ${kb(size)}, above the ${kb(opts.targetBytes)} target (${kb(opts.maxBytes)} ceiling)`)
+    }
+
+    const ext = path.extname(ref.resolved).toLowerCase()
+    if (['.jpg', '.jpeg', '.webp', '.avif'].includes(ext)) {
+      add('image-format', 'warning', ref, `Use PNG for screenshots or SVG for diagrams (got ${ext})`)
+    }
+
+    const width = imageWidth(ref.resolved)
+    if (width !== null && width > opts.maxWidth) {
+      add('image-too-wide', 'warning', ref, `Image is ${width}px wide, over the ${opts.maxWidth}px capture width (2x of a ${opts.maxWidth / 2}px display)`)
+    }
+  }
+
+  if (scoped) {
+    const referenced = new Set(allRefs.map((r) => r.resolved).filter(Boolean))
+    for (const img of changedImages) {
+      if (deletedImages.has(img)) continue // gone, so not orphaned
+      if (!referenced.has(img)) {
+        add('orphaned-image', 'warning', null,
+          'No image macro under modules/ references this file - if it is used through an attribute or from another repo, ignore this; otherwise remove it or add the macro',
+          path.relative(root, img))
+      }
+    }
+  }
+
+  const severityRank = { error: 0, warning: 1 }
+  findings.sort((a, b) => severityRank[a.severity] - severityRank[b.severity] ||
+    a.file.localeCompare(b.file) || (a.line || 0) - (b.line || 0))
+
+  const lintedFiles = new Set(refs.map((r) => r.relPath))
+  return {
+    scope: scoped ? 'changed' : 'repo',
+    findings,
+    summary: {
+      adoc_files_scanned: adocFiles.length,
+      adoc_files_linted: scoped ? lintedFiles.size : adocFiles.length,
+      references: refs.length,
+      images: seenImages.size,
+      errors: findings.filter((f) => f.severity === 'error').length,
+      warnings: findings.filter((f) => f.severity === 'warning').length
+    }
+  }
+}
+
+function formatHuman (result) {
+  const { summary, findings } = result
+  const scopeNote = result.scope === 'changed'
+    ? `${summary.adoc_files_linted} changed .adoc file(s) (${summary.references} image reference(s))`
+    : `${summary.adoc_files_scanned} .adoc files (${summary.references} image reference(s))`
+  if (findings.length === 0) {
+    return `Checked ${scopeNote}. No screenshot standard violations found.`
+  }
+  const lines = [`Checked ${scopeNote}. Found ${summary.errors} error(s), ${summary.warnings} warning(s):`, '']
+  const fmt = (f) => `${f.file}${f.line ? `:${f.line}` : ''}${f.image ? ` [${f.image}]` : ''} ${f.message}`
+  const errors = findings.filter((f) => f.severity === 'error')
+  const warnings = findings.filter((f) => f.severity === 'warning')
+  if (errors.length) {
+    lines.push('Errors:')
+    for (const f of errors) lines.push(`  ${fmt(f)}`)
+  }
+  if (warnings.length) {
+    if (errors.length) lines.push('')
+    lines.push('Warnings (not blocking):')
+    for (const f of warnings) lines.push(`  ${fmt(f)}`)
+  }
+  return lines.join('\n')
+}
+
+function readFileList (listPath) {
+  const text = fs.readFileSync(path.resolve(listPath), 'utf8')
+  return text.split('\n').map((l) => l.trim()).filter(Boolean)
+}
+
+function intOption (value, name) {
+  if (value === undefined || value === null) return undefined
+  const n = Number(value)
+  if (!Number.isInteger(n) || n <= 0) throw new Error(`${name} must be a positive integer (got ${value})`)
+  return n
+}
+
+function runCli (options) {
+  let result
+  try {
+    result = lintScreenshots({
+      root: options.root || process.cwd(),
+      files: options.files ? readFileList(options.files) : undefined,
+      maxAltLength: intOption(options.maxAltLength, '--max-alt-length'),
+      maxBytes: intOption(options.maxBytes, '--max-bytes'),
+      targetBytes: intOption(options.targetBytes, '--target-bytes'),
+      maxWidth: intOption(options.maxWidth, '--max-width')
+    })
+  } catch (err) {
+    console.error(`Error: ${err.message}`)
+    process.exit(2)
+  }
+
+  if (options.output) {
+    fs.mkdirSync(path.dirname(path.resolve(options.output)), { recursive: true })
+    fs.writeFileSync(path.resolve(options.output), JSON.stringify(result, null, 2) + '\n')
+  }
+  console.log(options.format === 'json' ? JSON.stringify(result, null, 2) : formatHuman(result))
+
+  const blocking = result.summary.errors + (options.warningsAsErrors ? result.summary.warnings : 0)
+  process.exit(blocking > 0 ? 1 : 0)
+}
+
+module.exports = {
+  DEFAULTS,
+  lintScreenshots,
+  formatHuman,
+  runCli,
+  parseAltText,
+  resolveImage,
+  imageWidth
+}

package/tools/property-extractor/rp-util-fetch.js

@@ -5,6 +5,7 @@ const fs = require('fs')
 const os = require('os')
 const path = require('path')
 const { getGitHubToken, getGitHubApiToken } = require('../../cli-utils/github-token')
+const { gitAuthEnv, redactCredentials } = require('../../cli-utils/git-credential-env')
 
 /**
  * rp_util's config schema JSON, for any streaming-enterprise ref (tag,
@@ -58,49 +59,6 @@ const SCHEMA_FLAGS = [
  * @param {string} ref - Branch, tag, or commit SHA
  * @param {string} destDir - Destination directory (must not exist yet)
  */
-/**
- * Strip a credential out of text before it's surfaced anywhere that gets
- * logged -- an Error message ends up in plain CI logs. Covers a credential
- * embedded in a Git remote URL's userinfo (e.g. https://<token>@github.com/...),
- * which Git echoes back verbatim in common failures (a private repo it can't
- * access, a bad ref, ...), and a Basic-auth header in case Git ever echoes
- * failing config back -- defense in depth: this module keeps the token out
- * of argv and URLs entirely (see gitAuthEnv).
- */
-function redactCredentials(text) {
-  return String(text || '')
-    .replace(/\/\/[^/@\s]+@/g, '//***@')
-    .replace(/(authorization:\s*basic\s+)\S+/gi, '$1***')
-}
-
-/**
- * Build the environment that authenticates git's github.com requests via a
- * per-invocation credential helper, injected through GIT_CONFIG_* env vars.
- * No token byte ever appears in argv (readable by any local process via
- * `ps`/`/proc/<pid>/cmdline` for the full multi-minute clone) or in a URL
- * (echoed verbatim by git on common failures), and nothing is written into
- * the resulting clone's .git/config, where it would otherwise sit readable
- * on disk for the entire downstream Bazel/Docker build. Same env-only
- * pattern the property-docs Makefile migration uses.
- * @param {string} token
- * @returns {object} env for spawnSync
- */
-function gitAuthEnv(token) {
-  return {
-    ...process.env,
-    RP_UTIL_FETCH_GIT_TOKEN: token,
-    GIT_CONFIG_COUNT: '2',
-    // Clear any inherited helpers first so a system credential manager
-    // can't intercept (or prompt) before ours answers.
-    GIT_CONFIG_KEY_0: 'credential.helper',
-    GIT_CONFIG_VALUE_0: '',
-    GIT_CONFIG_KEY_1: 'credential.https://github.com.helper',
-    // The helper reads the token from its own environment at callback time;
-    // argv carries only this static, secret-free string.
-    GIT_CONFIG_VALUE_1: '!f() { echo "username=x-access-token"; echo "password=$RP_UTIL_FETCH_GIT_TOKEN"; }; f'
-  }
-}
-
 function cloneStreamingEnterprise(ref, destDir) {
   const token = getGitHubToken()
   if (!token) {

package/tools/rpk-docs/generate-plugin-stubs.js

@@ -17,6 +17,8 @@ const fs = require('fs')
 const path = require('path')
 const os = require('os')
 const { spawnSync } = require('child_process')
+const { getGitHubToken } = require('../../cli-utils/github-token')
+const { gitAuthEnv, redactCredentials } = require('../../cli-utils/git-credential-env')
 
 /**
  * Read command titles from generated partials. The title line is
@@ -78,21 +80,35 @@ function fetchPartialsDir({ docsRepo, docsRef, plugin, sourcePath }) {
   // both carry the single-source tag, so either family can be stubbed
   const sparsePath = sourcePath || `modules/reference/partials/rpk-${plugin}`
 
-  console.log(`Fetching ${sparsePath} from ${docsRepo}@${docsRef}...`)
+  // The docs repo is private, so authenticate when the environment offers a
+  // token (GIT_CREDENTIALS in Antora builds; ACTIONS_BOT_TOKEN, GITHUB_TOKEN,
+  // and friends in workflows). Clone anonymously otherwise, and say so, so a
+  // failed run in CI names the missing piece instead of a bare git prompt.
+  const token = getGitHubToken()
+  // gitAuthEnv keeps the token in the subprocess environment only: never in
+  // argv, never in the remote URL, never in the clone's .git/config.
+  const env = gitAuthEnv(token)
+  const authNote = token ? '' : ' (no GitHub token found; cloning anonymously)'
+  console.log(`Fetching ${sparsePath} from ${docsRepo}@${docsRef}${authNote}...`)
   const cloneResult = spawnSync('git', [
     'clone', '--depth', '1', '--filter=blob:none', '--sparse',
     '--branch', docsRef,
     `https://github.com/${docsRepo}.git`, repoDir
-  ], { encoding: 'utf8', timeout: 180000 })
+  ], { encoding: 'utf8', timeout: 180000, env })
   if (cloneResult.status !== 0) {
-    throw new Error(`Failed to clone ${docsRepo}@${docsRef}: ${cloneResult.stderr}`)
+    const hint = token
+      ? ''
+      : `\nIf ${docsRepo} is private, set ACTIONS_BOT_TOKEN, GITHUB_TOKEN, REDPANDA_GITHUB_TOKEN, or GIT_CREDENTIALS so the clone can authenticate.`
+    throw new Error(`Failed to clone ${docsRepo}@${docsRef}: ${redactCredentials(cloneResult.stderr)}${hint}`)
   }
 
+  // --filter=blob:none deferred the blobs, so the sparse checkout pulls them
+  // now and needs the same credential helper as the clone.
   const sparseResult = spawnSync('git', ['sparse-checkout', 'set', sparsePath], {
-    cwd: repoDir, encoding: 'utf8', timeout: 60000
+    cwd: repoDir, encoding: 'utf8', timeout: 60000, env
   })
   if (sparseResult.status !== 0) {
-    throw new Error(`Failed sparse checkout of ${sparsePath}: ${sparseResult.stderr}`)
+    throw new Error(`Failed sparse checkout of ${sparsePath}: ${redactCredentials(sparseResult.stderr)}`)
   }
 
   const partialsDir = path.join(repoDir, sparsePath)

package/tools/rpk-docs/rpk-docs-handler.js

@@ -12,6 +12,7 @@ const { downloadRpkBinary, RPK_RELEASE_TAG_RE, RPK_CDN_BASE } = require('../../c
 const { generateRpkDiff, printDiffReport, generateWhatsNewSection, flattenToMap } = require('./report-delta')
 const { loadAndValidateOverrides, ValidationResult } = require('./validate-overrides')
 const { validateDirectory, formatResults } = require('./validate-output')
+const { gitAuthEnv, redactCredentials } = require('../../cli-utils/git-credential-env')
 
 /**
  * Known rpk plugins that are managed separately (have install/uninstall commands)
@@ -241,12 +242,10 @@ function prepareSourceFromRef(sourceRef, sourcePath = null) {
   const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'rpk-source-'))
   const repoDir = path.join(tmpDir, 'redpanda')
 
-  // streaming-enterprise is private, so a token is required. 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) and
-  // never embedded in the remote URL, so no token is persisted in the
-  // clone's .git/config either.
+  // streaming-enterprise is private, so a token is required. gitAuthEnv
+  // hands it to git through a credential helper carried in the subprocess
+  // environment, so it never reaches argv, the remote URL, or the clone's
+  // .git/config.
   const { getGitHubToken } = require('../../cli-utils/github-token')
   const token = getGitHubToken()
   if (!token) {
@@ -255,15 +254,7 @@ function prepareSourceFromRef(sourceRef, sourcePath = null) {
       'Set GH_TOKEN, GITHUB_TOKEN, or REDPANDA_GITHUB_TOKEN so the clone can authenticate.'
     )
   }
-  const gitEnv = {
-    ...process.env,
-    RPK_SOURCE_CLONE_TOKEN: token,
-    GIT_CONFIG_COUNT: '2',
-    GIT_CONFIG_KEY_0: 'credential.helper',
-    GIT_CONFIG_VALUE_0: '',
-    GIT_CONFIG_KEY_1: 'credential.https://github.com.helper',
-    GIT_CONFIG_VALUE_1: '!f() { echo "username=x-access-token"; echo "password=$RPK_SOURCE_CLONE_TOKEN"; }; f'
-  }
+  const gitEnv = gitAuthEnv(token)
 
   console.log(`Sparse-cloning streaming-enterprise repo (ref: ${sourceRef}) to ${repoDir}...`)
 
@@ -287,7 +278,7 @@ function prepareSourceFromRef(sourceRef, sourcePath = null) {
     throw new Error(
       `Failed to clone streaming-enterprise repo with ref '${sourceRef}'.\n` +
       `Make sure the branch or tag exists.\n` +
-      `Error: ${cloneResult.stderr}`
+      `Error: ${redactCredentials(cloneResult.stderr)}`
     )
   }
 
@@ -302,7 +293,7 @@ function prepareSourceFromRef(sourceRef, sourcePath = null) {
   })
 
   if (sparseResult.status !== 0) {
-    throw new Error(`Failed to set sparse checkout: ${sparseResult.stderr}`)
+    throw new Error(`Failed to set sparse checkout: ${redactCredentials(sparseResult.stderr)}`)
   }
 
   console.log(`Sparse checkout complete`)