Chore: Set up helmcov and helmdocs for charts.

.githooks/pre-commit

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(git rev-parse --show-toplevel)"
+cd "$repo_root"
+
+staged="$(git diff --cached --name-only --diff-filter=ACMR || true)"
+
+if [[ -z "${staged}" ]]; then
+  exit 0
+fi
+
+chart_changes=false
+docs_changes=false
+
+while IFS= read -r path; do
+  [[ -z "${path}" ]] && continue
+  case "${path}" in
+    charts/*)
+      chart_changes=true
+      ;;
+  esac
+  case "${path}" in
+    charts/*/Chart.yaml|charts/*/values.yaml|charts/*/README.md.gotmpl|charts/*/templates/*|scripts/helmdocs.sh|scripts/install-helm-docs.sh)
+      docs_changes=true
+      ;;
+  esac
+done <<< "${staged}"
+
+if [[ "${chart_changes}" != true && "${docs_changes}" != true ]]; then
+  exit 0
+fi
+
+# Contributors without Helm can't run the chart checks; warn rather than block
+# the commit. CI still enforces tests and docs on the PR.
+if ! command -v helm >/dev/null 2>&1; then
+  echo "pre-commit: helm not found; skipping chart tests and docs check (CI will enforce them)." >&2
+  echo "pre-commit: install Helm 3, or bypass this hook with 'git commit --no-verify'." >&2
+  exit 0
+fi
+
+# Validate the staged snapshot, not the working tree: stash unstaged/untracked
+# changes (keeping the index applied) so make runs against exactly what's being
+# committed. Restore the tree afterwards no matter how we exit.
+stashed=false
+if ! git diff --quiet || [[ -n "$(git ls-files --others --exclude-standard)" ]]; then
+  git stash push --keep-index --include-untracked --quiet
+  stashed=true
+fi
+
+restore() {
+  rc=$?
+  git checkout -- . >/dev/null 2>&1 || true          # drop anything make regenerated
+  if [[ "${stashed}" == true ]] && ! git stash pop --quiet; then
+    echo "pre-commit: FAILED to restore your unstaged/untracked changes." >&2
+    echo "pre-commit: they are safe in the stash — recover with 'git stash list' then 'git stash pop'." >&2
+    rc=1
+  fi
+  exit "${rc}"
+}
+trap restore EXIT
+
+if [[ "${chart_changes}" == true ]]; then
+  make test
+fi
+
+if [[ "${docs_changes}" == true ]]; then
+  if ! make docs-check; then
+    echo "Chart README(s) are out of date. Run 'make docs' and stage the updated README.md files." >&2
+    exit 1
+  fi
+fi

.github/workflows/helm-test.yaml

@@ -3,10 +3,19 @@ name: Helm Chart Tests
 on:
   push:
     branches: [ main ]
-    paths:
+    paths: &paths
       - 'charts/**'
+      - 'examples/**'
+      - 'Makefile'
+      - 'scripts/**'
+      - '.githooks/**'
+      - '.github/workflows/helm-test.yaml'
   pull_request:
     branches: [ main ]
+    paths: *paths
+
+permissions:
+  contents: read
 
 jobs:
   version-script-smoke:
@@ -57,39 +66,41 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
+
+      - name: Set up Helm
+        uses: azure/setup-helm@v4
         with:
-          fetch-depth: 0
+          version: v3.12.0
 
-      - name: Install dependencies
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y unzip git curl
+      - name: Install tools, run unit tests, verify docs
+        run: make ci-setup test docs-check
+
+  helmcov:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
 
       - name: Set up Helm
-        uses: azure/setup-helm@v3
+        uses: azure/setup-helm@v4
         with:
           version: v3.12.0
 
-      - name: Install helm-unittest plugin
-        run: |
-          helm plugin install https://github.com/helm-unittest/helm-unittest.git --version v1.0.3 ${{ runner.debug && '--debug' || ''}}
-
       - name: Build chart dependencies
-        run: |
-          helm repo add mongodb https://mongodb.github.io/helm-charts
-          helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
-          helm dependency build charts/clickstack
+        run: make chart-deps
 
-      - name: Validate example values render
-        run: |
-          helm template clickstack-example charts/clickstack \
-            -f examples/alb-ingress/values.yaml >/dev/null
-          helm template clickstack-example charts/clickstack \
-            -f examples/api-only/values.yaml >/dev/null
-          helm template clickstack-example charts/clickstack \
-            -f examples/otel-custom-config/values.yaml >/dev/null
-
-      - name: Run helm-unittest
-        run: |
-          helm unittest charts/clickstack
+      - name: Load pinned helmcov version and thresholds
+        run: grep -E '^(HELMCOV_VERSION|COVERAGE_THRESHOLD|BRANCH_COVERAGE_THRESHOLD)=' scripts/tool-versions.env >> "$GITHUB_ENV"
+
+      - name: Run helmcov
+        uses: ClickHouse/helmcov@f99c69183ad2528bf62828d6a02fb0d5f0da13ea  # v0.7.0
+        with:
+          chart: charts/clickstack
+          tests: charts/clickstack/tests
+          threshold: ${{ env.COVERAGE_THRESHOLD }}
+          branch-threshold: ${{ env.BRANCH_COVERAGE_THRESHOLD }}
+          version: ${{ env.HELMCOV_VERSION }}

.gitignore

@@ -14,5 +14,13 @@ node_modules
 
 charts/*/charts/*.tgz
 
+# helmcov
+coverage.out
+coverage.xml
+
+# local tooling
+.tools/
+.helmcov-work/
+
 # generated by scripts/extract-release-notes.js during release
 charts/*/RELEASE_NOTES.md

