feat: Add rules

Author: GoodbyePlanet

.claude/rules/fastmcp-http.md

@@ -0,0 +1,98 @@
+---
+paths:
+  - "server/routes/**/*.py"
+  - "server/tools/**/*.py"
+---
+
+# FastMCP + Starlette HTTP conventions
+
+This project uses **FastMCP**. HTTP routes are registered on the
+`FastMCP` instance via `@mcp.custom_route`. Never add routes to a separate
+FastAPI or Starlette app.
+
+## Route registration pattern
+
+Wrap registration in a `register_*` function that accepts `mcp: FastMCP`. Call it
+from `server/main.py`:
+
+```python
+from mcp.server.fastmcp import FastMCP
+from starlette.requests import Request
+from starlette.responses import StreamingResponse
+
+def register_http_routes(mcp: FastMCP) -> None:
+
+    @mcp.custom_route("/reindex", methods=["POST"])
+    async def reindex(request: Request) -> StreamingResponse:
+        ...
+```
+
+Same pattern for MCP tools — `register_*_tools(mcp: FastMCP)` in `server/tools/`.
+
+## Request body parsing
+
+Never assume a body exists. Check `content-type` first:
+
+```python
+body: dict = {}
+if request.headers.get("content-type", "").startswith("application/json"):
+    raw = await request.body()
+    if raw:
+        body = json.loads(raw)
+```
+
+## Streaming responses (NDJSON)
+
+All indexing endpoints return `StreamingResponse` with
+`media_type="application/x-ndjson"`. Emit one JSON object per line:
+
+- Progress frames: `{"type": "progress", "phase": "...", "current": int, "total": int, "percentage": float, "service": str}`
+- Done frame: `{"type": "done", "result": {...}}`
+- Error frame: `{"type": "error", "message": str}`
+
+Use an `asyncio.Queue` + `asyncio.create_task` to decouple the async pipeline
+from the generator that yields to the client:
+
+```python
+async def generate():
+    queue: asyncio.Queue = asyncio.Queue()
+
+    async def run() -> None:
+        try:
+            result = await pipeline.index_all(progress_callback=lambda e: queue.put_nowait(e))
+            await queue.put({"__done__": True, "result": result})
+        except Exception as exc:
+            await queue.put(exc)
+
+    task = asyncio.create_task(run())
+    try:
+        while True:
+            item = await queue.get()
+            if isinstance(item, Exception):
+                yield json.dumps({"type": "error", "message": str(item)}) + "\n"
+                break
+            if isinstance(item, dict):
+                yield json.dumps({"type": "done", "result": item["result"]}) + "\n"
+                break
+            yield json.dumps({"type": "progress", **dataclasses.asdict(item)}) + "\n"
+    finally:
+        await task
+
+return StreamingResponse(generate(), media_type="application/x-ndjson")
+```
+
+## Logging in routes
+
+Log at entry with `%s` args (not f-strings):
+
+```python
+logger.info("Reindex started: service=%s force=%s", service or "ALL", force)
+```
+
+## MCP tool conventions
+
+- Tool functions registered with `@mcp.tool()` must have descriptive docstrings —
+  these become the tool description visible to AI clients.
+- Access shared state via `server/state.py` getters (`get_store()`, `get_commit_store()`)
+  rather than importing globals directly.
+- Tool implementations live in `server/tools/`; route implementations in `server/routes/`.

.claude/rules/python.md

@@ -0,0 +1,80 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# Python conventions
+
+## Module header
+
+Every module must start with `from __future__ import annotations`. This enables
+PEP 563 deferred evaluation — it allows forward references in type hints without
+quotes and is already the project-wide convention.
+
+## Type hints
+
+- Annotate every function: parameters and return type. No untyped public functions.
+- Python ≥ 3.12 is required — use `X | Y` union syntax, not `Optional[X]` or `Union[X, Y]`.
+- Use built-in generics: `list[str]`, `dict[str, int]`, not `List[str]` / `Dict`.
+- Use `Protocol` for structural (duck) typing instead of abstract base classes:
+
+```python
+from typing import Protocol, runtime_checkable
+
+@runtime_checkable
+class EmbeddingProvider(Protocol):
+    @property
+    def dimensions(self) -> int: ...
+    async def embed_batch(self, texts: list[str]) -> list[list[float]]: ...
+```
+
+## Logging
+
+Never use `print()`. Use `logging.getLogger(__name__)` and pass format args as
+separate arguments (defers string formatting to when the log is actually emitted):
+
+```python
+# Correct
+logger = logging.getLogger(__name__)
+logger.info("Indexing service=%s force=%s", service, force)
+
+# Wrong — eager formatting, print
+print(f"indexing {service}")
+logger.info(f"Indexing service={service}")
+```
+
+## Naming
+
+- Functions and variables: `snake_case`
+- Classes: `PascalCase`
+- Constants: `UPPER_SNAKE_CASE`
+- Private helpers: prefix with `_` (e.g. `_build_bm25_text`)
+
+## String formatting
+
+Use f-strings everywhere except logger calls (see above).
+
+## Dependency management
+
+Use `uv`, not `pip`:
+
+- Install deps: `uv sync` / `uv sync --group dev`
+- Run tools: `uv run pytest`, `uv run <script>`
+- Never call `pip install` or `python -m pytest` directly.
+
+## Comprehensions over accumulate-in-loop
+
+Prefer list comprehensions. Refactor collect-and-append patterns:
+
+```python
+# Wrong
+results = []
+for sym in symbols:
+    if sym.language == "python":
+        results.append(sym.name)
+
+# Correct
+results = [sym.name for sym in symbols if sym.language == "python"]
+```
+
+Use generators for large sequences to avoid materializing the whole list at once.

