feat: replaced vulture with grimp - better deadcode detection (#242)

* feat: replaced vulture with grimp - better deadcode detection, also bumped up imports
* fix: bug detected

Author: HardMax71

.github/workflows/vulture.yml .github/workflows/grimp.yml.github/workflows/vulture.yml renamed to .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/consumer_group_monitor.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/events/core/producer.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 (