Metadata-Version: 2.4
Name: dead-scanner
Version: 0.1.0
Summary: Classify Python modules as dead, fake-alive, standalone, or island — zero dependencies
Project-URL: Homepage, https://github.com/nickchen/dead-scanner
Project-URL: Repository, https://github.com/nickchen/dead-scanner
Project-URL: Issues, https://github.com/nickchen/dead-scanner/issues
Author-email: ZEUS ARES Engine <nickchen791@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ast,code-quality,dead-code,python,static-analysis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# dead-scanner

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

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

## Install

```bash
pip install dead-scanner
```

## Quick Start

```bash
# 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

```python
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.
