# Timesheets — Agent Guide

## Project overview

A Python CLI tool that parses markdown pipe-delimited timesheet tables and
exports them to CSV for import into Odoo (or similar tools). It also supports
a human-readable summary view.

### Package layout

```
timesheets/
├── pyproject.toml                  # package metadata, entry point, dev dependencies
├── AGENTS.md
└── src/timesheets/
    ├── cli.py        # argument parsing, main() entry point
    ├── parser.py     # markdown table parsing and row aggregation
    ├── projects.py   # project_map.json loading and key resolution
    ├── output.py     # CSV writing and summary printing
    └── utils.py      # shared low-level helpers (duration parsing, formatting, etc.)
```

Tests live in `tests/`, one file per source module:

```
tests/
├── test_utils.py
├── test_parser.py
├── test_projects.py
└── test_output.py
```

---

## Package manager — uv

All dependency management and script execution is done via [`uv`](https://docs.astral.sh/uv/).
Do **not** use `pip` or `python` directly.

| Task | Command |
|---|---|
| Install / sync dependencies | `uv sync` |
| Add a runtime dependency | `uv add <package>` |
| Add a dev-only dependency | `uv add --dev <package>` |
| Run the CLI | `uv run timesheets <args>` |
| Run any Python script | `uv run python <script>` |

---

## CLI usage

```sh
# Print CSV to stdout (date defaults to today)
uv run timesheets input.md

# Write CSV to a file
uv run timesheets input.md -o output.csv

# Override the date (DD/MM/YY)
uv run timesheets input.md --date 22/03/26

# Use a specific project map file
uv run timesheets input.md --map /path/to/project_map.json

# Print a human-readable summary instead of CSV
uv run timesheets input.md --summary

# Read from stdin
cat input.md | uv run timesheets -
```

`project_map.json` is auto-discovered in the current working directory if
`--map` is not provided.

---

## Testing

The test suite uses **pytest** with **pytest-cov** for coverage reporting.

```sh
# Run all tests
uv run pytest

# Run with coverage report
uv run pytest --cov

# Run a specific test file
uv run pytest tests/test_parser.py

# Run a specific test
uv run pytest tests/test_parser.py::TestParseTable::test_empty_input
```

### Rules for adding or changing functionality

1. **Always update or add tests** when introducing new behaviour or modifying
   existing behaviour. Tests live in the `tests/` file that corresponds to the
   module being changed (e.g. changes to `parser.py` → `tests/test_parser.py`).

2. **Run the full test suite before finishing** and confirm it passes with no
   failures:
   ```sh
   uv run pytest --cov
   ```

3. **Do not reduce coverage.** Every new function or branch should have at
   least one test covering the happy path. Edge cases and error paths should be
   covered where the logic is non-trivial.

4. `cli.py` is intentionally excluded from unit tests — it is thin glue code.
   All logic worth testing belongs in the other modules.