# Repository Guidelines

## Project Structure & Module Organization
Source lives in `src/audiobooksorter/`: ingestion (`ingest.py`), sorting rules (`sorter/series_rules.py`), exporting (`export.py`), and the CLI (`cli.py`). Config defaults sit in `config/`, constants in `constants.py`, and shared logging in `logging.py`. Sample inputs for quick runs live in `samples/`. Test suites mirror the package under `tests/`, with fixtures in `tests/conftest.py`. Assets that do not execute (icons, mock exports) belong in `assets/`. Local library fixtures for manual checks live in `testdata/`.

## Build, Test, and Development Commands
Use Python 3.11+. Set up a venv and install dev tooling:
```
python -m venv .venv && source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e .[dev]
```
Preview ordering without writing files via `python -m audiobooksorter.cli --library ./testdata --dry-run`. Run against a JSON export with `python -m audiobooksorter.cli --library ./samples/library.json --output ./sorted_library.json`. Format and lint with `ruff check --fix` (plus `ruff format` if desired). Execute the suite using `pytest -q` (coverage gates are pre-configured).

## Coding Style & Naming Conventions
Follow PEP 8 with 4-space indentation and type hints on public surfaces. Prefer descriptive module names (`series_rules.py`, `ingest.py`) and uppercase constants. Use dataclasses for structured audiobook records and the shared logger from `logging.py` to centralize verbosity control.

## Testing Guidelines
Tests target `pytest` with coverage enforced at 90% (`pytest --cov=audiobooksorter --cov-report=term-missing`). Name files `test_<unit>.py` and tests `test_<behavior>`. Add regression cases whenever sorting order changes—especially around edge series, mixed narrators, or missing metadata—in both `tests/` and `testdata/` when a folder-based scenario is required.

## Commit & Pull Request Guidelines
Commit messages follow the `type(scope): summary` pattern (e.g., `feat(cli): add dry-run preview`). Reference issues in bodies (`Fixes #ID`). Pull requests should include a clear description of user-facing changes, testing evidence (command output is fine), and any migration notes for library paths or naming rules. Request review for sorting rule tweaks to avoid regressions in existing shelves.

## Security & Configuration Tips
Do not commit personal Audiobookshelf exports; anonymize anything checked into `samples/` or `testdata/`. Keep secrets (.env, tokens) out of the repo and load them at runtime. Validate file paths before writing outputs to avoid clobbering a user’s library.