Merge pull request #1369 from Open-Source-Legal/claude/resolve-issue-1332-1lh9h

Add type annotations to GraphQL resolvers, mutations, and filters

Author: JSv4

CHANGELOG.md

@@ -53,6 +53,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Mypy graduation: typed GraphQL resolvers, mutations, and filters** (Issue #1332): Raised return-annotation coverage in `config/graphql/` from ~4.8% at the start of #1331 to **91.5%** (421/460 function defs) and removed 22 modules from the `mypy.ini` baseline allow-list.
+  - **Root-cause annotation fixes in `opencontractserver/utils/permissioning.py`**: `set_permissions_for_obj_to_user`, `user_has_permission_for_obj`, `get_users_permissions_for_obj`, and `get_permission_id_to_name_map_for_model` were previously annotated with `instance: type[django.db.models.Model]` (a class) despite every call site passing an instance — and with `user: type[User]` instead of the `User` runtime instance. These were annotation bugs (the code was correct, the annotations were inverted), which compounded: every mutation calling `set_permissions_for_obj_to_user(user, obj, ...)` was a single `[arg-type]` error each. Corrected to `instance: django.db.models.Model` / `user: UserModel` (forward-referenced via `TYPE_CHECKING` import of `opencontractserver.users.models.User`). Also added the missing `dict[int, str]` annotation on `this_model_permission_id_map` and removed the `user_instance=User` (class) default on `get_users_group_ids`, which would have exploded at runtime if any caller ever omitted the argument. Module graduated out of the baseline.
+  - **Graduated from `mypy.ini` baseline** (22 modules): `config.graphql.{action_queries, agent_mutations, badge_mutations, base_types, conversation_mutations, conversation_types, corpus_types, document_queries, filters, ingestion_source_mutations, moderation_mutations, og_metadata_queries, pipeline_queries, security, serializers, slug_queries, smart_label_mutations, social_types, user_queries, user_types, voting_mutations}` and `opencontractserver.utils.permissioning`. Each had the underlying mypy errors fixed first (root-cause in `permissioning.py` cleared the `set_permissions_for_obj_to_user` cluster across every mutation file above).
+  - **Per-file type fixes**:
+    - `config/graphql/slug_queries.py` & `config/graphql/user_types.py` & `config/graphql/social_types.py` & `config/graphql/corpus_types.py`: Reversed `.filter(...).visible_to_user(user)` → `.visible_to_user(user).filter(...)` so the custom manager method (typed on the manager) resolves before `.filter()` flattens to the base `QuerySet[Model]` that django-stubs doesn't know carries `visible_to_user`. Semantics are preserved — both orderings AND the conditions. The CLAUDE.md permissioning docs already recommend the manager-first pattern.
+    - `config/graphql/og_metadata_queries.py`: Guarded against `Extract.corpus` being `None` (the FK uses `on_delete=SET_NULL`, so `corpus` is nullable in the DB but the OG metadata resolver was treating it as non-null).
+    - `config/graphql/pipeline_queries.py`: Narrowed the `mimetype` optional before passing to `get_components_by_mimetype_cached` (which required `str`), and typed `components_data` as `dict[str, Sequence[PipelineComponentDefinition]]` so both branches (which return `list[...]` vs `tuple[...]`) type-check against the unified annotation.
+    - `config/graphql/ingestion_source_mutations.py`: Replaced `if error:` with `if pk is None:` in two call sites — the error-then-continue pattern left mypy unable to narrow `pk: str | None` through the conditional. Functionally equivalent (`error is None ⟺ pk is not None` by construction of `_parse_ingestion_source_global_id`).
+    - `config/graphql/conversation_types.py`: Fixed `base64.binascii.Error` → `binascii.Error` with an explicit `import binascii` — `base64` doesn't re-export `binascii` as an attribute, so the reference was broken under `warn_unused_ignores`.
+    - `config/graphql/filters.py`: Coerced `from_global_id(value)[1]` (returns `str`) to `int` before passing to `folder_id` lookup.
+    - `config/graphql/security.py`: Replaced `CsrfViewMiddleware(lambda req: None)` with a typed `_csrf_noop_get_response(request) -> HttpResponse` so the middleware's `get_response` contract is satisfied in-types; switched `wrapped_view.csrf_exempt = True` and `request._dont_enforce_csrf_checks = True` to `setattr(...)` to avoid typing-only attribute errors against Django stubs that don't carry these internal flags. Behaviour identical.
+    - `config/graphql/moderation_mutations.py`: Added an explicit `Union[ChatMessage, Conversation, None]` annotation on `target` where the surrounding `if/else` mixes the two types (mypy can't unify across branches without the hint).
+    - `config/graphql/action_queries.py`: Coerced `from_global_id(...)[1]` to `int` at the three call sites where it feeds `for_corpus` / `for_document` custom queryset methods (which expect `int` PKs).
+  - **Docs & baseline maintenance**: `mypy.ini` baseline section for `config.graphql` trimmed from 35 modules to 14; 63 matching error lines pruned from `docs/typing/mypy_baseline.txt` so the reference file matches the live baseline.
+  - **Known remaining bugs surfaced by mypy** (filed as separate issues per the scope rules of #1332):
+    - #1359 — `RemoveLabelsFromLabelsetMutation` calls non-existent `labelset.documents`. Silent runtime failure (swallowed by a broad `except Exception`). Blocks `config.graphql.label_mutations` graduation; one-line fix + test needed.
+    - #1360 — `DRFMutation.IOSettings` declares `model: django.db.models.Model = None` and `serializer = None`. Non-trivial refactor of the base mutation class; blocks `config.graphql.base` graduation.
 - **Coverage: raise Corpus Chat & Agent Management component tests** (Issue #1276): added 36 new Playwright CT tests across the four lowest-ROI corpus components to drive coverage toward the ≥60% target. Breakdown:
   - `frontend/tests/CorpusChat.ct.tsx` (+13 tests): `initialQuery` auto-send, tool-call timeline entries (ASYNC_THOUGHT), ASYNC_SOURCES merge, SYNC_CONTENT rendering, ASYNC_RESUME, ask_document sub-tool approval remapping, unknown-type default branch, back-to-list navigation, server-message-with-sources rendering, title-filter debounce, and additional navigation-header coverage. Extended the shared `StubSocket` in `beforeEach` with new query-triggered frame sequences.
   - `frontend/tests/CreateCorpusActionModal.ct.tsx` (+8 tests): analyzer-path validation, inline-agent validation (empty name / empty instructions), existing-agent-selection validation, successful inline-agent mutation, backend error toast, analyzer edit-mode pre-population, and legacy trigger-casing normalization fallback.

config/graphql/action_queries.py

@@ -160,7 +160,7 @@ def resolve_corpus_action_executions(self, info, **kwargs) -> Any:
         # Filter by corpus if provided (with access check)
         corpus_id = kwargs.get("corpus_id")
         if corpus_id:
-            corpus_pk = from_global_id(corpus_id)[1]
+            corpus_pk = int(from_global_id(corpus_id)[1])
             # Defense-in-depth: verify user has access to this corpus
             if not Corpus.objects.visible_to_user(user).filter(pk=corpus_pk).exists():
                 return queryset.none()
@@ -169,7 +169,7 @@ def resolve_corpus_action_executions(self, info, **kwargs) -> Any:
         # Filter by document if provided (with access check)
         document_id = kwargs.get("document_id")
         if document_id:
-            document_pk = from_global_id(document_id)[1]
+            document_pk = int(from_global_id(document_id)[1])
             # Defense-in-depth: verify user has access to this document
             if (
                 not Document.objects.visible_to_user(user)
@@ -231,7 +231,7 @@ def resolve_corpus_action_trail_stats(self, info, corpus_id, since=None) -> Any:
         from opencontractserver.corpuses.models import Corpus, CorpusActionExecution
 
         user = info.context.user
-        corpus_pk = from_global_id(corpus_id)[1]
+        corpus_pk = int(from_global_id(corpus_id)[1])
 
         # Defense-in-depth: verify user has access to this corpus
         if not Corpus.objects.visible_to_user(user).filter(pk=corpus_pk).exists():

config/graphql/analysis_mutations.py

@@ -176,7 +176,7 @@ class Arguments:
         id = graphene.String(required=True)
 
     @login_required
-    def mutate(root, info, id) -> "DeleteAnalysisMutation | None":
+    def mutate(root, info, id) -> "DeleteAnalysisMutation":
 
         # ok = False
         # message = "Could not complete"
@@ -206,4 +206,5 @@ def mutate(root, info, id) -> "DeleteAnalysisMutation | None":
 
         # Kick off an async task to delete the analysis (as it can be very large)
         delete_analysis_and_annotations_task.si(analysis_pk=analysis_pk).apply_async()
-        return None
+
+        return DeleteAnalysisMutation(ok=True, message="SUCCESS")

config/graphql/annotation_types.py

@@ -93,14 +93,14 @@ def resolve_content_modalities(self, info) -> Any:
 
     all_source_node_in_relationship = graphene.List(lambda: RelationshipType)
 
-    def resolve_feedback_count(self, info) -> Any:
+    def resolve_feedback_count(self, info) -> int:
         # If feedback_count was annotated on the queryset, use it
         if hasattr(self, "feedback_count"):
             return self.feedback_count
         # Otherwise, count it (but this triggers N+1)
         return self.user_feedback.count()
 
-    def resolve_all_source_node_in_relationship(self, info) -> Any:
+    def resolve_all_source_node_in_relationship(self, info) -> QuerySet[Relationship]:
         return self.source_node_in_relationships.all()
 
     all_target_node_in_relationship = graphene.List(lambda: RelationshipType)
@@ -131,7 +131,7 @@ def resolve_descendants_tree(self, info) -> Any:
         """
         from django_cte import CTE, with_cte
 
-        def get_descendants(cte) -> Any:
+        def get_descendants(cte):
             base_qs = Annotation.objects.filter(parent_id=self.id).values(
                 "id", "parent_id", "raw_text"
             )
@@ -161,7 +161,7 @@ def resolve_full_tree(self, info) -> Any:
         while root.parent_id is not None:
             root = root.parent
 
-        def get_full_tree(cte) -> Any:
+        def get_full_tree(cte):
             base_qs = Annotation.objects.filter(id=root.id).values(
                 "id", "parent_id", "raw_text"
             )
@@ -197,7 +197,7 @@ def resolve_subtree(self, info) -> Any:
         ancestor_ids = [ancestor.id for ancestor in ancestors]
 
         # Get all descendants of the current node
-        def get_descendants(cte) -> Any:
+        def get_descendants(cte):
             base_qs = Annotation.objects.filter(parent_id=self.id).values(
                 "id", "parent_id", "raw_text"
             )
@@ -357,7 +357,7 @@ def resolve_descendants_tree(self, info) -> Any:
         """
         from django_cte import CTE, with_cte
 
-        def get_descendants(cte) -> Any:
+        def get_descendants(cte):
             base_qs = Note.objects.filter(parent_id=self.id).values(
                 "id", "parent_id", "content"
             )
@@ -387,7 +387,7 @@ def resolve_full_tree(self, info) -> Any:
         while root.parent_id is not None:
             root = root.parent
 
-        def get_full_tree(cte) -> Any:
+        def get_full_tree(cte):
             base_qs = Note.objects.filter(id=root.id).values(
                 "id", "parent_id", "content"
             )
@@ -421,7 +421,7 @@ def resolve_subtree(self, info) -> Any:
         ancestor_ids = [ancestor.id for ancestor in ancestors]
 
         # Get all descendants of the current node
-        def get_descendants(cte) -> Any:
+        def get_descendants(cte):
             base_qs = Note.objects.filter(parent_id=self.id).values(
                 "id", "parent_id", "content"
             )

config/graphql/base_types.py

@@ -1,15 +1,24 @@
 """GraphQL type definitions for shared utilities, enums, and simple types."""
 
-from typing import Any
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
 
 import graphene
 from graphene.types.generic import GenericScalar
 from graphql_relay import to_global_id
 
+if TYPE_CHECKING:
+    from config.graphql.annotation_types import AnnotationType
+    from config.graphql.corpus_types import CorpusFolderType
+    from config.graphql.user_types import UserType
+
 
 def build_flat_tree(
-    nodes: list, type_name: str = "AnnotationType", text_key: str = "raw_text"
-) -> list:
+    nodes: list[dict[str, Any]],
+    type_name: str = "AnnotationType",
+    text_key: str = "raw_text",
+) -> list[dict[str, Any]]:
     """
     Builds a flat list of node representations from a list of dictionaries where each
     has at least 'id' and 'parent_id', plus an additional text field (default "raw_text")
@@ -27,7 +36,7 @@ def build_flat_tree(
             - "children": list of child node global IDs.
     """
     # Map node IDs to their immediate children IDs
-    id_to_children: dict[Any, list[Any]] = {}
+    id_to_children: dict[int | str, list[int | str]] = {}
     for node in nodes:
         node_id = node["id"]
         parent_id = node["parent_id"]
@@ -227,19 +236,19 @@ class PageAwareAnnotationType(graphene.ObjectType):
     page_annotations = graphene.List(lambda: _get_annotation_type())
 
 
-def _get_user_type() -> Any:
+def _get_user_type() -> type[UserType]:
     from config.graphql.user_types import UserType
 
     return UserType
 
 
-def _get_corpus_folder_type() -> Any:
+def _get_corpus_folder_type() -> type[CorpusFolderType]:
     from config.graphql.corpus_types import CorpusFolderType
 
     return CorpusFolderType
 
 
-def _get_annotation_type() -> Any:
+def _get_annotation_type() -> type[AnnotationType]:
     from config.graphql.annotation_types import AnnotationType
 
     return AnnotationType

config/graphql/corpus_queries.py

@@ -29,7 +29,7 @@
 logger = logging.getLogger(__name__)
 
 
-def _corpus_count_subqueries() -> Any:
+def _corpus_count_subqueries() -> tuple[Any, Any]:
     """
     Build subqueries for efficient document and annotation counting on Corpus
     querysets. Used by resolve_corpuses and resolve_corpus_by_slugs to annotate

config/graphql/corpus_types.py

@@ -215,7 +215,7 @@ def resolve_documents(self, info, **kwargs) -> Any:
         corpus_doc_ids = self.get_documents(include_caml=True).values_list(
             "id", flat=True
         )
-        return Document.objects.filter(id__in=corpus_doc_ids).visible_to_user(user)
+        return Document.objects.visible_to_user(user).filter(id__in=corpus_doc_ids)
 
     def resolve_annotations(self, info) -> Any:
         """

config/graphql/document_queries.py

@@ -2,13 +2,17 @@
 GraphQL query mixin for document and document-relationship queries.
 """
 
+from __future__ import annotations
+
 import logging
 from typing import Any
 
 import graphene
 from django.conf import settings
+from django.db.models import QuerySet
 from graphene import relay
 from graphene_django.filter import DjangoFilterConnectionField
+from graphql import GraphQLError
 from graphql_jwt.decorators import login_required
 from graphql_relay import from_global_id
 
@@ -46,15 +50,19 @@ class DocumentQueryMixin:
     )
 
     @graphql_ratelimit_dynamic(get_rate=get_user_tier_rate("READ_LIGHT"))
-    def resolve_documents(self, info, **kwargs) -> Any:
+    def resolve_documents(
+        self, info: graphene.ResolveInfo, **kwargs: Any
+    ) -> QuerySet[Document]:
         # Use lightweight mode to skip heavy prefetches (doc_annotations,
         # rows, relationships, notes) that are unnecessary for list/TOC
         # queries requesting only basic document fields.
         return Document.objects.visible_to_user(info.context.user, lightweight=True)
 
     document = graphene.Field(DocumentType, id=graphene.ID())
 
-    def resolve_document(self, info, **kwargs) -> Any:
+    def resolve_document(
+        self, info: graphene.ResolveInfo, **kwargs: Any
+    ) -> Document | None:
         document_id = kwargs.get("id")
         if not document_id:
             return None
@@ -85,7 +93,9 @@ def resolve_document(self, info, **kwargs) -> Any:
     )
 
     @graphql_ratelimit_dynamic(get_rate=get_user_tier_rate("READ_LIGHT"))
-    def resolve_document_relationships(self, info, **kwargs) -> Any:
+    def resolve_document_relationships(
+        self, info: graphene.ResolveInfo, **kwargs: Any
+    ) -> QuerySet[DocumentRelationship]:
         """
         Resolve document relationships with proper permission filtering.
         Uses DocumentRelationshipQueryOptimizer for consistent eager loading.
@@ -124,12 +134,17 @@ def resolve_document_relationships(self, info, **kwargs) -> Any:
     document_relationship = relay.Node.Field(DocumentRelationshipType)
 
     @graphql_ratelimit_dynamic(get_rate=get_user_tier_rate("READ_LIGHT"))
-    def resolve_document_relationship(self, info, **kwargs) -> Any:
+    def resolve_document_relationship(
+        self, info: graphene.ResolveInfo, **kwargs: Any
+    ) -> DocumentRelationship:
         """
         Resolve a single document relationship by ID.
         Uses optimizer for IDOR-safe fetching with proper eager loading.
         """
-        django_pk = from_global_id(kwargs.get("id", None))[1]
+        relay_id = kwargs.get("id")
+        if relay_id is None:
+            raise GraphQLError("DocumentRelationship id is required")
+        django_pk = from_global_id(relay_id)[1]
         result = DocumentRelationshipQueryOptimizer.get_relationship_by_id(
             user=info.context.user,
             relationship_id=int(django_pk),
@@ -147,7 +162,9 @@ def resolve_document_relationship(self, info, **kwargs) -> Any:
     )
 
     @graphql_ratelimit_dynamic(get_rate=get_user_tier_rate("READ_LIGHT"))
-    def resolve_bulk_doc_relationships(self, info, document_id, **kwargs) -> Any:
+    def resolve_bulk_doc_relationships(
+        self, info: graphene.ResolveInfo, document_id: str, **kwargs: Any
+    ) -> QuerySet[DocumentRelationship]:
         """
         Bulk resolver for document relationships involving a specific document.
         Uses DocumentRelationshipQueryOptimizer for proper eager loading.
@@ -183,7 +200,9 @@ def resolve_bulk_doc_relationships(self, info, document_id, **kwargs) -> Any:
     )
 
     @login_required
-    def resolve_bulk_document_upload_status(self, info, job_id) -> Any:
+    def resolve_bulk_document_upload_status(
+        self, info: graphene.ResolveInfo, job_id: str
+    ) -> BulkDocumentUploadStatusType:
         """
         Resolver for the bulk_document_upload_status query.
 
@@ -292,7 +311,12 @@ def resolve_bulk_document_upload_status(self, info, job_id) -> Any:
 
     @login_required
     @graphql_ratelimit_dynamic(get_rate=get_user_tier_rate("READ_LIGHT"))
-    def resolve_ingestion_sources(self, info, active_only=False, **kwargs) -> Any:
+    def resolve_ingestion_sources(
+        self,
+        info: graphene.ResolveInfo,
+        active_only: bool = False,
+        **kwargs: Any,
+    ) -> QuerySet[IngestionSource]:
         qs = IngestionSource.objects.visible_to_user(info.context.user)
         if active_only:
             qs = qs.filter(active=True)
@@ -306,7 +330,9 @@ def resolve_ingestion_sources(self, info, active_only=False, **kwargs) -> Any:
 
     @login_required
     @graphql_ratelimit_dynamic(get_rate=get_user_tier_rate("READ_LIGHT"))
-    def resolve_ingestion_source(self, info, id, **kwargs) -> Any:
+    def resolve_ingestion_source(
+        self, info: graphene.ResolveInfo, id: str, **kwargs: Any
+    ) -> IngestionSource | None:
         try:
             type_name, pk = from_global_id(id)
             if not pk or type_name != INGESTION_SOURCE_GLOBAL_ID_TYPE: