godoc-current.txt is GOOS-dependent (sandbox per-OS docs); cross-platform commits trip the hook #126

New issue

Closed

opened 2026-06-10 17:34:57 +00:00 by coilysiren · 0 comments

coilysiren commented

2026-06-10 17:34:57 +00:00

Owner

Problem

godoc-current.txt is generated by scripts/check-godoc-current.sh running go doc -all per package, and the output is GOOS-dependent since cli/sandbox grew sandbox_linux.go / sandbox_other.go variants: a snapshot generated on macOS documents the off-Linux no-ops ("RunJail is unsupported off Linux"), while a Linux regeneration documents the real impls. The committed snapshot and the hook check can only agree on one platform at a time, so every cross-platform commit trips the hook with a spurious diff.

Surfaced while landing #125 on kai-server (Linux): the hook failed on sandbox docs untouched by the change. Swept the Linux regeneration into that commit to keep moving.

Fix options

Pin the generation platform: GOOS=linux go doc is not a thing (go doc builds for the host), but the script could go list-filter the per-OS files or run inside the Linux CI container only, with the hook skipping off-Linux.
Split the snapshot per GOOS (godoc-current_linux.txt + godoc-current_other.txt), each checked only on its platform.
Normalize: post-process the sandbox section out of the snapshot.

Related: the Actions runner servicing zero tasks (#107, #119) is why CI never caught the drift.

## Problem `godoc-current.txt` is generated by `scripts/check-godoc-current.sh` running `go doc -all` per package, and the output is GOOS-dependent since `cli/sandbox` grew `sandbox_linux.go` / `sandbox_other.go` variants: a snapshot generated on macOS documents the off-Linux no-ops ("RunJail is unsupported off Linux"), while a Linux regeneration documents the real impls. The committed snapshot and the hook check can only agree on one platform at a time, so every cross-platform commit trips the hook with a spurious diff. Surfaced while landing https://forgejo.coilysiren.me/coilyco-flight-deck/cli-guard/issues/125 on kai-server (Linux): the hook failed on sandbox docs untouched by the change. Swept the Linux regeneration into that commit to keep moving. ## Fix options * Pin the generation platform: `GOOS=linux go doc` is not a thing (go doc builds for the host), but the script could `go list`-filter the per-OS files or run inside the Linux CI container only, with the hook skipping off-Linux. * Split the snapshot per GOOS (`godoc-current_linux.txt` + `godoc-current_other.txt`), each checked only on its platform. * Normalize: post-process the sandbox section out of the snapshot. Related: the Actions runner servicing zero tasks (https://forgejo.coilysiren.me/coilyco-flight-deck/cli-guard/issues/107, https://forgejo.coilysiren.me/coilyco-flight-deck/cli-guard/issues/119) is why CI never caught the drift.

coilysiren added the

label

2026-06-17 07:04:36 +00:00

coilysiren added

and removed

labels

2026-06-17 08:39:36 +00:00

coilysiren added

consult

and removed

labels

2026-06-18 06:16:01 +00:00