feat: replaced vulture with grimp - better deadcode detection

.github/workflows/vulture.yml → .github/workflows/grimp.yml

@@ -8,8 +8,8 @@ on:
   workflow_dispatch:
 
 jobs:
-  vulture:
-    name: Vulture Dead Code Check
+  grimp:
+    name: Grimp Orphan Module Check
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
@@ -26,7 +26,7 @@ jobs:
           uv python install 3.12
           uv sync --frozen --group lint --no-dev
 
-      - name: Run vulture
+      - name: Run grimp orphan module check
         run: |
           cd backend
-          uv run vulture app/ vulture_whitelist.py
+          uv run python scripts/check_orphan_modules.py

.pre-commit-config.yaml

@@ -22,10 +22,10 @@ repos:
         files: ^backend/.*\.py$
         pass_filenames: false
 
-      # Vulture - matches CI: cd backend && uv run vulture app/ vulture_whitelist.py
-      - id: vulture-backend
-        name: vulture dead code (backend)
-        entry: bash -c 'cd backend && uv run vulture app/ vulture_whitelist.py'
+      # Grimp - matches CI: cd backend && uv run python scripts/check_orphan_modules.py
+      - id: grimp-backend
+        name: grimp orphan modules (backend)
+        entry: bash -c 'cd backend && uv run python scripts/check_orphan_modules.py'
         language: system
         files: ^backend/.*\.py$
         pass_filenames: false

AGENTS.md

@@ -48,7 +48,7 @@ uv run pytest tests/unit/                       # unit only
 uv run pytest -k "test_name" -x                 # single test, stop on failure
 uv run ruff check . --config pyproject.toml     # lint (must pass)
 uv run mypy --config-file pyproject.toml --strict .  # types (must pass)
-uv run vulture app/ vulture_whitelist.py        # dead code (must pass)
+uv run python scripts/check_orphan_modules.py   # dead code (must pass)
 
 # Frontend (from frontend/)
 npm run dev             # dev server with hot reload
