feat: Static code review

.github/workflows/python-tests.yml → .github/workflows/ci.yml

@@ -1,10 +1,10 @@
-name: Python Tests and Coverage
+name: CI
 
 on:
   push:
-    branches: [ main, feature/* ]
+    branches: [main, feature/*]
   pull_request:
-    branches: [ main ]
+    branches: [main]
 
 jobs:
   lint-pr-title:
@@ -23,23 +23,29 @@ jobs:
             exit 1
           fi
 
-  test:
+  quality:
     runs-on: ubuntu-latest
-
     steps:
-    - uses: actions/checkout@v4
-
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version: '3.9'
-
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install -r requirements.txt
-
-    - name: Run tests with coverage
-      run: |
-        export PYTHONPATH=$PYTHONPATH:.
-        pytest --cov=. --cov-report=term-missing --cov-fail-under=80 tests/
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.9"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff mypy types-requests -r requirements.txt
+
+      - name: Lint and format check
+        run: |
+          ruff check .
+          ruff format --check .
+
+      - name: Type check
+        run: mypy
+
+      - name: Tests and coverage
+        run: |
+          export PYTHONPATH=$PYTHONPATH:.
+          pytest --cov=. --cov-report=term-missing --cov-fail-under=80 tests/

GEMINI.md → CLAUDE.md

@@ -11,14 +11,14 @@ This document serves as the foundational mandate for all development work perfor
 
 ## 2. Python Standards
 
-*   **Type Safety**: Use Python 3.10+ type hints for all function signatures and complex variables.
-*   **Style**: Adhere strictly to PEP 8. Use `ruff` or `black` for formatting.
+*   **Type Safety**: Use Python 3.9+ type hints for all function signatures and complex variables. Use `from __future__ import annotations` where needed for forward references.
+*   **Style**: Adhere strictly to PEP 8. Use `ruff` for linting and formatting (replaces black/flake8/isort).
 *   **Documentation**: Every function must have a docstring (Google or NumPy style) explaining its purpose, parameters, and return values.
 *   **Environment**: Always use the virtual environment (`venv/`) and keep `requirements.txt` updated.
 
 ## 3. Data & Privacy (Mandatory)
 
-*   **Anonymity**: Never hardcode personal data (locations, usernames, credentials) into the codebase. 
+*   **Anonymity**: Never hardcode personal data (locations, usernames, credentials) into the codebase.
 *   **Externalize Assumptions**: Any personal identifying data or location assumptions must reside in external JSON files (e.g., `default_assumptions.json.example`) or environment variables.
 *   **Credential Protection**: Use the `AUTOBIO_` environment variable prefix for all configuration. Never log or print API keys or secrets.
 
@@ -27,7 +27,7 @@ This document serves as the foundational mandate for all development work perfor
 *   **Framework**: Use `pytest` for all tests.
 *   **Granularity**: Prefer unit tests for utility logic (`analysis_utils.py`) and integration tests for UI/CLI flows (`visualize.py`, `record_flythrough.py`).
 *   **Mocks**: Properly mock external dependencies (Last.fm API, Streamlit UI components) to ensure tests are fast, deterministic, and can run in CI.
-*   **Validation Step**: AI agents MUST run the full test suite (`.\venv\Scripts\python -m pytest tests/`) before proposing any change.
+*   **Validation Step**: AI agents MUST run the full test suite and all static analysis tools before proposing any change (see Section 7).
 
 ## 5. Caching & Efficiency
 
@@ -39,5 +39,34 @@ This document serves as the foundational mandate for all development work perfor
 1.  **Research**: Map dependencies and identify the minimal path to implementation.
 2.  **Strategy**: Formulate a plan that prioritizes the least disruptive, most maintainable change.
 3.  **Act**: Apply surgical edits. Use `replace` for targeted updates to large files.
-4.  **Validate**: Run tests, check linting, and verify manual use cases.
+4.  **Validate**: Run the full local gate (Section 7) before committing or pushing.
 
+## 7. Local Quality Gate (Required Before Every Commit or Push)
+
+All of the following must pass with zero errors before any commit or push to GitHub. AI agents must run these in order and fix all failures before proceeding.
+
+```bash
+# 1. Lint and format check
+ruff check .
+ruff format --check .
+
+# 2. Type checking
+mypy .
+
+# 3. Security scan
+bandit -r . -x venv,tests
+
+# 4. Tests with coverage
+pytest --cov=. --cov-report=term-missing --cov-fail-under=80 tests/
+```
+
+To auto-fix ruff lint and format issues before checking:
+```bash
+ruff check --fix .
+ruff format .
+```
+
+Install all tools into the venv if not present:
+```bash
+pip install ruff mypy bandit
+```