dead-scanner 0.1.0__py3-none-any.whl

.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+reports/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZEUS ARES Engine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,85 @@
+# 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.

dead_scanner/__init__.py

@@ -0,0 +1,10 @@
+"""dead_scanner — classify Python modules as dead / fake-alive / standalone / island.
+
+    pip install dead-scanner
+    dead-scanner /path/to/your/project
+    python -m dead_scanner /path/to/your/project --json
+
+Originally extracted from ZEUS ARES SilenceScanner (v3.0).
+"""
+
+from .scanner import SilenceScanner, HealthScorer, __version__

dead_scanner/scanner.py

@@ -0,0 +1,563 @@
+"""SilenceScanner — classify Python modules into dead / fake-alive / island / standalone.
+
+Extracted from ZEUS ARES Engine v3.0.
+Zero external dependencies beyond Python stdlib.
+"""
+
+from __future__ import annotations
+
+import ast
+import json
+import logging
+import os
+import sys
+from collections import defaultdict
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+__version__ = "0.1.0"
+
+logger = logging.getLogger("dead_scanner")
+
+
+class SilenceScanner:
+    """Classifies every Python module in a project into categories:
+
+    - truly_dead:  exported symbols with zero references from any entry point
+                   AND not classified as standalone
+    - standalone:  no inbound imports, but recognized as CLI entry / script /
+                   migration / build tool / test infra / server entry
+    - structural:  __init__.py or API surface re-export files (keep)
+    - island:      works and is referenced, but has no INTERFACE.md / MODULE.yaml
+                   — no cross-module contract
+    - fake_alive:  imported by something that is itself dead-end
+    """
+
+    EXCLUDE_DIRS = {"tests", "test", "__pycache__", ".git", "venv", ".venv",
+                    "node_modules", ".claude", "reports", "data", "certs",
+                    "logs", "backups", "k8s", "helm", "hades", "__pypackages__",
+                    ".tox", ".eggs", "build", "dist", "*.egg-info"}
+
+    STANDALONE_CATEGORIES = {
+        "standalone_script", "cli_entry", "db_migration",
+        "build_tooling", "test_infrastructure", "server_entry",
+    }
+
+    # Default standalone patterns (customizable via constructor)
+    DEFAULT_STANDALONE_PATTERNS: dict[str, list[str]] = {
+        "standalone_script": ["scripts/"],
+        "db_migration": ["alembic"],
+        "test_infrastructure": ["conftest.py"],
+        "build_tooling": ["setup.py", "setup_cython", "build_cython"],
+        "server_entry": ["startup.py", "dashboard/backend/main", "neural_viz_server"],
+        "cli_entry": ["_cli", "_start", "cli.py"],
+    }
+
+    def __init__(self, project_root: str | Path,
+                 standalone_patterns: Optional[dict[str, list[str]]] = None,
+                 exclude_dirs: Optional[set[str]] = None,
+                 output_dir: Optional[str | Path] = None):
+        self._root = Path(project_root).resolve()
+        if not self._root.exists():
+            raise FileNotFoundError(f"Project root not found: {self._root}")
+
+        self._all_modules: dict[str, Path] = {}
+        self._import_graph: dict[str, set[str]] = defaultdict(set)
+        self._reverse_imports: dict[str, set[str]] = defaultdict(set)
+
+        self._standalone_patterns = standalone_patterns or self.DEFAULT_STANDALONE_PATTERNS
+        self._exclude_dirs = exclude_dirs or self.EXCLUDE_DIRS
+        self._output_dir = Path(output_dir) if output_dir else self._root / "reports"
+
+    # -- public API --
+
+    def scan(self, output_json: bool = True) -> dict:
+        """Run full silence scan and return structured result.
+
+        Args:
+            output_json: If True, write result to {output_dir}/silence_map.json
+
+        Returns:
+            dict with keys: scanned_at, project_root, total_modules,
+            truly_dead_count, standalone_count, structural_init_count,
+            island_count, dead, island, fake_alive_hints, standalone_breakdown
+        """
+        self._discover_modules()
+        self._build_import_graph()
+
+        dead = self._find_dead_modules()
+
+        structural = [d for d in dead if d["suggestion"] in ("keep_structural", "keep_api_surface")]
+        standalone = [d for d in dead if d["suggestion"] in self.STANDALONE_CATEGORIES]
+        truly_dead = [d for d in dead
+                      if d["suggestion"] not in ("keep_structural", "keep_api_surface")
+                      and d["suggestion"] not in self.STANDALONE_CATEGORIES]
+
+        standalone_counts: dict[str, int] = {}
+        for d in standalone:
+            cat = d["suggestion"]
+            standalone_counts[cat] = standalone_counts.get(cat, 0) + 1
+
+        result = {
+            "scanned_at": datetime.now().isoformat(),
+            "project_root": str(self._root),
+            "scanner_version": __version__,
+            "total_modules": len(self._all_modules),
+            "truly_dead_count": len(truly_dead),
+            "standalone_count": len(standalone),
+            "standalone_breakdown": standalone_counts,
+            "structural_init_count": len(structural),
+            "island_count": len(self._find_island_modules()),
+            "dead": dead,
+            "standalone": [d["module"] for d in standalone],
+            "truly_dead": [d["module"] for d in truly_dead],
+            "island": self._find_island_modules(),
+            "fake_alive_hints": self._find_fake_alive_hints(),
+        }
+
+        if output_json:
+            self._output_dir.mkdir(parents=True, exist_ok=True)
+            out = self._output_dir / "silence_map.json"
+            out.write_text(json.dumps(result, indent=2, default=str), encoding="utf-8")
+            logger.info(
+                f"SilenceScanner: {len(truly_dead)} truly dead, "
+                f"{len(standalone)} standalone ({standalone_counts}), "
+                f"{len(structural)} structural __init__, "
+                f"{len(self._find_island_modules())} island → {out}"
+            )
+
+        return result
+
+    def scan_module(self, module_path: str | Path) -> dict:
+        """Scan a single module for dead symbols.
+
+        Returns:
+            dict with module, defined_symbols, unreferenced_symbols, unreferenced, status
+        """
+        path = Path(module_path)
+        if not path.exists():
+            return {"error": f"Module not found: {module_path}"}
+        if path.suffix != ".py":
+            return {"error": "Only .py files supported"}
+
+        tree = _parse(path)
+        if tree is None:
+            return {"error": f"Could not parse: {path}"}
+
+        defined = _collect_definitions(tree)
+        mod_name = _module_name_from_path(self._root, path)
+        referenced = {importer for importer, imports in self._import_graph.items()
+                      if mod_name in imports}
+
+        unused = [d for d in defined
+                  if d["name"] not in referenced and not d["name"].startswith("_")]
+
+        return {
+            "module": str(path.relative_to(self._root)),
+            "defined_symbols": len(defined),
+            "unreferenced_symbols": len(unused),
+            "unreferenced": [u["name"] for u in unused],
+            "status": "dead" if len(unused) == len(defined) else "partial",
+        }
+
+    @classmethod
+    def quick_check(cls, project_root: str | Path) -> str:
+        """One-liner: return a human-readable summary string.
+
+        >>> SilenceScanner.quick_check("/path/to/project")
+        '12 dead, 45 standalone, 3 island, 0 fake_alive (534 total modules)'
+        """
+        scanner = cls(project_root, output_dir=None)
+        result = scanner.scan(output_json=False)
+        return (
+            f"{result['truly_dead_count']} dead, "
+            f"{result['standalone_count']} standalone, "
+            f"{result['island_count']} island, "
+            f"{len(result['fake_alive_hints'])} fake_alive "
+            f"({result['total_modules']} total modules)"
+        )
+
+    # -- internal --
+
+    def _discover_modules(self):
+        self._all_modules.clear()
+        for dirpath, dirnames, filenames in os.walk(self._root):
+            dirnames[:] = [d for d in dirnames
+                           if d not in self._exclude_dirs and not d.startswith(".")]
+            for fn in filenames:
+                if fn.endswith(".py"):
+                    full = Path(dirpath) / fn
+                    name = _module_name_from_path(self._root, full)
+                    self._all_modules[name] = full
+
+    def _build_import_graph(self):
+        self._import_graph.clear()
+        self._reverse_imports.clear()
+        for mod_name, path in self._all_modules.items():
+            imported = _extract_imports(path, self._root)
+            self._import_graph[mod_name] = imported
+            for imp in imported:
+                self._reverse_imports[imp].add(mod_name)
+
+    def _classify_standalone(self, rel_path: str) -> Optional[str]:
+        """Classify a module as a known standalone type, or None.
+
+        Uses configurable standalone_patterns dict.
+        """
+        p = rel_path.replace("\\", "/")
+
+        for category, patterns in self._standalone_patterns.items():
+            for pattern in patterns:
+                if pattern.endswith(".py"):
+                    if p.endswith(pattern) or p.endswith("/" + pattern):
+                        return category
+                else:
+                    if pattern in p:
+                        return category
+
+        return None
+
+    def _find_dead_modules(self) -> list[dict]:
+        dead = []
+        for mod_name, path in self._all_modules.items():
+            importers = self._reverse_imports.get(mod_name, set())
+            if not importers:
+                rel = str(path.relative_to(self._root)).replace("\\", "/")
+
+                standalone = self._classify_standalone(rel)
+                if standalone:
+                    dead.append({
+                        "module": rel,
+                        "symbols_defined": 0,
+                        "def_class_count": 0,
+                        "reexport_count": 0,
+                        "suggestion": standalone,
+                    })
+                    continue
+
+                tree = _parse(path)
+                symbols = _collect_definitions(tree) if tree else []
+                public = [s for s in symbols if not s["name"].startswith("_")]
+                is_init = path.name == "__init__.py"
+                defs = [s for s in public if s["type"] in ("function", "class")]
+                reexports = [s for s in public if s["type"] in ("reexport", "import")]
+
+                if is_init and not defs:
+                    suggestion = "keep_structural" if not reexports else "keep_api_surface"
+                elif not public:
+                    suggestion = "remove"
+                else:
+                    suggestion = "remove_or_wake"
+
+                dead.append({
+                    "module": rel,
+                    "symbols_defined": len(public),
+                    "def_class_count": len(defs),
+                    "reexport_count": len(reexports),
+                    "suggestion": suggestion,
+                })
+        return sorted(dead, key=lambda d: d["module"])
+
+    def _find_island_modules(self) -> list[dict]:
+        islands = []
+        for mod_name, path in self._all_modules.items():
+            importers = self._reverse_imports.get(mod_name, set())
+            if importers:
+                pkg_dir = path.parent
+                has_contract = (pkg_dir / "INTERFACE.md").exists() or \
+                               (pkg_dir / "MODULE.yaml").exists()
+                if not has_contract:
+                    islands.append({
+                        "module": str(path.relative_to(self._root)),
+                        "imported_by": len(importers),
+                        "importers": sorted(importers)[:5],
+                        "suggestion": "add_contract",
+                    })
+        return sorted(islands, key=lambda d: d["module"])
+
+    def _find_fake_alive_hints(self) -> list[dict]:
+        hints = []
+        for mod_name in self._all_modules:
+            importers = self._reverse_imports.get(mod_name, set())
+            if not importers:
+                continue
+            if len(importers) == 1:
+                sole = next(iter(importers))
+                sole_importers = self._reverse_imports.get(sole, set())
+                if not sole_importers:
+                    hints.append({
+                        "module": mod_name,
+                        "sole_importer": sole,
+                        "risk": "sole_importer_is_dead_end",
+                    })
+        return hints
+
+
+class HealthScorer:
+    """0-100 health score per module across four dimensions.
+
+    - references (30 pts): inbound dependency count
+    - contract (20 pts): INTERFACE.md or MODULE.yaml present
+    - test (25 pts): corresponding test file exists
+    - runtime (25 pts): invocation counter (configurable)
+
+    Modules below 60 trigger a warning.
+    """
+
+    CRITICAL_THRESHOLD = 60
+    WARNING_THRESHOLD = 80
+
+    def __init__(self, project_root: str | Path,
+                 graph=None,
+                 runtime_counters: Optional[dict[str, int]] = None):
+        self._root = Path(project_root)
+        self._graph = graph
+        self._runtime_counters = runtime_counters or {}
+        self._report_dir = self._root / "reports"
+
+    def score_module(self, name: str, in_degree: int = 0,
+                     contract_exists: bool = False, test_exists: bool = False,
+                     runtime_calls: int = 0) -> dict:
+        ref_score = min(30, in_degree * 3)
+        contract_score = 20 if contract_exists else 0
+        test_score = 25 if test_exists else 0
+        runtime_score = min(25, runtime_calls // 10) if runtime_calls else 0
+        total = ref_score + contract_score + test_score + runtime_score
+
+        if total < self.CRITICAL_THRESHOLD:
+            tier = "critical"
+        elif total < self.WARNING_THRESHOLD:
+            tier = "warning"
+        else:
+            tier = "healthy"
+
+        return {
+            "module": name, "score": total, "tier": tier,
+            "breakdown": {"references": ref_score, "contract": contract_score,
+                          "test": test_score, "runtime": runtime_score},
+            "details": {"in_degree": in_degree, "has_contract": contract_exists,
+                        "has_test": test_exists, "runtime_calls": runtime_calls},
+        }
+
+    def score_all(self, graph=None,
+                  contract_modules: Optional[set[str]] = None,
+                  test_files: Optional[set[str]] = None) -> list[dict]:
+        g = graph or self._graph
+        if g is None:
+            return []
+
+        contracts = contract_modules or set()
+        tests = test_files or set()
+
+        results = []
+        for name, node in g.nodes.items():
+            pkg = name.replace(".", "/").split("/")[0]
+            contract_ok = name in contracts or pkg in contracts
+            test_ok = name in tests or any(
+                t.startswith(name.replace(".", "_")) for t in tests)
+            runtime = self._runtime_counters.get(name, 0)
+
+            results.append(self.score_module(
+                name=name, in_degree=node.in_degree,
+                contract_exists=contract_ok, test_exists=test_ok,
+                runtime_calls=runtime,
+            ))
+        return sorted(results, key=lambda r: r["score"])
+
+    def generate_report(self, graph=None,
+                        contract_modules: Optional[set[str]] = None,
+                        test_files: Optional[set[str]] = None) -> dict:
+        scored = self.score_all(graph, contract_modules, test_files)
+        previous = self._load_previous_report()
+
+        prev_scores = {r["module"]: r["score"] for r in previous.get("modules", [])}
+        trends = []
+        for entry in scored:
+            prev = prev_scores.get(entry["module"])
+            trends.append({
+                "module": entry["module"],
+                "delta": entry["score"] - prev if prev is not None else None,
+                "previous": prev, "current": entry["score"],
+            })
+
+        improved = [t for t in trends if t["delta"] is not None and t["delta"] > 0]
+        declined = [t for t in trends if t["delta"] is not None and t["delta"] < 0]
+        critical = [s for s in scored if s["tier"] == "critical"]
+        avg_score = (sum(s["score"] for s in scored) / len(scored)) if scored else 0
+
+        report = {
+            "generated_at": datetime.now().isoformat(),
+            "total_modules": len(scored), "average_score": round(avg_score, 1),
+            "distribution": {
+                "healthy": len([s for s in scored if s["tier"] == "healthy"]),
+                "warning": len([s for s in scored if s["tier"] == "warning"]),
+                "critical": len(critical),
+            },
+            "modules": scored,
+            "trends": {
+                "improved": len(improved), "declined": len(declined),
+                "stable": len(trends) - len(improved) - len(declined),
+                "details": trends,
+            },
+        }
+
+        self._report_dir.mkdir(parents=True, exist_ok=True)
+        out = self._report_dir / "health-report.json"
+        out.write_text(json.dumps(report, indent=2, default=str), encoding="utf-8")
+        logger.info(f"HealthScorer: avg={avg_score:.1f}, critical={len(critical)} → {out}")
+
+        return report
+
+    def _load_previous_report(self) -> dict:
+        prev = self._report_dir / "health-report.json"
+        if not prev.exists():
+            return {}
+        try:
+            return json.loads(prev.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            return {}
+
+
+# -- AST helpers (private, exposed for testing) --
+
+def _parse(path: Path) -> Optional[ast.Module]:
+    try:
+        return ast.parse(path.read_text(encoding="utf-8"))
+    except (SyntaxError, UnicodeDecodeError, OSError):
+        return None
+
+
+def _extract_imports(path: Path, root: Optional[Path] = None) -> set[str]:
+    tree = _parse(path)
+    if tree is None:
+        return set()
+    imports: set[str] = set()
+
+    own_prefix = ""
+    if root is not None:
+        own_prefix = _module_name_from_path(root, path)
+        if path.name != "__init__.py":
+            own_prefix = ".".join(own_prefix.split(".")[:-1])
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                imports.add(alias.name)
+                parts = alias.name.split(".")
+                for i in range(1, len(parts)):
+                    imports.add(".".join(parts[:i]))
+
+        elif isinstance(node, ast.ImportFrom):
+            if node.module is None:
+                continue
+            if node.level is not None and node.level > 0:
+                parts = own_prefix.split(".") if own_prefix else []
+                if len(parts) >= node.level:
+                    base = ".".join(parts[:-(node.level - 1)] if node.level > 1 else parts)
+                else:
+                    base = ""
+                if base:
+                    imports.add(f"{base}.{node.module}")
+                else:
+                    imports.add(node.module)
+            else:
+                imports.add(node.module)
+
+    return imports
+
+
+def _collect_definitions(tree: ast.Module) -> list[dict]:
+    defs = []
+    for node in ast.iter_child_nodes(tree):
+        if isinstance(node, ast.FunctionDef):
+            defs.append({"name": node.name, "type": "function", "lineno": node.lineno})
+        elif isinstance(node, ast.ClassDef):
+            defs.append({"name": node.name, "type": "class", "lineno": node.lineno})
+        elif isinstance(node, ast.Assign):
+            for target in node.targets:
+                if isinstance(target, ast.Name):
+                    defs.append({"name": target.id, "type": "variable", "lineno": node.lineno})
+        elif isinstance(node, ast.ImportFrom):
+            for alias in node.names:
+                name = alias.asname or alias.name
+                if not name.startswith("_"):
+                    defs.append({"name": name, "type": "reexport", "lineno": node.lineno})
+        elif isinstance(node, ast.Import):
+            for alias in node.names:
+                name = alias.asname or alias.name
+                if not name.startswith("_"):
+                    defs.append({"name": name, "type": "import", "lineno": node.lineno})
+    return defs
+
+
+def _module_name_from_path(root: Path, path: Path) -> str:
+    try:
+        rel = path.relative_to(root)
+    except ValueError:
+        return path.stem
+    parts = list(rel.parts)
+    parts[-1] = parts[-1].replace(".py", "")
+    if parts[-1] == "__init__":
+        parts.pop()
+        if not parts:
+            return "__init__"
+    return ".".join(parts) if len(parts) > 1 else parts[0]
+
+
+# -- CLI entry point --
+
+def main():
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="dead_scanner — classify Python dead/fake-alive/standalone/island modules"
+    )
+    parser.add_argument("project", nargs="?", default=".", help="Project root directory")
+    parser.add_argument("--json", action="store_true", help="Output JSON to stdout")
+    parser.add_argument("--module", "-m", help="Scan a single module")
+    parser.add_argument("--exclude", nargs="*", help="Additional directories to exclude")
+    parser.add_argument("--version", action="store_true", help="Show version")
+    parser.add_argument("--verbose", "-v", action="store_true", help="Verbose output")
+    args = parser.parse_args()
+
+    if args.version:
+        print(f"dead_scanner v{__version__}")
+        return
+
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(levelname)s | %(name)s | %(message)s",
+    )
+
+    exclude = SilenceScanner.EXCLUDE_DIRS.copy()
+    if args.exclude:
+        exclude.update(args.exclude)
+
+    scanner = SilenceScanner(args.project, exclude_dirs=exclude)
+
+    if args.module:
+        result = scanner.scan_module(args.module)
+    else:
+        result = scanner.scan(output_json=not args.json)
+
+    if args.json:
+        print(json.dumps(result, indent=2, default=str, ensure_ascii=False))
+    elif not args.module:
+        print(f"\n  Project: {result['project_root']}")
+        print(f"  Modules: {result['total_modules']}")
+        print(f"  Truly Dead: {result['truly_dead_count']}")
+        print(f"  Standalone: {result['standalone_count']}  {result.get('standalone_breakdown', {})}")
+        print(f"  Structural __init__: {result['structural_init_count']}")
+        print(f"  Island: {result['island_count']}")
+        print(f"  Fake-Alive Hints: {len(result.get('fake_alive_hints', []))}")
+        if result.get('truly_dead'):
+            print(f"\n  Truly Dead Modules:")
+            for m in result['truly_dead']:
+                print(f"    - {m}")
+    else:
+        print(json.dumps(result, indent=2, default=str, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()

dead_scanner-0.1.0.dist-info/METADATA

@@ -0,0 +1,110 @@
+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.

dead_scanner-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+./.gitignore,sha256=pdCt-gTDblr7Fw-Yj_uWXJCNzm3EMO-3PqIMW2W4J3U,66
+./LICENSE,sha256=f-kvs4qU2smq3K9yBODv2C964b4KdA52qYgrL2QVlHw,1073
+./README.md,sha256=mgVBkzGG6Q02Egq_wASlDxQC0pKV8vf5UEvLHtIvaZ8,2557
+./pyproject.toml,sha256=G2uoeKRS-MBjODn2tfYbIaix7TVlwk2T_5dYX9804Gc,1276
+./dead_scanner/__init__.py,sha256=-VXP-Mlmu8THl7-WtgXQVzHWt1RmgeENh2dQlVpUxQg,341
+./dead_scanner/scanner.py,sha256=y3cySWCfGqx90nvq35uQnBjp9dDAB1dxeteeSdLwOrQ,22356
+dead_scanner-0.1.0.dist-info/METADATA,sha256=9l3pg4f359m94nT_tF8kZ04cTrVUKaUN3E4yEgWsiZU,3680
+dead_scanner-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+dead_scanner-0.1.0.dist-info/entry_points.txt,sha256=h7FS0wbpjaICd74BvCXwvKDT4sHebsRxvleGmeJPLLM,59
+dead_scanner-0.1.0.dist-info/licenses/LICENSE,sha256=f-kvs4qU2smq3K9yBODv2C964b4KdA52qYgrL2QVlHw,1073
+dead_scanner-0.1.0.dist-info/RECORD,,

dead_scanner-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

dead_scanner-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dead-scanner = dead_scanner.scanner:main

dead_scanner-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZEUS ARES Engine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dead-scanner"
+version = "0.1.0"
+description = "Classify Python modules as dead, fake-alive, standalone, or island — zero dependencies"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [
+    {name = "ZEUS ARES Engine", email = "nickchen791@gmail.com"},
+]
+keywords = ["dead-code", "python", "static-analysis", "code-quality", "ast"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Testing",
+]
+
+[project.scripts]
+dead-scanner = "dead_scanner.scanner:main"
+
+[project.urls]
+Homepage = "https://github.com/nickchen/dead-scanner"
+Repository = "https://github.com/nickchen/dead-scanner"
+Issues = "https://github.com/nickchen/dead-scanner/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]