feat: add runnable simulator foundation

2026-07-12 23:06:25 +03:00
parent 8804a3ec47
commit e11014ea26
25 changed files with 739 additions and 0 deletions
@@ -0,0 +1,85 @@
+PYTHON ?= python3.13
+VENV ?= .venv
+BIN := $(VENV)/bin
+COMPOSE ?= docker compose
+
+.PHONY: help install format lint typecheck test test-unit test-integration test-contract coverage run dev docker-build docker-up docker-down docker-logs db-up db-down db-migrate db-reset api-import api-diff seed clean ci
+
+help: ## Show available commands
+	@awk 'BEGIN {FS = ":.*## "}; /^[a-zA-Z0-9_-]+:.*## / {printf "%-18s %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+
+install: ## Create the Python 3.13 environment and install development dependencies
+	$(PYTHON) -m venv $(VENV)
+	$(BIN)/python -m pip install --upgrade "pip>=25.1,<26"
+	$(BIN)/python -m pip install -e '.[dev]'
+
+format: ## Format Python sources
+	$(BIN)/ruff format .
+
+lint: ## Run Ruff lint checks
+	$(BIN)/ruff check .
+
+typecheck: ## Run strict mypy checks
+	$(BIN)/mypy
+
+test: ## Run all offline tests
+	$(BIN)/pytest
+
+test-unit: ## Run unit tests
+	$(BIN)/pytest tests/unit
+
+test-integration: ## Run tests that require PostgreSQL
+	$(BIN)/pytest -m integration
+
+test-contract: ## Run offline API contract tests
+	$(BIN)/pytest -m contract
+
+coverage: ## Run tests with coverage enforcement
+	$(BIN)/pytest --cov=app --cov-report=term-missing --cov-report=xml
+
+run: ## Run the application
+	$(BIN)/uvicorn app.main:app --host "$${APP_HOST:-0.0.0.0}" --port "$${APP_PORT:-8006}"
+
+dev: ## Run with auto-reload
+	$(BIN)/uvicorn app.main:app --reload --host "$${APP_HOST:-0.0.0.0}" --port "$${APP_PORT:-8006}"
+
+docker-build: ## Build the runtime image
+	$(COMPOSE) build simulator
+
+docker-up: ## Start PostgreSQL and simulator
+	@test -f .env || cp .env.example .env
+	$(COMPOSE) up -d --build
+
+docker-down: ## Stop local services
+	$(COMPOSE) down
+
+docker-logs: ## Follow simulator logs
+	$(COMPOSE) logs -f simulator
+
+db-up: ## Start PostgreSQL only
+	$(COMPOSE) up -d postgres
+
+db-down: ## Stop PostgreSQL
+	$(COMPOSE) stop postgres
+
+db-migrate: ## Apply database migrations
+	@echo "Database migrations are scheduled for milestone D1" >&2; exit 2
+
+db-reset: ## Recreate the local database volume
+	$(COMPOSE) down -v
+	$(COMPOSE) up -d postgres
+
+api-import: ## Import an API snapshot
+	@echo "API import is scheduled for milestone B4" >&2; exit 2
+
+api-diff: ## Compare API snapshots
+	@echo "API diff is scheduled for milestone B5" >&2; exit 2
+
+seed: ## Seed simulation data
+	@echo "Database seed is scheduled for milestone D2" >&2; exit 2
+
+clean: ## Remove generated local artifacts
+	rm -rf $(VENV) .coverage coverage.xml htmlcov .mypy_cache .pytest_cache .ruff_cache
+
+ci: format lint typecheck coverage ## Run the complete local quality gate
+