From a9d84383fbb8b1269ee6397543fdec8ef26e21f8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Vig=C3=A9e?= Date: Sun, 21 Jun 2026 09:45:10 +0100 Subject: [PATCH] docs(go): document pre_run field in test provider_state struct form Adds pre_run to the test struct form docs in both the main Go plugin page and its Claude Code reference twin. Triggered by hephbuild/heph#111 (feat(plugin-go): test pre_run shell lines via provider state) --- plugins/heph-go/skills/heph-go/references/go-plugin.md | 6 ++++-- website/docs/plugins/go.md | 6 ++++-- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/plugins/heph-go/skills/heph-go/references/go-plugin.md b/plugins/heph-go/skills/heph-go/references/go-plugin.md index 38f56f9..6d29636 100644 --- a/plugins/heph-go/skills/heph-go/references/go-plugin.md +++ b/plugins/heph-go/skills/heph-go/references/go-plugin.md @@ -205,7 +205,7 @@ provider_state( |-------------------|------------------------|--------| | `go_codegen_root` | `bool` | When `True` on an ancestor, `go_src` targets are searched across the whole subtree rooted here (matched by package prefix) instead of only the leaf package. Use when one generator feeds many descendant packages. The deepest ancestor with this flag whose package is a prefix of the target's package is chosen. | | `go_codegen_deps` | `list[string]` | Explicit codegen target addresses injected into every descendant package's analysis/build sandbox. For generators that aren't labelled `go_src`. Honored independently of `go_codegen_root` (a BUILD setting only this still injects them). The closest ancestor carrying it wins. | -| `test` | `bool \| struct(...)` | `False` stops test-target generation for this subtree; `True` / unset runs them. The struct form sets env on `test`/`xtest` run targets, package-scoped only. See below. | +| `test` | `bool \| struct(...)` | `False` stops test-target generation for this subtree; `True` / unset runs them. The struct form configures `test`/`xtest` run targets — env vars and pre-run shell lines — package-scoped only. See below. | ### `test` — skipping and environment @@ -216,7 +216,7 @@ provider_state( **Struct form** (package-scoped only — does **not** affect descendants): -Sets environment variables on the generated `test`/`xtest` run targets. A struct-form +Configures the generated `test`/`xtest` run targets. A struct-form state also re-enables tests even when an ancestor set `test = False`. ```python title="BUILD" @@ -227,6 +227,7 @@ provider_state( "pass_env": ["HOME"], # hashed; affects the cache key "runtime_env": {"BAR": "2"}, # not hashed; runtime-only "runtime_pass_env": ["PATH"], # not hashed; runtime-only + "pre_run": ["export FOO=bar", "mkdir -p ./scratch"], }, ) ``` @@ -237,6 +238,7 @@ provider_state( | `pass_env` | `list[string]` | yes | Names of host env vars forwarded to the test run. | | `runtime_env` | `map[string]` | no | Like `env` but excluded from the cache key. | | `runtime_pass_env` | `list[string]` | no | Like `pass_env` but excluded from the cache key. | +| `pre_run` | `list[string]` | yes | Shell lines run before the test binary. When non-empty, the target switches from the `exec` driver to the `bash` driver so the lines execute as shell. | ### How `go_src`/codegen resolution actually composes diff --git a/website/docs/plugins/go.md b/website/docs/plugins/go.md index 2544443..ee98e82 100644 --- a/website/docs/plugins/go.md +++ b/website/docs/plugins/go.md @@ -302,7 +302,7 @@ at multiple depths, the deepest (closest) ancestor wins. |-------------------|----------------------|----------| | `go_codegen_root` | `bool` | When `True` on an ancestor, `go_src` targets are searched across the whole subtree rooted here instead of only the leaf package. Use when one generator feeds many descendant packages. | | `go_codegen_deps` | `list[string]` | Explicit codegen target addresses injected into every descendant package's sandbox. For generators not labelled `go_src`. The closest ancestor carrying it wins. | -| `test` | `bool \| struct(...)` | Controls test-target generation and environment for this package and descendants. See below. | +| `test` | `bool \| struct(...)` | Controls test-target generation and configuration for this package and descendants. See below. | ### Skipping tests @@ -320,7 +320,7 @@ provider_state(provider = "go", test = True) ### Test environment -The struct form sets environment variables on the generated `test`/`xtest` run +The struct form configures the generated `test`/`xtest` run targets. Unlike the boolean form, it is **package-scoped**: it applies only to the exact package where the `provider_state` lives — descendants are not affected. A struct-form state also re-enables tests even when an ancestor set @@ -334,6 +334,7 @@ provider_state( "pass_env": ["HOME"], # hashed; affects the cache key "runtime_env": {"BAR": "2"}, # not hashed; runtime-only "runtime_pass_env": ["PATH"], # not hashed; runtime-only + "pre_run": ["export FOO=bar", "mkdir -p ./scratch"], }, ) ``` @@ -344,6 +345,7 @@ provider_state( | `pass_env` | `list[string]` | yes | Names of host env vars forwarded to the test run. | | `runtime_env` | `map[string]` | no | Like `env` but excluded from the cache key. | | `runtime_pass_env` | `list[string]` | no | Like `pass_env` but excluded from the cache key. | +| `pre_run` | `list[string]` | yes | Shell lines run before the test binary. When non-empty, the target switches from the `exec` driver to the `bash` driver so the lines execute as shell. | ## Claude Code plugin