From ca28ec27259152bd61545277ff05cb3890231d48 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Vig=C3=A9e?= Date: Wed, 24 Jun 2026 13:03:36 +0100 Subject: [PATCH 1/2] docs: add heph validate guide and update CI guide heph validate was undocumented. PR hephbuild/heph#123 improved its behavior to report all failures at once instead of stopping at the first one, making it a clean CI gate. Document it and update the CI guide to use it in place of the manual gitignore check. --- website/docs/guides/ci.md | 14 ++++++------ website/docs/guides/validate.md | 38 +++++++++++++++++++++++++++++++++ website/sidebars.ts | 2 +- 3 files changed, 47 insertions(+), 7 deletions(-) create mode 100644 website/docs/guides/validate.md diff --git a/website/docs/guides/ci.md b/website/docs/guides/ci.md index 048f793..da09819 100644 --- a/website/docs/guides/ci.md +++ b/website/docs/guides/ci.md @@ -31,16 +31,18 @@ If a generated file is missing or out of date, the run exits non-zero with a diff — so a contributor who forgot to regenerate gets a red build, not a silent drift. -## Check the .gitignore is in sync +## Validate the workspace -`copy` codegen outputs belong in `.gitignore`, and heph maintains that block for -you. Make CI fail if it's out of date: +[`heph validate`](/docs/guides/validate) checks that every target resolves, that +no two `codegen = copy` targets write to the same path, and that `.gitignore` is +current — all in one read-only command: ```bash title="terminal" -heph tool gen-gitignore -git diff --exit-code .gitignore +heph validate --no-tui ``` +It reports every problem it finds, not just the first one. + ## Reuse the cache The [cache](/docs/concepts/caching) is keyed by input hash, so persisting it @@ -53,5 +55,5 @@ using your CI's caching mechanism, keyed on your lockfiles. ```bash title="terminal" heph run //... --no-tui --frozen # build everything; fail on stale codegen heph run //... --no-tui # run tests / checks -heph tool gen-gitignore && git diff --exit-code .gitignore +heph validate --no-tui # check targets resolve and .gitignore is current ``` diff --git a/website/docs/guides/validate.md b/website/docs/guides/validate.md new file mode 100644 index 0000000..7c0b8ab --- /dev/null +++ b/website/docs/guides/validate.md @@ -0,0 +1,38 @@ +--- +title: "Validating your workspace" +sidebar_position: 3 +description: Use heph validate to catch broken targets, overlapping codegen outputs, and a stale .gitignore before they reach CI. +--- + +# Validating your workspace + +`heph validate` checks your workspace without running any builds. It resolves every target's inputs, detects overlapping codegen outputs, and verifies that `.gitignore` is current. All three checks run in parallel and every failure is reported at once — not just the first one — so you can fix everything in a single pass. + +## What it checks + +| Check | What it catches | +|-------|-----------------| +| **Target link** | Every in-scope target is parsed and its runtime inputs are resolved. A missing dependency or an unresolvable target surfaces here. No execution happens. | +| **Codegen overlap** | Two `codegen = copy` targets that write to the same output path. | +| **`.gitignore` freshness** | The `.gitignore` block maintained by heph is out of date. If stale, the error message tells you to run `heph tool gen-gitignore`. Skipped when a package matcher is provided. | + +## Usage + +```bash title="terminal" +heph validate # whole workspace +heph validate //pkg/... # scope to a package matcher +``` + +When a package matcher is provided, the `.gitignore` freshness check is skipped (it applies to the whole workspace), and a warning is printed to say so. The target link and overlap checks still run. + +If any check fails, `heph validate` exits non-zero and lists every problem it found. + +## In CI + +`heph validate` is a natural CI gate: it is read-only, exits non-zero on any problem, and surfaces all failures in one run. + +```bash title="terminal" +heph validate --no-tui +``` + +Use `--no-tui` to force plain log output in headless environments. See [Using heph in CI](/docs/guides/ci) for a representative CI job. diff --git a/website/sidebars.ts b/website/sidebars.ts index bbb9f02..0d51f0b 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -30,7 +30,7 @@ const sidebars: SidebarsConfig = { type: 'category', label: 'Guides', collapsible: false, - items: ['guides/first-build', 'guides/ci', 'guides/remote-cache', 'guides/inspecting-builds', 'guides/editor-setup', 'guides/claude-code-plugin'], + items: ['guides/first-build', 'guides/ci', 'guides/validate', 'guides/remote-cache', 'guides/inspecting-builds', 'guides/editor-setup', 'guides/claude-code-plugin'], }, { type: 'category', From 3d501daf52791b934021a38926429961d9f9bbc2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Vig=C3=A9e?= Date: Wed, 24 Jun 2026 20:46:18 +0100 Subject: [PATCH 2/2] docs: remove --no-tui flags from validate and CI guides --- website/docs/guides/ci.md | 15 ++++++--------- website/docs/guides/validate.md | 4 ++-- 2 files changed, 8 insertions(+), 11 deletions(-) diff --git a/website/docs/guides/ci.md b/website/docs/guides/ci.md index da09819..4fd21d8 100644 --- a/website/docs/guides/ci.md +++ b/website/docs/guides/ci.md @@ -11,11 +11,8 @@ few flags make CI runs cleaner and turn heph's guarantees into gates. ## Plain log output -The interactive TUI assumes a terminal. In CI, force log-only output: - -```bash title="terminal" -heph run //... --no-tui -``` +The interactive TUI assumes a terminal. In CI, force log-only output with +`--no-tui`. ## Fail on stale codegen @@ -38,7 +35,7 @@ no two `codegen = copy` targets write to the same path, and that `.gitignore` is current — all in one read-only command: ```bash title="terminal" -heph validate --no-tui +heph validate ``` It reports every problem it finds, not just the first one. @@ -53,7 +50,7 @@ using your CI's caching mechanism, keyed on your lockfiles. ## A representative job ```bash title="terminal" -heph run //... --no-tui --frozen # build everything; fail on stale codegen -heph run //... --no-tui # run tests / checks -heph validate --no-tui # check targets resolve and .gitignore is current +heph run //... --frozen # build everything; fail on stale codegen +heph run //... # run tests / checks +heph validate # check targets resolve and .gitignore is current ``` diff --git a/website/docs/guides/validate.md b/website/docs/guides/validate.md index 7c0b8ab..db06809 100644 --- a/website/docs/guides/validate.md +++ b/website/docs/guides/validate.md @@ -32,7 +32,7 @@ If any check fails, `heph validate` exits non-zero and lists every problem it fo `heph validate` is a natural CI gate: it is read-only, exits non-zero on any problem, and surfaces all failures in one run. ```bash title="terminal" -heph validate --no-tui +heph validate ``` -Use `--no-tui` to force plain log output in headless environments. See [Using heph in CI](/docs/guides/ci) for a representative CI job. +See [Using heph in CI](/docs/guides/ci) for a representative CI job.