gem-dota: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

This project is managed with uv. Prefer uv run — it uses the project's .venv without a manual source .venv/bin/activate. (CONTRIBUTING.md has the fuller contributor workflow; the list below is the day-to-day short version.)

# Install project + dev dependencies
uv sync --group dev

# Run default test suite (skips slow/integration/network markers via pyproject.toml)
uv run pytest

# Run all tests, including slow/integration/network markers
uv run pytest -m ""

# Run a single test file
uv run pytest tests/binary/test_reader.py

# Run a single test by name
uv run pytest tests/binary/test_reader.py::TestReadBits::test_read_8_bits

# Run with coverage
uv run pytest --cov=gem --cov-report=term-missing

# Explicit fast loop — equivalent to the default marker filter
uv run pytest -m "not slow and not integration and not network"

# Offline integration suite (requires local replay fixtures); 4 workers, one per
# shared parsed replay (tests/conftest.py groups them)
uv run pytest -m "integration and not network" -n 4 --dist loadgroup

# OpenDota parity checks the parity audit repeats; run with the audit
uv run pytest -m corpus -n 4 --dist loadgroup

# All offline tests
uv run pytest -m "not network"

# Live network smoke
uv run pytest -m network

# Broader remote draft integration sample (downloads/parses 5 pro replays)
GEM_DRAFT_INTEGRATION_FULL=1 uv run pytest tests/test_draft_integration.py -m integration

# Lint, format, type-check (run before committing)
uv run ruff check src/ tests/
uv run ruff format src/ tests/
uv run mypy src/gem/

# Regenerate protobuf modules after updating proto_definitions/
uv run python scripts/compile_protos.py

# Docs — the Astro site lives in site/ (Node 22+, see "Docs" below)
cd site && npm install && npm run dev

Architecture

Note: STRATEGY.md (the original implementation plan referenced in older versions of this file) has been removed. The living architecture references are now site/src/content/docs/architecture.md and the site/src/content/docs/deep-dives/ pages. CHANGELOG.md is the authoritative record of what shipped in each release.