Necropsy
A safety-first dead-code detector for Ruby projects.
Necropsy builds a unified call graph from Ruby definitions, static call-site evidence, framework entry points, and optional runtime observations. It reports code that may be removable while keeping unresolved dispatch, incomplete scans, and external references visible as blockers.
Features
- Prism-based analysis of ordinary, singleton, delegated, aliased, forwarded, reopened, and dynamically defined methods
- Physical-definition identities so duplicate and reopened methods remain independently reviewable
- Static name resolution, CHA, rank-only RTA hints, and conservative Ruby value flow
- Rails routes, callbacks, views, components, migrations, plain Ruby, and test entry points
- Optional positive runtime evidence from TracePoint, Ruby Coverage, and Coverband-compatible artifacts
-
unreachable,blocked, andtest_only_reachableclassifications with confidence, actionability, and analysis-health metadata - Human, JSON, YAML, NDJSON, SARIF, and GitHub Actions output
- Baselines, quarantine annotations, causal diffs, isolated removal plans, and CI guardrails
Installation
Add Necropsy to the development or test group in your Gemfile:
group :development, :test do
gem "necropsy", require: false
endInstall the bundle and verify the CLI:
bundle install
bundle exec necropsy --versionRequirements
- Ruby 3.2 or newer
- Prism 1.x (installed through the gem dependency)
Quick Start
Generate a physical-definition baseline:
bundle exec necropsy baseline --root .Run an interactive report:
bundle exec necropsy analyze --root . --format humanThe default report shows medium-and-higher confidence findings. Include exploratory findings explicitly when needed:
bundle exec necropsy analyze --root . --min-confidence lowCheck for new actionable candidates in CI:
bundle exec necropsy check --root .The check uses .necropsy_baseline.yml by default. A new candidate requires
review and causes a non-zero exit status; incomplete analysis health fails closed
instead of silently approving the result.
Investigate a Finding
Use why to see an evidenced reachability path:
bundle exec necropsy why 'MyService#call' --root .Use why-not when a candidate needs a refutable explanation:
bundle exec necropsy why-not 'LegacyService#unused' --root . --format jsonUse explain to inspect confidence components, blockers, assumptions, and the
recommended next evidence:
bundle exec necropsy explain 'LegacyService#unused' --root .Logical symbols that resolve to multiple physical definitions are reported as
ambiguous. Pass the complete definition_id shown by the diagnostic output to
review one definition at a time.
Safe Removal Workflow
Compare reports or analyze only files changed since a Git revision:
bundle exec necropsy diff --base tmp/base.json --head tmp/head.json
bundle exec necropsy diff --root . --base origin/mainCreate an isolated removal proof and run the project's test command in the temporary checkout:
bundle exec necropsy plan \
--report tmp/head.json \
--candidate 'def:v1:...' \
--output tmp/removal-proof.json
bundle exec necropsy verify \
--root . \
--report tmp/head.json \
--candidate 'def:v1:...' \
-- bundle exec rspecconfidence ranks evidence; it does not prove that removal is safe. The
actionability and analysis-health fields distinguish review candidates from
blocked or incomplete results.
Runtime Evidence
Runtime observations are positive-only: observed execution can keep a method alive, but the absence of an observation is never treated as proof that a method is dead.
Record TracePoint or Coverage evidence while running a script or command:
bundle exec necropsy record \
--root . \
--output tmp/necropsy_trace_point.yml \
-- script/runner.rb
bundle exec necropsy coverage \
--root . \
--output tmp/necropsy_coverage.yml \
-- bundle exec rspecCompare static findings with observed targets or export positive runtime fixtures:
bundle exec necropsy feedback compare \
--report tmp/static.json \
--observed tmp/runtime-targets.json
bundle exec necropsy feedback export-fixtures \
--report tmp/static.json \
--observed tmp/runtime-targets.json \
--output spec/fixtures/runtime_feedbackConfiguration
Create .necropsy.yml in the project root. The default configuration analyzes
an application world and uses known load roots:
analysis:
world: application # application | library
load_roots: known # known | all
paths:
analyze: ["app/**/*.rb", "lib/**/*.rb"]
reference: ["**/*"]
exclude: ["app/legacy/**/*.rb"]
report:
include: ["app/**", "lib/**"]
exclude: ["lib/generated/**"]
ci:
baseline: .necropsy_baseline.yml
fail_on: new_review_candidateImportant scope rules:
-
paths.analyzeselects Ruby definitions eligible for findings. -
paths.referencediscovers callers and references outside the analysis scope; it defaults to the whole repository. -
report.includeandreport.excludefilter output only. They do not remove graph nodes, callers, or entry points. -
analysis.world: libraryprotects non-test public and protected methods as external roots for open-world libraries. -
ci.fail_on: new_review_candidateis the default safety gate. Legacy confidence thresholds remain available for compatibility.
The scan cache is enabled by default and is invalidated when analyzed files, reference files, or configuration values change.
How It Works
- Discover Ruby definitions and repository references with Prism and safe source discovery.
- Build a physical-definition call graph from static analyzers, framework conventions, configured entry points, and positive runtime evidence.
- Resolve calls conservatively. Partial or unknown dispatch produces a scoped blocker instead of speculative deadness.
- Classify reachability, confidence, actionability, and analysis health.
- Report findings in a human or machine-readable format, or compare them with a physical-definition baseline for CI.
Machine-readable reports use schema v2. The published contract is
schema/necropsy-report-v2.schema.json.
The documentation hub indexes migration guides, architecture
decisions, and frozen review records. The 0.4.0 migration guide
describes the actionability-aware CI and removal workflow changes.
Repository Landing Page
The repository includes an Astro-based landing page in site/ that explains
Necropsy's safety-first approach to Ruby dead-code analysis.
Run it locally:
cd site
npm ci
npm run devBuild the static site for production:
npm run buildThe workflow at .github/workflows/deploy-pages.yml deploys the site to
GitHub Pages after pushes to main. On the first deployment, set the
repository's Pages source to GitHub Actions in Settings → Pages.
Development
Set up a checkout and run the complete local quality suite:
bin/setup
bundle exec rakeRun individual checks or build the gem:
bundle exec rspec
bundle exec rubocop
gem build necropsy.gemspecUse bin/console for an interactive Ruby session with Necropsy loaded.
Contributing
Bug reports and pull requests are welcome on GitHub.
License
Released under the MIT License.