scripts/helm-docs.sh: add --check, fail only on README diffs

.buildkite/pipeline.yaml

@@ -20,10 +20,7 @@ steps:
     agents: { queue: standard }
 
   - label: ":book: Verify helm-docs is up-to-date"
-    commands:
-      - "./scripts/helm-docs.sh"
-      - "echo \"checking for uncommitted changes\""
-      - "[[ -z $(git status -s) ]]"
+    command: "./scripts/helm-docs.sh --check"
     agents: { queue: standard }
 
   # Releases rewrite image digests and the registry in values.yaml. If a README

AGENTS.md

@@ -2,12 +2,12 @@
 
 ## After Making Changes
 
-After making changes to any `values.yaml` file, regenerate the helm docs and verify there are no uncommitted changes:
+After making changes to any `values.yaml` file, regenerate the helm docs; this script exits non-zero and lists the README.md files it changed:
 
 ```sh
-./scripts/helm-docs.sh && [[ -z $(git status -s) ]]
+./scripts/helm-docs.sh --check
 ```
 
-If the README was updated, stage and commit the changes alongside your other modifications.
+If the README.d was updated, stage and commit the changes alongside your other modifications.
 
 Releases rewrite every pinned image `defaultTag` and the `sourcegraph.image.repository` registry in `values.yaml`. When adding one of these values, give it a `# -- ` description and a `# @default -- ` annotation, like the existing images, so the README does not change on release. Published charts still list the exact values: the publish workflows run `scripts/ci/render-published-readmes.sh`, which matches these annotations by their exact text, so update it if you reword them.

scripts/helm-docs.sh

@@ -1,12 +1,34 @@
-#!/usr/bin/env bash
-# Copy from https://github.com/linkerd/linkerd2/blob/main/bin/helm-docs
+#!/bin/sh
+# Downloads the pinned helm-docs release into target/bin (gitignored) on first
+# use, then runs it from the repository root with any arguments passed to this
+# script.
+#
+# Usage:
+#   ./scripts/helm-docs.sh                Regenerate charts/**/README.md after changing a values.yaml file
+#   ./scripts/helm-docs.sh --check        Regenerate, then exit 1 listing any README that changed
+#   ./scripts/helm-docs.sh [args]         Run the helm-docs CLI with args
+#   ./scripts/helm-docs.sh --check [args] Check with helm-docs CLI args
+#
+# POSIX sh, so it runs the same on developer machines and in Buildkite.
+#
+# Adapted from https://github.com/linkerd/linkerd2/blob/main/bin/helm-docs
 
-set -euf -o pipefail
+helmdocsversion=1.14.2
 
-helmdocsv=1.14.2
-bindir=$( cd "${0%/*}" && pwd ) # Change to script dir and set bin dir to this
-targetbin=$( cd "$bindir"/.. && pwd )/target/bin
-helmdocsbin=$targetbin/helm-docs-$helmdocsv
+set -euf
+
+check=false
+if [ "${1:-}" = --check ]; then
+    check=true
+    shift
+fi
+
+# helm-docs scans the cwd for charts and reads .helmdocsignore from there, so
+# run from the repository root regardless of the caller's cwd.
+cd "$(dirname "$0")/.."
+
+targetbin=$PWD/target/bin
+helmdocsbin=$targetbin/helm-docs-$helmdocsversion
 
 if [ ! -f "$helmdocsbin" ]; then
     # Release assets are named helm-docs_<version>_<OS>_<arch>.tar.gz,
@@ -15,25 +37,46 @@ if [ ! -f "$helmdocsbin" ]; then
         Darwin) os=Darwin ;;
         Linux) os=Linux ;;
         MSYS*|MINGW*|CYGWIN*) os=Windows ;;
-        *) echo "Unsupported OS: $(uname -s)"; exit 126 ;;
+        *) echo "Unsupported host OS: $(uname -s)" >&2; exit 126 ;;
     esac
     case $(uname -m) in
         x86_64|amd64) arch=x86_64 ;;
         aarch64|arm64) arch=arm64 ;;
         armv7l) arch=arm7 ;;
         armv6l) arch=arm6 ;;
-        *) echo "Unsupported architecture: $(uname -m)"; exit 126 ;;
+        *) echo "Unsupported host architecture: $(uname -m)" >&2; exit 126 ;;
     esac
-    helmdocscurl="https://github.com/norwoodj/helm-docs/releases/download/v$helmdocsv/helm-docs_${helmdocsv}_${os}_${arch}.tar.gz"
-    tmp=$(mktemp -d -t helm-docs.XXX)
+    helmdocscurl="https://github.com/norwoodj/helm-docs/releases/download/v$helmdocsversion/helm-docs_${helmdocsversion}_${os}_${arch}.tar.gz"
+    tmp=$(mktemp -d "${TMPDIR:-/tmp}/helm-docs.XXXXXX")
     mkdir -p "$targetbin"
     (
         cd "$tmp"
-        curl --proto '=https' --tlsv1.2 -sSfL -o "./helm-docs.tar.gz" "$helmdocscurl"
-        tar zf "./helm-docs.tar.gz" -x "helm-docs"
-        chmod +x "helm-docs"
+        curl --proto '=https' --tlsv1.2 -sSfL -o helm-docs.tar.gz "$helmdocscurl"
+        tar -xzf helm-docs.tar.gz helm-docs
+        chmod +x helm-docs
     )
     mv "$tmp/helm-docs" "$helmdocsbin"
+    rm -rf "$tmp"
+fi
+
+if [ "$check" = false ]; then
+    exec "$helmdocsbin" "$@"
 fi
 
-"$helmdocsbin" "$@"
+# --check: checksum every chart README before and after, and fail if any
+# changed. Only the READMEs count, so unrelated uncommitted edits elsewhere in
+# the tree do not fail the check.
+readme_checksums() { find charts -name README.md -exec cksum {} +; }
+before=$(readme_checksums)
+
+"$helmdocsbin" "$@"
+
+rewritten=$(readme_checksums | while read -r line; do
+    printf '%s\n' "$before" | grep -qxF -- "$line" || echo "${line##* }"
+done)
+
+if [ -n "$rewritten" ]; then
+    echo "$rewritten"
+    echo "The chart READMEs listed above are out of date. Run ./scripts/helm-docs.sh and commit them" >&2
+    exit 1
+fi