AGENTS.md

@@ -8,6 +8,22 @@ Helm charts for ClickStack (HyperDX observability platform). Two charts:
 
 Package manager: Yarn 4 (via Corepack). Versioning: Changesets.
 
+## Local Development
+
+Use the Makefile for tool setup, unit tests, and template coverage:
+
+```bash
+make setup      # install helm-unittest, helm-docs, chart deps, and git hooks
+make test       # helm-unittest + example values validation
+make coverage   # helmcov template coverage
+make integration  # Kind integration suites (SUITES=api-only for one)
+make ci         # test + coverage + docs verification
+```
+
+The pre-commit hook runs `make test` when staged files under `charts/` change, and
+`make docs` when chart values, templates, or README templates change. Install hooks
+with `make setup` or `make hooks`.
+
 ## Build & Dependency Commands
 
 ```bash
@@ -35,14 +51,8 @@ helm template clickstack-test charts/clickstack -f examples/api-only/values.yaml
 
 ### Unit Tests (helm-unittest)
 
-Requires the `helm-unittest` plugin:
-```bash
-helm plugin install https://github.com/helm-unittest/helm-unittest.git --version v1.0.3
-```
-
 ```bash
-# Run ALL unit tests
-helm unittest charts/clickstack
+make test
 
 # Run a SINGLE test file
 helm unittest -f tests/app-deployment_test.yaml charts/clickstack
@@ -54,18 +64,71 @@ helm unittest -f 'tests/clickhouse-*_test.yaml' charts/clickstack
 Test files live in `charts/clickstack/tests/` and follow the naming convention
 `<component>_test.yaml`. Snapshots are stored in `tests/__snapshot__/`.
 
