chore(ci): enforce unused imports/vars + advisory dead-code scan (#2144)

* chore(ci): enforce unused imports/vars + advisory dead-code scan

Enable ruff F401 (unused imports) and F841 (unused variables) -- previously
ignored as "too noisy" -- across hindsight-api-slim, hindsight-dev, and
hindsight-embed, and clean up the resulting violations. These are now blocking:
lint.sh auto-removes them and the verify-generated-files CI job fails on any
leftover diff.

Add an advisory dead-code scan for what the linter cannot see -- whole unused
Python functions (vulture) and orphaned files/exports/dependencies in the
control plane (knip):
- scripts/hooks/check-unused.sh runs both locally
- new non-blocking check-unused-code CI job surfaces findings on PRs
- hindsight-control-plane/knip.json tunes out toolchain false positives

vulture stays advisory because its function/argument heuristics false-positive
on FastAPI/SQLAlchemy/Pydantic patterns; knip can be flipped to blocking once
the control-plane dead code (PR #2135) lands.

* chore(ci): make knip blocking on unused files/deps; remove dead deps

#2135 deleted tooltip.tsx but left @radix-ui/react-tooltip in package.json, and
react-chrono / three were never imported. Remove all three, and declare
@radix-ui/react-visually-hidden (used in directive-detail-modal but unlisted).

With the control-plane tree now clean, the check-unused-code job runs
`knip --include files,dependencies,unlisted` as a BLOCKING step. vulture and
knip's unused-exports check (the shadcn/ui surface is kept intentionally) stay
advisory.

Author: nicoloboschi

.github/workflows/test.yml

@@ -4311,6 +4311,60 @@ jobs:
           fi
         done
 
+  # Dead-code detection beyond what ruff's F401/F841 catch (those are already
+  # BLOCKING via the ruff config + the verify-generated-files job).
+  #
+  # - knip (control plane): BLOCKING on unused files / dependencies / unlisted
+  #   dependencies. These are unambiguous — an orphaned file or a dead
+  #   package.json entry — so they fail the build.
+  # - vulture (Python) + knip unused *exports*: ADVISORY only. vulture's
+  #   function/argument heuristics false-positive on FastAPI/SQLAlchemy/Pydantic
+  #   patterns, and the control plane intentionally keeps an unused shadcn/ui
+  #   component surface, so these are surfaced in the step summary, not gated.
+  check-unused-code:
+    needs: [detect-changes]
+    if: >-
+      (github.event_name == 'workflow_dispatch' ||
+      needs.detect-changes.outputs.core == 'true' ||
+      needs.detect-changes.outputs.control-plane == 'true' ||
+      needs.detect-changes.outputs.ci == 'true')
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+    - uses: actions/checkout@v6
+      with:
+        ref: ${{ github.event.pull_request.head.sha || '' }}
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
+      with:
+        enable-cache: true
+
+    - name: Set up Node.js
+      uses: actions/setup-node@v6
+      with:
+        node-version: '20'
+        cache: 'npm'
+        cache-dependency-path: package-lock.json
+
+    - name: Install Control Plane dependencies
+      run: npm install --workspace=hindsight-control-plane
+
+    - name: knip — unused files / dependencies (blocking)
+      working-directory: hindsight-control-plane
+      run: npx --yes knip@5 --no-progress --include files,dependencies,unlisted
+
+    - name: Advisory scan — vulture + knip exports
+      continue-on-error: true
+      run: |
+        {
+          echo '## Dead-code scan (advisory)'
+          echo ''
+          echo '```'
+          ./scripts/hooks/check-unused.sh 2>&1 | sed 's/\x1b\[[0-9;]*m//g'
+          echo '```'
+        } | tee -a "$GITHUB_STEP_SUMMARY"
+
   verify-generated-files:
     runs-on: ubuntu-latest
     timeout-minutes: 30

CLAUDE.md

@@ -216,6 +216,18 @@ migration file dispatches through `run_for_dialect`, which calls either
 ./scripts/hooks/lint.sh
 ```
 
+Dead-code detection runs in CI (the `check-unused-code` job) at two levels:
+- **Blocking:** unused imports (ruff `F401`) and variables (`F841`) — `lint.sh` auto-removes
+  them and `verify-generated-files` fails on any leftover diff; and **knip** for orphaned
+  control-plane files / unused (or unlisted) `package.json` dependencies.
+- **Advisory:** whole unused Python functions (vulture) and unused control-plane *exports*
+  (the shadcn/ui surface is kept on purpose) — surfaced, not gated.
+
+Run both locally with:
+```bash
+./scripts/hooks/check-unused.sh
+```
+
 **After completing any implementation work, run `/code-review`** to verify your changes against project standards (missing tests, dead code, type safety, etc.). Fix any "must fix" issues before considering the task done.
 
 **MANDATORY: Run `/code-review` before pushing code or creating a pull request.** Do not push or create a PR until all "must fix" issues are resolved.

hindsight-api-slim/pyproject.toml

@@ -204,8 +204,6 @@ select = [
 ignore = [
     "E501",   # line too long (handled by formatter)
     "E402",   # module import not at top of file
-    "F401",   # unused import (too noisy during development)
-    "F841",   # unused variable (too noisy during development)
     "F811",   # redefined while unused
     "F821",   # undefined name (forward references in type hints)
 ]

hindsight-control-plane/knip.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://unpkg.com/knip@5/schema.json",
+  "entry": [
+    "src/app/**/{page,layout,route,loading,error,not-found,template,default,global-error,sitemap,robots,manifest,opengraph-image,icon}.{ts,tsx}",
+    "next.config.{js,mjs,ts}",
+    "tailwind.config.{js,ts}",
+    "postcss.config.{js,mjs}"
+  ],
+  "project": ["src/**/*.{ts,tsx}"],
+  "ignoreDependencies": [
+    "eslint",
+    "eslint-config-next",
+    "@eslint/eslintrc",
+    "autoprefixer",
+    "tailwindcss-animate",
+    "postcss-load-config",
+    "react-is",
+    "@vectorize-io/hindsight-client",
+    "prettier",
+    "tsx"
+  ]
+}

hindsight-control-plane/package.json

@@ -42,7 +42,7 @@
     "@radix-ui/react-slot": "^1.2.4",
     "@radix-ui/react-switch": "^1.2.6",
     "@radix-ui/react-tabs": "^1.1.13",
-    "@radix-ui/react-tooltip": "^1.2.8",
+    "@radix-ui/react-visually-hidden": "^1.2.5",
     "@tailwindcss/postcss": "^4.1.17",
     "@tailwindcss/typography": "^0.5.19",
     "@types/cytoscape": "^3.21.9",
@@ -63,7 +63,6 @@
     "next-themes": "^0.4.6",
     "postcss": "^8.5.6",
     "react": "^19.2.0",
-    "react-chrono": "^2.9.1",
     "react-dom": "^19.2.0",
     "react-is": "^19.2.4",
     "react-markdown": "^10.1.0",
@@ -74,7 +73,6 @@
     "tailwind-merge": "^3.4.0",
     "tailwindcss": "^4.1.17",
     "tailwindcss-animate": "^1.0.7",
-    "three": "^0.182.0",
     "typescript": "^5.9.3"
   },
   "devDependencies": {

hindsight-dev/benchmarks/common/benchmark_runner.py

@@ -22,7 +22,7 @@
 import logging
 import os
 from abc import ABC, abstractmethod
-from datetime import datetime, timezone
+from datetime import datetime
 from pathlib import Path
 from typing import Any, Dict, Iterable, List, Optional, Tuple, Union
 
@@ -34,7 +34,6 @@
 get_config().configure_logging()
 from hindsight_api.engine.memory_engine import Budget
 from hindsight_api.models import RequestContext
-from openai import AsyncOpenAI
 from rich import box
 from rich.console import Console
 from rich.progress import BarColumn, Progress, SpinnerColumn, TextColumn
@@ -596,9 +595,6 @@ async def answer_question(
             # Map thinking_budget to budget level
             budget = Budget.LOW if thinking_budget <= 30 else Budget.MID if thinking_budget <= 70 else Budget.HIGH
 
-            import time
-
-            recall_start_time = time.time()
             # Use default fact types (no filtering)
             search_result = await self.memory.recall_async(
                 bank_id=agent_id,
@@ -611,12 +607,6 @@ async def answer_question(
                 include_chunks=True,
                 request_context=RequestContext(),
             )
-            recall_time = time.time() - recall_start_time
-
-            # Log recall stats
-            num_results = len(search_result.results) if search_result.results else 0
-            num_chunks = len(search_result.chunks) if search_result.chunks else 0
-            num_entities = len(search_result.entities) if search_result.entities else 0
 
             # Convert entire RecallResult to dictionary for answer generation
             recall_result_dict = search_result.model_dump()

hindsight-dev/benchmarks/consolidation/consolidation_benchmark.py

@@ -23,7 +23,6 @@
 from hindsight_api.engine.memory_engine import MemoryEngine
 from hindsight_api.models import RequestContext
 from rich.console import Console
-from rich.progress import BarColumn, Progress, SpinnerColumn, TextColumn
 from rich.table import Table
 
 console = Console()

hindsight-dev/benchmarks/locomo/locomo_benchmark.py

@@ -7,14 +7,12 @@
 import asyncio
 import json
 import os
-import sys
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
 import pydantic
 from hindsight_api.engine.llm_wrapper import LLMConfig
-from openai import AsyncOpenAI
 
 from benchmarks.common.benchmark_runner import (
     BenchmarkDataset,
@@ -414,7 +412,6 @@ async def run_benchmark(
         console.print(f"[green]Found {len(filtered_items)} conversations to re-evaluate[/green]")
 
         # Temporarily replace dataset's load method
-        original_load = dataset.load
 
         def filtered_load(path: Path, max_items: Optional[int] = None):
             return filtered_items[:max_items] if max_items else filtered_items
@@ -501,8 +498,6 @@ def generate_markdown_table(results: dict, use_reflect: bool = False):
 
     console = Console()
 
-    category_names = {"1": "Multi-hop", "2": "Single-hop", "3": "Temporal", "4": "Open-domain"}
-
     # Build markdown content
     lines = []
     mode_str = " (Reflect Mode)" if use_reflect else ""

hindsight-dev/benchmarks/longmemeval/longmemeval_benchmark.py

@@ -7,14 +7,12 @@
 import asyncio
 import json
 import os
-import sys
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
 import pydantic
 from hindsight_api.engine.llm_wrapper import LLMConfig
-from openai import AsyncOpenAI
 
 from benchmarks.common.benchmark_runner import (
     BenchmarkDataset,
@@ -200,7 +198,6 @@ def _format_context_structured(self, recall_result: Dict[str, Any]) -> str:
 
             # Extract temporal information
             occurred_start = fact.get("occurred_start")
-            occurred_end = fact.get("occurred_end")
             mentioned_at = fact.get("mentioned_at")
 
             # Build temporal string
@@ -622,8 +619,6 @@ async def run_benchmark(
             console.print(f"[green]Found {total_found} {filter_type} items to re-evaluate[/green]")
 
     # Create local memory engine
-    from hindsight_api.engine.memory_engine import Budget
-    from hindsight_api.models import RequestContext
 
     from benchmarks.common.benchmark_runner import create_memory_engine
 
@@ -677,7 +672,6 @@ async def run_benchmark(
     # If filtering by category, failed, invalid, only_ingested, or max_instances_per_category, we need to use a custom dataset that only returns those items
     # We'll temporarily replace the dataset's load method
     if filtered_items is not None:
-        original_load = dataset.load
 
         def filtered_load(path: Path, max_items: Optional[int] = None):
             return filtered_items[:max_items] if max_items else filtered_items

hindsight-dev/benchmarks/perf/recall_perf.py

@@ -39,7 +39,6 @@
 
 import argparse
 import asyncio
-import json
 import os
 import statistics
 import time