feat: centralize logic, narrow exceptions, add tests and dev tooling (v0.13.0)

Address all 5 review priorities from project review:
- Centralize duplicated logic: normalize_country(), _db_connection(),
  _build_result() helpers (#22)
- Narrow exception handling: replace 9 bare except Exception blocks
  with specific types (#23)
- Add Makefile, pre-commit hooks, ruff format CI check (#24)
- Add 69 pytest tests covering postal_patterns, data_loader, and
  API endpoints with CI test job (#25)
- Version bump to 0.13.0, requirements-dev.txt, .dockerignore updates

Closes #22, closes #23, closes #24, closes #25

Author: bk86a

.dockerignore

@@ -2,3 +2,8 @@ __pycache__
 *.pyc
 .git
 .env
+tests/
+Makefile
+.pre-commit-config.yaml
+requirements-dev.txt
+docs/

.github/workflows/ci.yml

@@ -20,6 +20,7 @@ jobs:
           python-version: "3.12"
       - run: pip install ruff
       - run: ruff check app/ scripts/
+      - run: ruff format --check app/ scripts/
 
   import-check:
     runs-on: ubuntu-latest
@@ -44,6 +45,16 @@ jobs:
       - name: Static security analysis
         run: pip install bandit && bandit -r app/ -c pyproject.toml
 
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install -r requirements-dev.txt
+      - run: pytest tests/ -v
+
   docker:
     runs-on: ubuntu-latest
     steps:
@@ -58,7 +69,7 @@ jobs:
 
   publish:
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-    needs: [lint, import-check, security, docker]
+    needs: [lint, import-check, test, security, docker]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6

.gitignore

@@ -7,3 +7,4 @@ build/
 .venv/
 venv/
 data/
+tests/*.csv

.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.13.0] - 2026-02-23
+
+### Added
+
+- **Automated test suite** (#25): 69 pytest tests covering `postal_patterns.py` (preprocessing, tercet_map, extraction), `data_loader.py` (normalize functions, all 5 lookup tiers), and FastAPI endpoints (`/lookup`, `/pattern`, `/health`). CI now runs tests before publish.
+- **Makefile** (#24): standard targets for `lint`, `format`, `test`, `run`, `docker-build`, `docker-run`.
+- **Pre-commit hooks** (#24): ruff lint + format via `.pre-commit-config.yaml`.
+- **`requirements-dev.txt`** (#22): dev/test dependencies (ruff, bandit, pip-audit, pytest).
+- **`ruff format` CI check** (#24): enforces consistent code formatting in CI.
+
+### Changed
+
+- **Centralized duplicated logic** (#22): `normalize_country()` replaces duplicate GR→EL blocks, `_db_connection()` context manager replaces 6 manual SQLite connect/close patterns, `_build_result()` helper replaces repetitive result dict construction across all lookup tiers.
+- **Narrowed exception handling** (#23): 9 bare `except Exception` blocks in `data_loader.py` replaced with specific types (`sqlite3.Error`, `httpx.RequestError`, `OSError`, etc.). Silent catch in `import_estimates.py` now logs a message.
+- **Return type hints** added to `dispatch()` and `_rate_limit_handler()` in `main.py`.
+
 ## [0.12.0] - 2026-02-23
 
 ### Fixed

Makefile

@@ -0,0 +1,19 @@
+.PHONY: lint format test run docker-build docker-run
+
+lint:
+	ruff check app/ scripts/
+
+format:
+	ruff format app/ scripts/
+
+test:
+	pytest tests/ -v
+
+run:
+	uvicorn app.main:app --reload --port 8000
+
+docker-build:
+	docker build -t postalcode2nuts .
+
+docker-run:
+	docker run -p 8000:8000 postalcode2nuts

app/__init__.py

@@ -1 +1 @@
-__version__ = "0.12.0"
+__version__ = "0.13.0"