testsAndMisc/.github/copilot-instructions.md

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)

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

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/)

# 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