dead-scanner 0.1.0

Classify Python modules as dead, fake-alive, standalone, or island — zero dependencies

dead-scanner

Classify Python modules as dead / fake-alive / standalone / island — zero dependencies.

Extracted from ZEUS ARES Engine SilenceScanner (v3.0).

Install

pip install dead-scanner

Quick Start

# Scan a project
dead-scanner /path/to/your/project

# JSON output
dead-scanner /path/to/project --json

# Scan a single module
dead-scanner /path/to/project -m path/to/file.py

# Quick summary (one line)
python -c "from dead_scanner import SilenceScanner; print(SilenceScanner.quick_check('.'))"

Categories

Category	Meaning
truly_dead	Exported symbols with zero references, not standalone
standalone	No imports in, but recognized as CLI/script/migration/build tool
structural	__init__.py or API surface files (keep)
island	Referenced but missing INTERFACE.md / MODULE.yaml contract
fake_alive	Imported by something that is itself a dead end

Python API

from dead_scanner import SilenceScanner, HealthScorer

# Full scan
scanner = SilenceScanner("/path/to/project")
result = scanner.scan()
print(f"{result['truly_dead_count']} dead, {result['standalone_count']} standalone")

# Quick one-liner
print(SilenceScanner.quick_check("/path/to/project"))
# → "12 dead, 45 standalone, 3 island, 0 fake_alive (534 total modules)"

# Single module
mod = scanner.scan_module("path/to/module.py")
print(mod["status"], mod["unreferenced"])

# Custom standalone patterns
scanner = SilenceScanner(".",
    standalone_patterns={
        "standalone_script": ["tools/", "scripts/"],
        "cli_entry": ["cli.py"],
    }
)

# Health scoring
scorer = HealthScorer(".")
scores = scorer.score_module("my_module", in_degree=5, contract_exists=True,
                              test_exists=True, runtime_calls=100)
print(scores["score"], scores["tier"])  # → 75, "warning"

What makes this different from Vulture?

Vulture	dead-scanner
Finds unused functions/classes	Finds unused modules + classifies them
No categorization	5 categories (dead/standalone/structural/island/fake_alive)
No import-graph analysis	Full directed import graph + reverse lookups
No contract checking	Detects missing INTERFACE.md contracts

They complement each other — use Vulture for unused symbols, dead-scanner for unused modules and architecture gaps.

License

MIT — extracted from ZEUS ARES Engine, originally built for the ZEUS Autonomous Trading System.