@@ -732,14 +732,14 @@ vi.mock('../../../lib/api', () => ({
 # Backend
 uv run ruff check . --config pyproject.toml        # rules: E, F, B, I, W; ignore W293
 uv run mypy --config-file pyproject.toml --strict . # 318 source files
-uv run vulture app/ vulture_whitelist.py            # framework patterns in whitelist
+uv run python scripts/check_orphan_modules.py       # orphan module detection
 
 # Frontend
 npm run check   # svelte-check: 0 errors, 0 warnings
 npm run test    # Vitest tests must pass
 ```
 
-Vulture whitelist (`backend/vulture_whitelist.py`) covers Dishka providers, FastAPI routes, Beanie documents, and Pydantic models that appear unused but are called at runtime.
+Grimp orphan module check (`backend/scripts/check_orphan_modules.py`) detects modules never imported by any other module in the package.
 
 ---
 

backend/app/core/providers.py

@@ -26,7 +26,7 @@
 )
 from app.core.security import SecurityService
 from app.core.tracing import Tracer
-from app.db.repositories import (
+from app.db import (
     AdminEventsRepository,
     AdminSettingsRepository,
     DLQRepository,
@@ -42,7 +42,7 @@
 )
 from app.dlq.manager import DLQManager
 from app.domain.saga import SagaConfig
-from app.events.core import UnifiedProducer
+from app.events import UnifiedProducer
 from app.services.admin import AdminEventsService, AdminSettingsService, AdminUserService
 from app.services.admin.admin_execution_service import AdminExecutionService
 from app.services.auth_service import AuthService

backend/app/db/__init__.py

@@ -1,21 +1,27 @@
 from app.db.repositories import (
+    AdminEventsRepository,
     AdminSettingsRepository,
+    DLQRepository,
     EventRepository,
     ExecutionRepository,
     NotificationRepository,
     ReplayRepository,
+    ResourceAllocationRepository,
     SagaRepository,
     SavedScriptRepository,
     UserRepository,
     UserSettingsRepository,
 )
 
 __all__ = [
+    "AdminEventsRepository",
     "AdminSettingsRepository",
+    "DLQRepository",
     "EventRepository",
     "ExecutionRepository",
     "NotificationRepository",
     "ReplayRepository",
+    "ResourceAllocationRepository",
     "SagaRepository",
     "SavedScriptRepository",
     "UserRepository",

backend/app/db/repositories/__init__.py

@@ -1,5 +1,4 @@
-from app.db.repositories.admin.admin_events_repository import AdminEventsRepository
-from app.db.repositories.admin.admin_settings_repository import AdminSettingsRepository
+from app.db.repositories.admin import AdminEventsRepository, AdminSettingsRepository
 from app.db.repositories.dlq_repository import DLQRepository
 from app.db.repositories.event_repository import EventRepository
 from app.db.repositories.execution_repository import ExecutionRepository

backend/app/dlq/manager.py

@@ -6,7 +6,7 @@
 from faststream.kafka import KafkaBroker
 
 from app.core.metrics import DLQMetrics
-from app.db.repositories import DLQRepository
+from app.db import DLQRepository
 from app.dlq.models import (
     DLQBatchRetryResult,
     DLQMessage,

backend/app/events/core/producer.py

@@ -2,7 +2,7 @@
 from faststream.kafka import KafkaBroker
 
 from app.core.metrics import EventMetrics
-from app.db.repositories import EventRepository
+from app.db import EventRepository
 from app.domain.events import DomainEvent
 
 

backend/app/services/admin/admin_events_service.py

@@ -7,8 +7,8 @@
 
 import structlog
 
+from app.db import AdminEventsRepository
 from app.db.docs.replay import ReplaySessionDocument
-from app.db.repositories import AdminEventsRepository
 from app.domain.admin import ReplaySessionData, ReplaySessionStatusDetail, ReplaySessionUpdate
 from app.domain.enums import ExportFormat, ReplayStatus, ReplayTarget, ReplayType
 from app.domain.events import (

backend/app/services/admin/admin_execution_service.py

@@ -2,7 +2,7 @@
 
 import structlog
 
-from app.db.repositories import ExecutionRepository
+from app.db import ExecutionRepository
 from app.domain.enums import ExecutionStatus, QueuePriority
 from app.domain.execution import DomainExecution, ExecutionNotFoundError
 from app.services.execution_queue import ExecutionQueueService

backend/app/services/admin/admin_settings_service.py

@@ -1,6 +1,6 @@
 import structlog
 
-from app.db.repositories import AdminSettingsRepository
+from app.db import AdminSettingsRepository
 from app.domain.admin import SystemSettings
 from app.services.runtime_settings import RuntimeSettingsLoader
 

backend/app/services/admin/admin_user_service.py

@@ -5,7 +5,7 @@
 
 from app.core.metrics import SecurityMetrics
 from app.core.security import SecurityService
-from app.db.repositories import UserRepository
+from app.db import UserRepository
 from app.domain.admin import AdminUserOverviewDomain, DerivedCountsDomain, RateLimitSummaryDomain
 from app.domain.enums import EventType, ExecutionStatus, UserRole
 from app.domain.exceptions import ConflictError, NotFoundError

backend/app/services/auth_service.py

@@ -6,7 +6,7 @@
 
 from app.core.metrics import SecurityMetrics
 from app.core.security import SecurityService
-from app.db.repositories import UserRepository
+from app.db import UserRepository
 from app.domain.enums import LoginMethod, UserRole
 from app.domain.events import (
     AuthFailedEvent,
@@ -25,7 +25,7 @@
     LoginResult,
     User,
 )
-from app.events.core import UnifiedProducer
+from app.events import UnifiedProducer
 from app.services.login_lockout import LoginLockoutService
 from app.services.runtime_settings import RuntimeSettingsLoader
 from app.settings import Settings

backend/app/services/event_replay/replay_service.py

@@ -12,7 +12,7 @@
 from pydantic import ValidationError
 
 from app.core.metrics import ReplayMetrics
-from app.db.repositories import ReplayRepository
+from app.db import ReplayRepository
 from app.domain.admin import ReplaySessionUpdate
 from app.domain.enums import ReplayStatus, ReplayTarget
 from app.domain.events import DomainEvent, DomainEventAdapter
@@ -26,7 +26,7 @@
     ReplaySessionState,
 )
 from app.domain.sse import DomainReplaySSEPayload
-from app.events.core import UnifiedProducer
+from app.events import UnifiedProducer
 from app.services.sse.redis_bus import SSERedisBus
 
 

backend/app/services/event_service.py

@@ -1,6 +1,6 @@
 from datetime import datetime
 
-from app.db.repositories import EventRepository
+from app.db import EventRepository
 from app.domain.enums import EventType, UserRole
 from app.domain.events import ArchivedEvent, DomainEvent, EventListResult, EventReplayInfo, EventStatistics
 

backend/app/services/execution_service.py

@@ -7,7 +7,7 @@
 from pydantic import TypeAdapter
 
 from app.core.metrics import ExecutionMetrics
-from app.db.repositories import ExecutionRepository
+from app.db import ExecutionRepository
 from app.domain.enums import CancelStatus, EventType, ExecutionStatus, QueuePriority
 from app.domain.events import (
     BaseEvent,
@@ -26,7 +26,7 @@
     ResourceLimitsDomain,
 )
 from app.domain.idempotency import IdempotencyStatus, KeyStrategy
-from app.events.core import UnifiedProducer
+from app.events import UnifiedProducer
 from app.runtime_registry import RUNTIME_REGISTRY
 from app.services.idempotency import IdempotencyManager
 from app.services.runtime_settings import RuntimeSettingsLoader

backend/app/services/k8s_worker/worker.py

@@ -15,7 +15,7 @@
     ExecutionFailedEvent,
     PodCreatedEvent,
 )
-from app.events.core import UnifiedProducer
+from app.events import UnifiedProducer
 from app.runtime_registry import RUNTIME_REGISTRY
 from app.settings import Settings
 

backend/app/services/kafka_event_service.py

@@ -5,7 +5,7 @@
 
 from app.core.metrics import EventMetrics
 from app.domain.events import DomainEvent
-from app.events.core import UnifiedProducer
+from app.events import UnifiedProducer
 from app.settings import Settings
 
 tracer = trace.get_tracer(__name__)

backend/app/services/notification_scheduler.py

@@ -1,6 +1,6 @@
 import structlog
 
-from app.db.repositories import NotificationRepository
+from app.db import NotificationRepository
 from app.services.notification_service import NotificationService
 
 

backend/app/services/notification_service.py

@@ -10,7 +10,7 @@
 from opentelemetry import trace
 
 from app.core.metrics import NotificationMetrics
-from app.db.repositories import NotificationRepository
+from app.db import NotificationRepository
 from app.domain.enums import NotificationChannel, NotificationSeverity, NotificationStatus, UserRole
 from app.domain.events import (
     EventMetadata,