mirror of
https://github.com/kuhyx/testsAndMisc.git
synced 2026-07-05 22:43:07 +02:00
Krzysztof kuhy Rudnicki
2518528c86
- Add C engine build/usage commands and key files - Document stockfish_analysis, keyboard_coop, mock_server, screen_locker - List other standalone scripts
118 lines
3.9 KiB
Markdown
118 lines
3.9 KiB
Markdown
# Copilot Instructions for testsAndMisc
|
|
|
|
## Project Overview
|
|
|
|
A mixed-language monorepo containing Python packages, C programs, TypeScript apps, and misc scripts. The primary actively-developed component is `python_pkg/lichess_bot/` - a Lichess chess bot.
|
|
|
|
## Architecture
|
|
|
|
### Python Packages (`python_pkg/`)
|
|
|
|
- **lichess_bot/** - Main project: Lichess bot with 100% test coverage requirement
|
|
- `main.py` - Bot entry point, game handling, event loop
|
|
- `lichess_api.py` - Lichess API client (NDJSON streaming)
|
|
- `engine.py` - Wraps C engine at `C/lichess_random_engine/`
|
|
- `tests/` - Comprehensive pytest tests using `MagicMock`, `PropertyMock`, `patch`
|
|
- **stockfish_analysis/** - Post-game analysis using Stockfish engine
|
|
- Called by lichess_bot after games to analyze move quality
|
|
- Parses PGN from game logs, outputs per-move evaluations
|
|
- **keyboard_coop/** - 2-player cooperative word game (pygame)
|
|
- Players form words using adjacent QWERTY keys
|
|
- **mock_server/** - mitmproxy-based connection failure simulator
|
|
- **screen_locker/** - Tkinter screen lock with systemd integration
|
|
- Other standalone scripts: download_cats, extract_links, random_jpg, etc.
|
|
|
|
### C Engine (`C/lichess_random_engine/`)
|
|
|
|
Chess move selection engine called by Python via subprocess:
|
|
|
|
```bash
|
|
# Build the engine
|
|
cd C/lichess_random_engine && make
|
|
|
|
# Binary usage (called by python_pkg/lichess_bot/engine.py)
|
|
./random_engine --fen "<FEN>" move1 move2 move3... # Returns chosen UCI move
|
|
./random_engine --fen "<FEN>" --explain move1... # Returns JSON with analysis
|
|
```
|
|
|
|
**Key files:**
|
|
|
|
- `main.c` - CLI interface, argument parsing
|
|
- `movegen.c/h` - Legal move generation
|
|
- `search.c/h` - Alpha-beta search with scoring
|
|
- `Makefile` - Build with `make`, clean with `make clean`
|
|
|
|
### Cross-Language Integration
|
|
|
|
- Python `engine.py` → calls C binary via `subprocess.Popen`
|
|
- Python `stockfish_analysis/` → post-game analysis subprocess
|
|
|
|
## Development Workflow
|
|
|
|
### Testing (Critical - 100% coverage enforced)
|
|
|
|
```bash
|
|
# Run lichess_bot tests with coverage
|
|
python -m pytest python_pkg/lichess_bot/tests/ --cov=python_pkg.lichess_bot --cov-branch --cov-fail-under=100
|
|
|
|
# Quick test run
|
|
python -m pytest python_pkg/lichess_bot/tests/ -x -v
|
|
```
|
|
|
|
### Pre-commit Hooks (Always run before commits)
|
|
|
|
```bash
|
|
pre-commit run --all-files # Full check
|
|
pre-commit run --files <file1> <file2> # Specific files
|
|
```
|
|
|
|
**Hook order**: ruff (lint+fix) → ruff-format → mypy → pylint → bandit
|
|
|
|
### Linting Tools Configured in `pyproject.toml`
|
|
|
|
- **ruff**: `select = ["ALL"]` - all rules enabled, Google docstrings
|
|
- **mypy**: `strict = true` with full type checking
|
|
- **pylint**: all checks enabled
|
|
- **coverage**: `fail_under = 100`, branch coverage required
|
|
|
|
## Code Conventions
|
|
|
|
### Python Style
|
|
|
|
- Use `from __future__ import annotations` for forward references
|
|
- Google docstring convention
|
|
- Absolute imports only (`ban-relative-imports = "all"`)
|
|
- Type hints required on all functions
|
|
- Private functions prefixed with `_` (e.g., `_process_game_event`)
|
|
|
|
### Test Patterns (`python_pkg/lichess_bot/tests/`)
|
|
|
|
```python
|
|
# Type aliases for test dicts (keeps mypy happy)
|
|
Event = dict[str, Any]
|
|
GameThreads = dict[str, threading.Thread]
|
|
|
|
# Mock external calls, never hit real APIs
|
|
with patch("python_pkg.lichess_bot.main.threading.Thread") as mock:
|
|
...
|
|
|
|
# Use PropertyMock for property exceptions
|
|
type(mock_obj).property_name = PropertyMock(side_effect=TypeError())
|
|
```
|
|
|
|
### Branch Coverage Tips
|
|
|
|
- Use explicit `while True` + `try/except StopIteration` instead of `for` loops when iterator exhaustion needs coverage
|
|
- Mock threads/subprocesses to avoid slow tests
|
|
|
|
## Key Files
|
|
|
|
- `pyproject.toml` - All tool configs (ruff, mypy, pylint, pytest, coverage)
|
|
- `.pre-commit-config.yaml` - Pre-commit hook definitions
|
|
- `requirements.txt` - Runtime dependencies
|
|
- `.github/workflows/python-tests.yml` - CI pipeline
|
|
|
|
## Per-File Ignores (in `pyproject.toml`)
|
|
|
|
Test files allow: `S101` (assert), `PLR2004` (magic values), `S310`, `S607`, `PLC0415`
|