Metadata-Version: 2.4
Name: codeguessr
Version: 0.1.0
Summary: A GeoGuessr-style browser game for code
Project-URL: Homepage, https://github.com/eroeum/codeguessr
Project-URL: Source, https://github.com/eroeum/codeguessr
Project-URL: Issues, https://github.com/eroeum/codeguessr/issues
License: MIT
Classifier: Environment :: Web Environment
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: fastapi>=0.110
Requires-Dist: pathspec>=0.12
Requires-Dist: uvicorn[standard]>=0.29
Provides-Extra: dev
Requires-Dist: httpx; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: playwright; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# CodeGuessr

A [GeoGuessr](https://www.geoguessr.com/)-style browser game for code. Point it at any local repository and try to identify which file a code snippet came from — before all the clues run out.

The UI is styled to look like VS Code.

---

## How it works

Each game consists of several rounds. In every round, a random file from your project is selected and a snippet is shown. The snippet starts almost completely hidden and progressively reveals more code as you make wrong guesses. Click a file in the explorer to guess — the faster you identify it, the more points you earn.

### Reveal progression

| Wrong guesses | What you see |
|---|---|
| 0 | Entire file, all characters replaced with `█` |
| 1 | 1 line visible (centered on a key line) |
| 2 | 7 lines visible |
| 3 | 17 lines visible |
| 4 | 31 lines visible |
| 5 | Full file, no obscuring |

### Scoring

| Guess attempt | Points |
|---|---|
| 1st (no wrong guesses) | 1000 |
| 2nd | 800 |
| 3rd | 600 |
| 4th | 400 |
| 5th | 200 |
| 6th (last chance) | 100 |

---

## Supported languages

TypeScript · JavaScript · Python · Go · Rust · Java · C++ · C · Ruby · Swift · Kotlin · C# · PHP

---

## Installation

**Requirements:** Python 3.11+, Node.js 18+

```bash
# 1. Clone the repo
git clone <repo-url>
cd codeguessr

# 2. Build the frontend and install the package
make install

# or manually:
cd client && npm install && npm run build -- --output-path=../src/codeguessr/static
cd ..
pip install -e .
```

---

## Usage

```bash
# Run against the current directory
codeguessr

# Run against a specific project
codeguessr /path/to/your/project

# Use a different port (default: 4200)
codeguessr --port 8080 /path/to/your/project
```

The browser opens automatically at `http://localhost:4200`.

---

## Settings

Before each game, a VS Code-style settings screen lets you configure:

| Setting | Default | Description |
|---|---|---|
| Rounds | 5 | Number of rounds per game (1–20) |
| Guesses per round | 6 | Wrong guesses allowed before the round ends (1–10) |
| Min lines per file | 10 | Files shorter than this are excluded (1–500) |
| Min chars in highlighted line | 1 | Ensures the focal line has meaningful content (0–200) |
| Include pattern | *(empty)* | Regex — only matching file paths are included |
| Ignore pattern | *(empty)* | Regex — matching file paths are excluded |

Settings are saved to `localStorage` and restored on next visit.

The include/ignore patterns are applied to relative file paths (forward-slash separated). The game also respects any `.gitignore` files found in the scanned directory.

---

## Development

```
codeguessr/
├── src/codeguessr/
│   ├── game.py      # Core logic: file scanning, game state, scoring
│   ├── server.py    # FastAPI app — API routes + Angular SPA catch-all
│   ├── cli.py       # Click CLI entry point
│   └── static/      # Built Angular output (generated by make build)
├── client/          # Angular 17 standalone app
│   └── src/app/
│       ├── settings/    # Landing/settings screen
│       ├── game/        # Main game screen
│       └── results/     # End-of-game summary
├── tests/
│   ├── test_game.py # Unit tests for game logic
│   └── test_api.py  # Integration tests for the FastAPI endpoints
├── Makefile
└── pyproject.toml
```

### Running in development

```bash
# Terminal 1 — backend (auto-reload)
CODEGUESSR_DIR=/path/to/project uvicorn codeguessr.server:app --reload

# Terminal 2 — frontend (dev server with proxy)
cd client && npm start
```

### Running tests

```bash
pip install -e ".[dev]"
pytest
```

### Rebuilding after frontend changes

```bash
make build
```

---

## How the backend works

- **`scan_directory`** walks the project tree, skips pruned directories (`node_modules`, `.git`, `__pycache__`, etc.), respects `.gitignore` files at every directory level using [`pathspec`](https://github.com/cpburnz/python-pathspec), and returns a sorted list of qualifying relative file paths.
- **`GameSession`** holds the round state for one game. Each round stores a randomly chosen file and a "highlight line" picked from the middle 80% of the file. The session lives in an in-memory dict keyed by a UUID.
- **`/api/game/new`** re-scans the directory with the settings from the request body, creates a session, and returns the first round's payload.
- **`/api/game/{id}/guess`** checks the guess, updates the round state, and returns an updated code display with more lines revealed.
- The Angular SPA is served via a catch-all route registered *after* the API routes.
