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
• 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:

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

# 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