Add vulture for dead code detection

[lbedner]

Overview

Add vulture to detect unused code (functions, classes, variables, imports) that should be removed or marked as intentionally unused.

Background

Currently using ruff which only detects unused imports (F401), but not unused functions/classes. We discovered get_recommended_free_providers() was defined but never used anywhere in the codebase.

Implementation

1. Add vulture to dev dependencies

# pyproject.toml
[project.optional-dependencies]
dev = [
    # ... existing deps ...
    "vulture>=2.11",
]

2. Create vulture configuration

# pyproject.toml
[tool.vulture]
min_confidence = 80  # Only report high-confidence dead code
paths = ["app", "aegis"]
exclude = ["tests/", ".venv/", "build/"]

3. Add to Makefile

.PHONY: check-dead-code
check-dead-code:
	@echo "🔍 Checking for dead code..."
	uv run vulture app/ aegis/ --min-confidence 80

.PHONY: check
check: lint typecheck test check-dead-code

4. (Optional) Add to pre-commit

# .pre-commit-config.yaml
- repo: local
  hooks:
    - id: vulture
      name: vulture
      entry: vulture
      language: system
      types: [python]
      args: [--min-confidence=80]

Benefits

• Automatically detect unused code
• Keep codebase clean
• Avoid accumulating technical debt
• Catch refactoring artifacts

Notes

• Use min_confidence = 80 to avoid false positives
• May need whitelist file for intentional unused code (test fixtures, init.py exports, etc.)
• Vulture doesn't understand dynamic imports, so some false positives are expected

References

• https://github.com/jendrikseipp/vulture
• Discovered during AI service refactoring (#issue-number-here)