.claude/rules/testing.md

@@ -0,0 +1,110 @@
+---
+paths:
+  - "tests/**/*.py"
+---
+
+# Testing conventions
+
+## Framework
+
+Use `pytest`. `asyncio_mode = "auto"` is set globally in `pyproject.toml` — write
+`async def test_...()` directly. Never add `@pytest.mark.asyncio`.
+
+## File header
+
+Every test file starts with `from __future__ import annotations`.
+
+## Test naming
+
+Flat functions, not classes. Name tests after the behaviour being verified:
+
+```python
+# Correct — describes what the code does
+def test_empty_file_returns_no_symbols(): ...
+def test_async_function_detected_as_async(): ...
+
+# Wrong — generic or vague
+def test_parser(): ...
+def test_it_works(): ...
+```
+
+## Fixtures
+
+- Use `@pytest.fixture` for reusable setup — they compose cleanly and handle teardown.
+- Default scope is function. Use `scope="session"` only for expensive, read-only
+  resources (e.g. `fixtures_dir` in `conftest.py`).
+- Prefer `conftest.py` for fixtures shared across multiple test files.
+
+## Mocking
+
+Use `unittest.mock` — `AsyncMock`, `MagicMock`, `patch`. Do **not** use `pytest-mock`.
+
+```python
+from unittest.mock import ANY, AsyncMock, MagicMock, patch
+
+@pytest.fixture
+def mock_pipeline():
+    pipeline = AsyncMock()
+    pipeline.index_service.return_value = {"files": 10, "chunks": 50, "skipped": 2}
+    return pipeline
+
+async def test_reindex(client, mock_pipeline):
+    with patch("server.routes.reindex.IndexPipeline", return_value=mock_pipeline):
+        resp = await client.post("/reindex")
+    assert resp.status_code == 200
+```
+
+Use `patch` as a context manager, not a decorator, when patching multiple targets.
+
+## HTTP endpoint tests
+
+Use `httpx.AsyncClient` with `httpx.ASGITransport` — never spin up a real server:
+
+```python
+@pytest.fixture
+async def client(app):
+    async with httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=app),
+        base_url="http://test",
+    ) as c:
+        yield c
+```
+
+Use `respx` for mocking outbound `httpx` calls (external HTTP the server makes).
+
+## Parser tests
+
+Parse fixtures, then assert by building a name-keyed dict. Check `symbol_type`,
+`extras`, and `language` explicitly:
+
+```python
+def test_canonical_api_fixture(read_fixture):
+    src = read_fixture("python/api.py")
+    syms = PythonParser().parse_file(src, "svc/api.py")
+
+    by_name = {s.name: s for s in syms}
+    assert set(by_name) == {"ChatRequest", "chat", "helper"}
+
+    chat = by_name["chat"]
+    assert chat.symbol_type == "api_route"
+    assert chat.extras["http_method"] == "POST"
+```
+
+Add canonical fixture files under `tests/fixtures/<language>/` for each new language
+parser, then snapshot-test via the `read_fixture` fixture from `conftest.py`.
+
+## Parametrize
+
+Use `@pytest.mark.parametrize` for data-driven cases — it avoids duplicating test
+logic and makes failures easy to pinpoint:
+
+```python
+@pytest.mark.parametrize("source,expected_type", [
+    (b"def fn(): pass", "function"),
+    (b"async def fn(): pass", "function"),
+    (b"class Foo: pass", "class"),
+])
+def test_symbol_type(source, expected_type):
+    syms = PythonParser().parse_file(source, "mod.py")
+    assert syms[0].symbol_type == expected_type
+```