Development Workflow

Use local Git hooks to catch issues before pushing to GitHub CI.

Lefthook Setup

Install Lefthook and register hooks from the repository config:

# macOS
brew install lefthook
 
# Linux
# see https://lefthook.dev/installation/ for package-specific options
 
# from repository root
lefthook install

Hook Policy in This Repository

The repository ships a lefthook.yml policy with two levels:

• pre-commit (fast):
  • ruff format --check on staged Python files
  • ruff check on staged Python files
  • git diff --check --cached for whitespace/conflict-marker style issues
• pre-push (strict, CI-oriented):
  • uv run --extra lint ruff format --check .
  • uv run --extra lint ruff check .
  • uv run --extra test pytest
  • uv run python scripts/check_pipeline.py --mode ci
  • docs build (runs only when docs-affecting files changed in the push range): cd docs && CI=1 pnpm install --frozen-lockfile --prefer-offline --reporter=append-only && pnpm build

This setup mirrors the main CI jobs and reduces “works locally, fails in CI” cases.

Running Hooks Manually

lefthook run pre-commit
lefthook run pre-push

Documentation Sync With Code

When code structure changes, update docs in the same PR. Use this quick loop:

1. Detect stale path patterns in docs:

rg -n "src/hedgehog/stages/|structFilters/|dockingFilters/" docs/content modules/README.md | rg -v "rg -n "

2. Confirm current package layout:

find src/hedgehog -maxdepth 1 -type d | sort

3. Rebuild docs:

cd docs && CI=1 pnpm install --frozen-lockfile --prefer-offline --reporter=append-only && pnpm build

pnpm build runs a prebuild step that generates docs/content/api/index.mdx from runtime introspection (scripts/generate_api_docs.py). That file may be absent in a fresh checkout until the docs build runs. Do not edit the generated API page manually.

4. If CLI behavior changed, refresh docs/content/cli.mdx from:
   • uv run hedgehog --help
   • uv run hedge --help
   • uv run hedgehog run --help
   • uv run hedgehog setup --help
   • uv run hedgehog setup aizynthfinder --help
   • uv run hedgehog version

Temporary Skip (Use Sparingly)

You can skip a specific command once:

SKIP=docs-build git push

Use this only for exceptional cases; branch protection in GitHub should still require passing CI checks on pull requests.