From 9130bdc4528d5199a44b7afc912c65b307ec580a Mon Sep 17 00:00:00 2001 From: Douglas J Hunley Date: Thu, 3 Sep 2026 12:32:34 -0400 Subject: [PATCH 1/2] docs: add CLAUDE.md documenting the local pre-push gate Names the two local checks CI runs: pre-commit run --all-files (black pinned to 24.2.0, bin/compile.py, bin/check_lints.py, hygiene hooks) and the docker-compose pg_regress suite. Every command verified against the repo's own .pre-commit-config.yaml and .github/workflows/*.yaml. --- CLAUDE.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..54c28c3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,36 @@ +# CLAUDE.md + +Guidance for Claude Code sessions working in this repo. + +## What this is + +`splinter` (Supabase Postgres LINTER) maintains a set of SQL-based lints for +Supabase Postgres projects, checked via `bin/check_lints.py` and compiled +via `bin/compile.py`. + +## Build / test / lint + +``` +pre-commit run --all-files +``` + +Runs the full local gate, matching `.github/workflows/pre-commit_hooks.yaml`: +`black` (pinned to `24.2.0` in `.pre-commit-config.yaml` - install that exact +version in a venv, since a newer `black`'s reformatting can differ), +`bin/compile.py` (compiles the SQL lint files), `bin/check_lints.py` (checks +every lint is fully registered), plus standard hygiene hooks +(trailing-whitespace, check-yaml, mixed-line-ending, remove-tabs). + +``` +PG_VERSION= docker compose -f dockerfiles/docker-compose.yml build +PG_VERSION= docker compose -f dockerfiles/docker-compose.yml run test +``` + +Runs the real pg_regress test suite against a live Postgres, matching +`.github/workflows/test.yml`. Rebuild with `--no-cache` after any +dependency/lockfile change - a bare `docker compose run` reuses the last +built image and can report a stale pass. + +A CI failure right after a commit that looks unrelated to your own change +can be drift on `main` picked up by a merge, not a regression in your own +work - diff `origin/main` fresh before assuming it's self-inflicted. From b1081bef51a2c9e7bea213d796da3b7b4c17e4c0 Mon Sep 17 00:00:00 2001 From: Douglas J Hunley Date: Thu, 3 Sep 2026 12:38:40 -0400 Subject: [PATCH 2/2] fix: correct env var, staleness fix, and black-install claims in CLAUDE.md PG_VERSION never selects a Postgres version -- dockerfiles/docker-compose.yml only reads SUPABASE_VERSION for its build arg, verified via docker compose config with both vars set. The rmi-first staleness fix and --rm flag now match the repo's own README/new-lint skill convention. Pre-commit builds its own isolated black env from the pinned rev, so the venv-install instruction was actively wrong; added the real prerequisite (python3.12 on PATH) instead. Also names bin/compile.py's tracked output (splinter.sql) and completes the hygiene-hook list. Every documented command re-run for real (pre-commit run --all-files: 8/8 hooks passed; the docker test suite: 28/28 tests passed) after this edit. --- CLAUDE.md | 35 +++++++++++++++++++---------------- 1 file changed, 19 insertions(+), 16 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 54c28c3..7f8f2d9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,8 +5,10 @@ Guidance for Claude Code sessions working in this repo. ## What this is `splinter` (Supabase Postgres LINTER) maintains a set of SQL-based lints for -Supabase Postgres projects, checked via `bin/check_lints.py` and compiled -via `bin/compile.py`. +Supabase Postgres projects. `bin/check_lints.py` checks every lint is fully +registered, and `bin/compile.py` compiles all lint views into the tracked, +generated `splinter.sql` (`UNION ALL` of every `lints/*.sql` view) - don't +hand-edit `splinter.sql` directly, it's overwritten by `bin/compile.py`. ## Build / test / lint @@ -15,22 +17,23 @@ pre-commit run --all-files ``` Runs the full local gate, matching `.github/workflows/pre-commit_hooks.yaml`: -`black` (pinned to `24.2.0` in `.pre-commit-config.yaml` - install that exact -version in a venv, since a newer `black`'s reformatting can differ), -`bin/compile.py` (compiles the SQL lint files), `bin/check_lints.py` (checks -every lint is fully registered), plus standard hygiene hooks -(trailing-whitespace, check-yaml, mixed-line-ending, remove-tabs). +`black` (pinned to `24.2.0` in `.pre-commit-config.yaml`, needs a `python3.12` +interpreter on PATH for its hook env - pre-commit installs `black` itself, no +manual install needed), `bin/compile.py` (regenerates `splinter.sql`), +`bin/check_lints.py` (checks every lint is fully registered), plus standard +hygiene hooks (trailing-whitespace, excluding `test/expected` since those +`.out` files are whitespace-exact pg_regress golden files; check-added-large-files; +check-yaml; mixed-line-ending; remove-tabs). ``` -PG_VERSION= docker compose -f dockerfiles/docker-compose.yml build -PG_VERSION= docker compose -f dockerfiles/docker-compose.yml run test +docker rmi -f dockerfiles-test +SUPABASE_VERSION=15.1.1.13 docker-compose -f dockerfiles/docker-compose.yml run --rm test ``` Runs the real pg_regress test suite against a live Postgres, matching -`.github/workflows/test.yml`. Rebuild with `--no-cache` after any -dependency/lockfile change - a bare `docker compose run` reuses the last -built image and can report a stale pass. - -A CI failure right after a commit that looks unrelated to your own change -can be drift on `main` picked up by a merge, not a regression in your own -work - diff `origin/main` fresh before assuming it's self-inflicted. +`.github/workflows/test.yml`'s effective behavior (which sets `PG_VERSION`, +not `SUPABASE_VERSION` - a repo-side no-op both there and here, since +`dockerfiles/docker-compose.yml` only reads `SUPABASE_VERSION` for its build +arg). The `docker rmi -f` first is required, not optional: `docker compose +run` reuses the last built image, so a lint/test/expected-file change without +it can report a stale pass.