hack: scope docs validation and show diff on failure

[lohitkolluri]

Summary

Tighten the validate stage of hack/dockerfiles/docs.Dockerfile:

• Drop the unscoped git add -A; the validation is a working-tree-vs-HEAD check, which git status --porcelain answers directly without mutating the index.
• Path-scope both detection (git status --porcelain) and diagnostics (git diff) to docs/reference and docs/bake-stdlib.md, so unrelated working-tree state cannot false-positive.
• Mirror the freshly generated docs with rsync -a --delete so any stale files are also reset (no separate rm -rf needed).
• On failure, print changed paths and a (truncated) diff alongside the existing error message, giving contributors an actionable signal instead of just filenames.
• git add -N before diffing so untracked files (e.g. a new command's docs) appear in the diff instead of only in the path list.

Approach

Detection and diagnostics are both path-scoped: git status --porcelain for the binary check, git diff for the failure output. rsync --delete handles the wholesale replacement, and git add -N ensures the diff shows content for newly added files.

Test plan

• make docs && make validate-docs succeeds when docs are in sync
• Modify a file under docs/reference/, re-run make validate-docs, confirm validate fails with the new changed-paths + diff output
• Add a new file under docs/reference/, re-run make validate-docs, confirm the new file's content is shown in the diff
• Dirty a file outside the scoped paths, confirm make validate-docs still passes (no false positive)

AI disclosure

Prepared with AI assistance (Claude Code).

[crazy-max]

I think we should keep the git-based validation here.

This target is already sandboxed. The validate stage copies the source context into a tmpfs, then checks whether applying the generated /out docs would leave docs/reference or docs/bake-stdlib.md dirty. The git add -A snapshots the docs as received by the sandbox, and git status validates the same contract as make docs: after replacing docs with generated output, there should be no repository changes under those paths.

A raw diff -ru /out/reference docs/reference changes that from a repository-state validation into a byte-for-byte directory comparison. That does not make generation more deterministic, it mostly changes diagnostics and bypasses Git's normalization/index behavior. If the issue is that the current error is not useful enough, we can add a diff on the failure path while keeping the git validation.

The bake/entitlements_test.go change also looks unrelated to docs validation. I can see the theory, since evaluateToExistingPath resolves symlinked path components and macOS may expose /var through /private/var, but the PR doesn't show an actual failing case, and the current tests already pass on macOS runners. If there is a real local macOS failure, please include the failing output and split that fix into a separate PR. Otherwise I think that change should be dropped.

[lohitkolluri]

Updated to scope the docs validation and make the failure output actionable:

• drop the unscoped git add -A; the check is working-tree vs HEAD, no need to mutate the index
• scope detection and the failure diff to docs/reference and docs/bake-stdlib.md; no false positives on unrelated working-tree state
• mirror the freshly generated docs with rsync -a --delete so stale files are also reset
• on failure, print the changed paths and a (truncated) diff alongside the error message
• git add -N before the diff so untracked files (e.g. a new command's docs) show their content
• trailing-slash on the docsgen --source to match the tool's expected path

All four test cases from the updated test plan pass against the final state. @crazy-max PTAL