# 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`

### Go Projects (`robotgo_demo/`)

- **robotgo_demo/** - Desktop automation using [go-vgo/robotgo](https://github.com/go-vgo/robotgo)
  - `main.go` - Demo: mouse, keyboard, screen, clipboard, window control
  - Requires X11 (Arch Linux), built with `go build -o robotgo_demo .`
  - See `robotgo_demo/.github/copilot-instructions.md` for full API reference

### 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

**CRITICAL: NEVER use `--no-verify`** on `git commit` or `git push`, even when pre-commit failures are pre-existing and unrelated to your changes. Fix the failures or ask the user how to proceed — never bypass hooks.

### 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`