# Story 1.4: Location Resolution (ICAO & Address)

Status: done

## Story

As a user setting up the device,
I want to type my home airfield ICAO code or my home address/postcode and have the device resolve it to coordinates and show the result for confirmation,
So that I can verify the device is centred on the correct location before committing.

## Acceptance Criteria

1. **Given** the user enters a valid ICAO code (e.g. `EGLL`) **When** "Find location" is pressed **Then** the bundled `airports.csv` is queried via `importlib.resources` and the matching lat/lon is returned **And** the resolved location name and coordinates are displayed on the portal for confirmation

2. **Given** the user enters an address or postcode (e.g. `OX1 1AA`) **When** "Find location" is pressed **Then** the Nominatim API is called once with the input and the resolved lat/lon is displayed for confirmation

3. **Given** the user enters an ICAO code not present in `airports.csv` **When** "Find location" is pressed **Then** the portal displays: "ICAO code not found — try an address instead"

4. **Given** Nominatim returns no results **When** "Find location" is pressed **Then** the portal displays: "Location not found — try a different search term"

5. **Given** tests run in CI **When** location tests execute **Then** Nominatim calls are mocked — no real network calls required in the test suite

## Tasks / Subtasks

- [x] Task 1: Implement `location.resolve(query)` in `src/planemapper/provisioning/location.py` (AC: #1, #2, #3, #4)
  - [x] 1.1 Normalise the input: `query = query.strip().upper()`
  - [x] 1.2 Detect ICAO heuristic: `len(query) == 4 and query.isalpha()` — if true, attempt ICAO lookup first
  - [x] 1.3 ICAO lookup: open `airports.csv` via `importlib.resources.files("planemapper.data").joinpath("airports.csv").open("r", encoding="utf-8")`; parse with `csv.DictReader`; search for row where `row["ident"] == query`; return `(float(row["latitude_deg"]), float(row["longitude_deg"]), row["name"])`
  - [x] 1.4 If ICAO lookup finds no match, raise `ValueError("ICAO code not found — try an address instead")`
  - [x] 1.5 Non-ICAO path: call `requests.get("https://nominatim.openstreetmap.org/search", params={"q": query, "format": "json", "limit": 1}, headers={"User-Agent": "planemapper/0.1 (https://github.com/football2801/planeMapper)"}, timeout=10)`
  - [x] 1.6 Parse Nominatim response: if `results` list is non-empty, return `(float(results[0]["lat"]), float(results[0]["lon"]), results[0]["display_name"])`
  - [x] 1.7 If Nominatim returns an empty list, raise `ValueError("Location not found — try a different search term")`
  - [x] 1.8 Annotate the function signature: `def resolve(query: str) -> tuple[float, float, str]`

- [x] Task 2: Add `POST /find-location` route to `src/planemapper/provisioning/portal.py` (AC: #1, #2, #3, #4)
  - [x] 2.1 Import `location` from `planemapper.provisioning` at the top of `portal.py`
  - [x] 2.2 Implement `POST /find-location` — read `request.form["location"]` field
  - [x] 2.3 Call `location.resolve(query)` inside a `try/except ValueError`
  - [x] 2.4 On success: return updated form HTML showing the resolved name and coordinates (e.g. a confirmation section with `lat`, `lon`, `name` values visible) and hidden fields pre-populated with `lat`/`lon` for subsequent form submit
  - [x] 2.5 On `ValueError`: return updated form HTML with the error message displayed inline (no 4xx status — keep the form usable)
  - [x] 2.6 Annotate the route function with return type `str | Response`

- [x] Task 3: Write tests in `tests/provisioning/test_location.py` (AC: #1, #2, #3, #4, #5)
  - [x] 3.1 Test ICAO lookup hit: call `resolve("EGLL")` against the real `airports.csv`; assert returned `(lat, lon, name)` is a `tuple[float, float, str]` with plausible UK coordinates
  - [x] 3.2 Test ICAO lookup miss: call `resolve("ZZZZ")`; assert `ValueError` is raised with message `"ICAO code not found — try an address instead"`
  - [x] 3.3 Test Nominatim success: patch `planemapper.provisioning.location.requests.get` with `unittest.mock.patch`; mock return value `.json()` returns `[{"lat": "51.5", "lon": "-0.1", "display_name": "London"}]`; call `resolve("OX1 1AA")`; assert `(51.5, -0.1, "London")` returned
  - [x] 3.4 Test Nominatim empty response: patch `requests.get` as above but `.json()` returns `[]`; call `resolve("nonsense query")`; assert `ValueError` is raised with message `"Location not found — try a different search term"`
  - [x] 3.5 Assert the mock was called exactly once with the expected URL and `User-Agent` header (confirms no real HTTP in CI)

- [x] Task 4: Update portal tests in `tests/provisioning/test_portal.py` (AC: #1, #2, #3, #4)
  - [x] 4.1 Add test for `POST /find-location` with a successful resolve (mock `location.resolve` to return `(51.5, -0.1, "London")`); assert 200 and that the response body contains the resolved name and coordinates
  - [x] 4.2 Add test for `POST /find-location` with a `ValueError` from `location.resolve`; assert 200 and that the response body contains the error message text

- [x] Task 5: Run quality gates
  - [x] 5.1 `pytest tests/` — all tests pass, 0 failures
  - [x] 5.2 `ruff check .` — zero violations
  - [x] 5.3 `ruff format --check .` — no formatting issues

## Dev Notes

### CSV parsing via `importlib.resources`

Use `csv.DictReader` and access the bundled file through `importlib.resources`:

```python
import csv
import importlib.resources

def _lookup_icao(code: str) -> tuple[float, float, str] | None:
    traversable = importlib.resources.files("planemapper.data").joinpath("airports.csv")
    with traversable.open("r", encoding="utf-8") as fh:
        reader = csv.DictReader(fh)
        for row in reader:
            if row["ident"] == code:
                return float(row["latitude_deg"]), float(row["longitude_deg"]), row["name"]
    return None
```

OurAirports CSV columns used: `ident` (4-letter ICAO code), `name`, `latitude_deg`, `longitude_deg`.

### ICAO detection heuristic

```python
query = query.strip().upper()
if len(query) == 4 and query.isalpha():
    # try ICAO first
```

This is not a perfect ICAO validator but is sufficient for MVP. A 4-letter all-alpha string is almost certainly an ICAO code in this context.

### Nominatim call

```python
import requests

NOMINATIM_URL = "https://nominatim.openstreetmap.org/search"
USER_AGENT = "planemapper/0.1 (https://github.com/football2801/planeMapper)"

def _geocode(query: str) -> tuple[float, float, str] | None:
    resp = requests.get(
        NOMINATIM_URL,
        params={"q": query, "format": "json", "limit": 1},
        headers={"User-Agent": USER_AGENT},
        timeout=10,
    )
    resp.raise_for_status()
    results = resp.json()
    if not results:
        return None
    r = results[0]
    return float(r["lat"]), float(r["lon"]), r["display_name"]
```

The `User-Agent` header is required by Nominatim's usage policy.

### Return type and coordinate convention

`resolve(query: str) -> tuple[float, float, str]` — always `(lat, lon, name)`, never `(lon, lat)`. This convention is used throughout the codebase.

### Test mock path

```python
from unittest.mock import patch, MagicMock

@patch("planemapper.provisioning.location.requests.get")
def test_nominatim_success(mock_get):
    mock_resp = MagicMock()
    mock_resp.json.return_value = [{"lat": "51.5", "lon": "-0.1", "display_name": "London"}]
    mock_get.return_value = mock_resp
    lat, lon, name = resolve("OX1 1AA")
    assert lat == 51.5
    assert lon == -0.1
    assert name == "London"
    mock_get.assert_called_once()
```

Patching at `planemapper.provisioning.location.requests.get` (the module where `requests` is imported, not the `requests` package directly) ensures no real HTTP calls reach Nominatim in CI.

### `airports.csv` file path

The CSV must be declared as package data in `pyproject.toml` (or `setup.cfg`) so that `importlib.resources` can find it at runtime and during tests. Confirm `[tool.setuptools.package-data]` includes `"planemapper.data" = ["*.csv"]` (this should already be in place from Story 1.1 scaffold).