| name | dead-code-audit |
| version | 0.8.0 |
| description | Deterministic, advisory dead-code audit for Python. Uses vulture (unused functions/classes/methods/properties) and ruff F401/F811/F841 (unused imports, redefinitions, unused locals) to emit DELETE findings to the shared code-health finding schema. Never mutates source.
|
dead-code-audit
Overview
A code-health leaf skill reporting unused/dead code as advisory DELETE findings. It
does not delete anything.
Quick Start
python3 scripts/dead_code_audit.py \
--root /path/to/repo \
--source-prefix src/pkg/ \
--out-dir /tmp/dead-code \
--allowlist .vulture_whitelist.py
Output
dead-code_findings.json — sorted findings (shared schema).dead-code_report.md — summary plus suppression count.- stdout status JSON includes
suppressed_test_referenced.
Exit Codes
0 clean, 1 advisory findings present, 2 tool/config error.
Tools
vulture + ruff (F401/F811/F841 only). See
skills/dead-code-audit/references/rubric.md. --allowlist FILE suppresses
vulture false positives. Vulture function/class/method/property findings whose
symbols appear in tests/test_*.py are suppressed and counted as
suppressed_test_referenced; ruff findings are unaffected. The test-reference
scan is a conservative substring check, so even a test comment can suppress an
advisory DELETE. Findings are deterministic.
Limits
- Advisory only — emits DELETE findings and never deletes or mutates source.
- Python only: backed by
vulture and ruff (F401/F811/F841 only).
- Requires
vulture and ruff installed; a missing tool is a config error
(exit 2), not a finding.
- Static analysis cannot see dynamic usage (reflection,
getattr, string-based
dispatch, plugin entry points), so vulture can report false positives; use
--allowlist to suppress them.
- Test-reference suppression is a conservative substring check, so a mere
mention in a test (even a comment) can hide a genuine DELETE.
- Deterministic and offline; no network access.
