From bebcfb11e88aaef131289ee88afb31a2496827a4 Mon Sep 17 00:00:00 2001
From: Krzysztof kuhy Rudnicki <krzysztofrudnicki0@gmail.com>
Date: Tue, 2 Dec 2025 22:15:22 +0100
Subject: [PATCH] Add .github/copilot-instructions.md for AI coding agents

Documents:
- Project architecture and cross-language integration
- 100% test coverage requirement and testing commands
- Pre-commit workflow and tool configuration
- Code conventions and test patterns
- Key files and per-file lint ignores
---
 .github/copilot-instructions.md | 90 +++++++++++++++++++++++++++++++++
 1 file changed, 90 insertions(+)
 create mode 100644 .github/copilot-instructions.md

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..307b680
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,90 @@
+# 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`
+- Other packages are standalone scripts (download_cats, screen_locker, etc.)
+
+### 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`