From e3c1167bbe80824ee81fad0e6d73d7c9fe4e2c55 Mon Sep 17 00:00:00 2001
From: Lohit Kolluri <lohitkolluri@gmail.com>
Date: Sun, 21 Jun 2026 01:39:21 +0530
Subject: [PATCH] validate: make docs validation deterministic

Compare generated docs output directly against checked-in reference
docs to make validation deterministic, instead of using diff-based
comparison which was non-deterministic across runs.

- Use trailing slash on docsgen source path for directory semantics
- Replace docs instead of diffing: rm + cp replaces git-add + diff -ru
- Check git diff --cached instead of git status --porcelain for
  more reliable change detection
- Scope git add to specific paths (docs/reference, docs/bake-stdlib.md)

Signed-off-by: Lohit Kolluri <lohitkolluri@gmail.com>
---
 hack/dockerfiles/docs.Dockerfile | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/hack/dockerfiles/docs.Dockerfile b/hack/dockerfiles/docs.Dockerfile
index c16a8b273fc2..1644e1e5bb1b 100644
--- a/hack/dockerfiles/docs.Dockerfile
+++ b/hack/dockerfiles/docs.Dockerfile
@@ -21,7 +21,7 @@ RUN --mount=target=/context \
   --mount=target=.,type=tmpfs <<EOT
 set -e
 rsync -a /context/. .
-docsgen --formats "$FORMATS" --source "docs/reference" --bake-stdlib-source "docs/bake-stdlib.md"
+docsgen --formats "$FORMATS" --source "docs/reference/" --bake-stdlib-source "docs/bake-stdlib.md"
 mkdir /out
 cp -r docs/reference docs/bake-stdlib.md /out
 rm -f /out/reference/*__INTERNAL_SERVE.yaml /out/reference/*__INTERNAL_SERVE.md
@@ -35,12 +35,17 @@ RUN --mount=target=/context \
   --mount=target=.,type=tmpfs <<EOT
 set -e
 rsync -a /context/. .
-git add -A
-rm -rf docs/reference/* docs/bake-stdlib.md
-cp -rf /out/* ./docs/
-if [ -n "$(git status --porcelain -- docs/reference docs/bake-stdlib.md)" ]; then
+
+# Replace checked-in docs with freshly generated output and ensure this does not
+# leave the repository dirty, matching the contract of `make docs`.
+rm -rf docs/reference
+cp -r /out/reference docs/reference
+cp /out/bake-stdlib.md docs/bake-stdlib.md
+
+git add -A docs/reference docs/bake-stdlib.md
+if ! git diff --cached --quiet; then
   echo >&2 'ERROR: Docs result differs. Please update with "make docs"'
-  git status --porcelain -- docs/reference docs/bake-stdlib.md
+  git diff --cached
   exit 1
 fi
 EOT