+Shared value fixtures live in `charts/clickstack/tests/values/<case>.yaml` and are
+loaded with the suite-level `values:` key when a test needs more data than inline
+`set:` overrides comfortably provide:
+
+```yaml
+suite: Test Deployment Default Sources Tpl
+templates:
+  - hyperdx/deployment.yaml
+values:
+  - values/deployment-tpl-defaults.yaml
+tests:
+  - it: should render tpl-interpolated default connections
+    asserts:
+      - matchRegex:
+          path: spec.template.spec.containers[0].env[?(@.name=="DEFAULT_CONNECTIONS")].value
+          pattern: clickhouse-headless
+```
+
+Prefer inline `set:` for small overrides; use `tests/values/` for multi-field
+fixtures or tpl-heavy defaults reused across assertions.
+
+### Template Coverage (helmcov)
+
+```bash
+make coverage
+
+# Verbose per-file output
+VERBOSE=1 make coverage
+
+# Override the line and branch minimums
+COVERAGE_THRESHOLD=99 BRANCH_COVERAGE_THRESHOLD=90 make coverage
+```
+
+Downloads the helmcov release pinned in `scripts/tool-versions.env` into `.tools/`
+and fails below **99% line and 90% branch coverage**. Outputs `coverage.out` (Go
+coverprofile) and `coverage.xml` (Cobertura).
+
+CI runs the [helmcov GitHub Action](https://github.com/ClickHouse/helmcov)
+via the `helmcov` job in `.github/workflows/helm-test.yaml`, which posts or updates
+a pull request comment with line/branch coverage and uncovered details.
+
+### Chart README (helm-docs)
+
+```bash
+make docs
+```
+
+Regenerates `charts/*/README.md` from `values.yaml` using [helm-docs](https://github.com/norwoodj/helm-docs).
+Only values with `#` comments in `values.yaml` appear in the README (`--ignore-non-descriptions`).
+Each chart README includes version and CI build status badges.
+The pre-commit hook verifies docs are up to date when values or templates change.
+
 ### Integration Tests (Kind cluster)
 
 Suites live under `integration-tests/<suite-name>/`. Each has `suite.yaml`,
 `values.yaml`, and `assert.sh`. Run locally with:
 
 ```bash
-./integration-tests/run-suite.sh api-only    # or full-stack
-# Cleanup
-helm uninstall test-api-only || true
-kind delete cluster --name test-api-only || true
+make integration                 # every suite, as CI runs them
+make integration SUITES=api-only # one suite
 ```
 
+Each suite creates a `test-<suite>` Kind cluster and deletes it afterwards. The
+full-stack suite also runs `scripts/smoke-test.sh` and the Playwright checks in `scripts/e2e/`.
+
 Requires: `kind`, `helm`, `kubectl`, `yq`.
 
 ## Git Conventions
@@ -103,6 +166,8 @@ Requires: `kind`, `helm`, `kubectl`, `yq`.
 
 ### Values Structure (`values.yaml`)
 - Top-level keys: `global`, `hyperdx`, `clickhouse`, `mongodb`, `otel-collector`
+- Document user-facing values with `# --` comments directly above each key (helm-docs format)
+- `make docs` omits undocumented keys (`--ignore-non-descriptions`); prefer commenting parent keys for operator/subchart passthrough specs
 - `hyperdx.config` — non-sensitive env vars (ConfigMap), supports `tpl` expressions
 - `hyperdx.secrets` — sensitive env vars (Secret); set to `null` to skip creation
 - `hyperdx.deployment` — Deployment spec (image, replicas, resources, probes, etc.)
@@ -141,7 +206,7 @@ tests:
 
 ## Shell Script Conventions
 
-- Always start with `#!/bin/bash`, `set -e`, and `set -o pipefail`
+- Always start with `#!/usr/bin/env bash` and `set -euo pipefail`
 - Use uppercase for exported env vars: `RELEASE_NAME`, `NAMESPACE`, `SUITE_DIR`
 - Use functions for reusable logic (see `smoke-test.sh`, `run-suite.sh`)
 - Default variables with `${VAR:-default}` or `${1:?Usage message}`
@@ -150,7 +215,7 @@ tests:
 
 | Workflow | File | Trigger | Purpose |
 |----------|------|---------|---------|
-| Helm Chart Tests | `helm-test.yaml` | push/PR to main | Unit tests + example validation |
+| Helm Chart Tests | `helm-test.yaml` | push/PR to main | `helm-unittest` job (unit tests + example validation + docs check) and `helmcov` job (template coverage; PR comment with line/branch coverage) |
 | Integration Test | `chart-test.yml` | push/PR/nightly | Kind-based integration suites |
 | Release | `release.yml` | after tests pass on main | Changeset version + chart release |
 | Update App Version | `update-app-version.yml` | workflow_dispatch | Bump `appVersion` in Chart.yaml |
@@ -165,3 +230,4 @@ tests:
 - Example values: `examples/*/values.yaml`
 - Version sync script: `scripts/update-chart-versions.js`
 - Smoke test: `scripts/smoke-test.sh`
+- Makefile: `make setup`, `make test`, `make coverage`