feat: add project adapter shadow contract

src/docforge/index.py

@@ -8,13 +8,13 @@ import os
 import sqlite3
 import tempfile
 from collections import deque
-from collections.abc import Iterator
+from collections.abc import Generator
 from contextlib import contextmanager
 from pathlib import Path
 
 from .errors import DocForgeError
-from .models import Edge, Node, ProjectSnapshot
-from .project import Project, project_root_fingerprint
+from .models import Edge, Node, ProjectService, ProjectSnapshot
+from .project import project_root_fingerprint
 
 INDEX_SCHEMA_VERSION = 1
 APPLICATION_ID = 1_146_683_778
@@ -43,7 +43,7 @@ def _connect_read_only(path: Path) -> sqlite3.Connection:
 
 
 @contextmanager
-def _read_connection(path: Path) -> Iterator[sqlite3.Connection]:
+def _read_connection(path: Path) -> Generator[sqlite3.Connection, None, None]:
     connection: sqlite3.Connection | None = None
     try:
         connection = _connect_read_only(path)
@@ -76,7 +76,7 @@ def _status(snapshot: ProjectSnapshot) -> dict[str, object]:
 class ProjectIndex:
     """A disposable index that always checks current canonical source before queries."""
 
-    def __init__(self, project: Project) -> None:
+    def __init__(self, project: ProjectService) -> None:
         self.project = project
 
     @property
@@ -265,7 +265,7 @@ class ProjectIndex:
                 """,
                 (expression, bounded),
             ).fetchall()
-        results = []
+        results: list[dict[str, object]] = []
         for row in rows:
             payload = _row_to_node(row).as_dict(include_content=False)
             payload.update({"rank": row["rank"], "snippet": row["snippet"]})
@@ -330,7 +330,7 @@ class ProjectIndex:
         checked = self.check()
         self._require_node(node_id)
         maximum = self.project.descriptor.limits.max_traversal_depth
-        if not isinstance(depth, int) or isinstance(depth, bool) or depth < 0 or depth > maximum:
+        if type(depth) is not int or depth < 0 or depth > maximum:
             raise DocForgeError("invalid_depth", "Traversal depth is outside the configured limit")
         with _read_connection(self.path) as connection:
             edges = tuple(
@@ -340,7 +340,7 @@ class ProjectIndex:
                     "ORDER BY source_id, relation, target_id"
                 )
             )
-        queue = deque([(node_id, 0, (node_id,))])
+        queue: deque[tuple[str, int, tuple[str, ...]]] = deque([(node_id, 0, (node_id,))])
         seen = {node_id}
         results: list[dict[str, object]] = []
         while queue:
@@ -417,7 +417,7 @@ def _row_to_node(row: sqlite3.Row) -> Node:
 def _bounded_limit(value: int | None, maximum: int, *, default: int) -> int:
     if value is None:
         return min(default, maximum)
-    if not isinstance(value, int) or isinstance(value, bool) or value < 1 or value > maximum:
+    if type(value) is not int or value < 1 or value > maximum:
         raise DocForgeError("invalid_limit", "Result limit is outside the configured range")
     return value