necropsy 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: acc21c7bf0937bb810decd0a6df03911149a32fc08146b15a37e74d133b397eb
+  data.tar.gz: 781f39ee1fb14299dbd9bedb6cad792785269517494b1d6c336fdb52674c10c2
+SHA512:
+  metadata.gz: cef485cc0bb21d6e684107bb08f7882655ddf24600c9f9d53c744b5ce8a4cf78a460540c6bc9d981e652c6679f12641d34950761ceb1f78d17e8708436afc4d8
+  data.tar.gz: 787d658f3eb89506530b4467d3b7071ed9eccab5a9288b4e023e6b9dbcdd97f6a5b5a7127927d060f698deca80510d0ccd81e059a33990bb0531238d85c95ed4

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+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.

data/README.md

@@ -0,0 +1,125 @@
+# Necropsy
+
+Necropsy is a Ruby dead-code detector built around a unified call graph. It
+collects method definitions with Prism, adds call-edge evidence from static and
+optional dynamic analyzers, then runs reachability from framework and configured
+entry points.
+
+The first implementation includes:
+
+- Prism-based method collection for `def`, `define_method`, `attr_*`, and `delegate`
+- static name resolution, CHA, and RTA-style filtering over instantiated classes
+- Rails route/callback/view-helper/component, plain Ruby, and test-suite entry point providers
+- `unreachable`, `unused`, and `test_only_reachable` classifications
+- confidence levels, JSON/YAML/human/SARIF/GitHub reports, baseline/check guardrails, quarantine suggestions, TracePoint recording, and a bench evaluator
+
+## Installation
+
+Add the gem to the development/test group:
+
+```ruby
+gem "necropsy", require: false
+```
+
+## Usage
+
+Create a baseline:
+
+```bash
+bundle exec necropsy baseline --root .
+```
+
+Run a report:
+
+```bash
+bundle exec necropsy analyze --root . --format human
+```
+
+Fail CI only for new high-confidence findings:
+
+```bash
+bundle exec necropsy check --root . --fail-on high
+```
+
+Record dynamic evidence from a Ruby script:
+
+```bash
+bundle exec necropsy record --root . --output tmp/necropsy_trace_point.yml -- script/runner.rb
+bundle exec necropsy coverage --root . --output tmp/necropsy_coverage.yml -- script/runner.rb
+```
+
+Record Ruby Coverage while running an external command:
+
+```bash
+bundle exec necropsy coverage --root . --output tmp/necropsy_coverage.yml -- bundle exec rspec
+```
+
+Child Ruby processes inherit the collector and are merged into the same output
+for that run.
+
+Evaluate against a gold standard:
+
+```bash
+bundle exec necropsy bench --root . --gold-standard gold.yml --ablation
+```
+
+Example configuration:
+
+```yaml
+analyzers:
+  static: [name_resolution, cha, rta]
+  dynamic:
+    coverage:
+      source: tmp/necropsy_coverage.yml
+      min_observation_days: 30
+    coverband:
+      source: redis://prod-redis:6379/2?key=coverband
+    trace_point:
+      source: tmp/necropsy_trace_point.yml
+  custom:
+    - "MyCompany::GraphqlEntryAnalyzer"
+cache:
+  enabled: true
+  path: .necropsy_cache/scan.yml
+entry_points:
+  extra:
+    - "PublicApi::*"
+ci:
+  fail_on: high
+  baseline: .necropsy_baseline.yml
+quarantine:
+  days: 30
+bench:
+  precision_threshold: 0.85
+```
+
+The scan cache is invalidated when scanned Ruby files or configuration values
+change.
+
+Dynamic inputs may provide `executed` or `nodes` entries with method IDs,
+`edges` with `caller_id`/`callee_id`, and an `observation` hash. SARIF and
+GitHub Actions annotations are available via `--format sarif` and
+`--format github`.
+
+Coverband file, Redis string, and Redis hash exports are supported. Rails route
+entry point detection covers common `resources`, `resource`, `namespace`,
+`scope`, `controller`, `concerns`, `draw`, `mount`, `root`, and verb route
+forms.
+
+`necropsy quarantine --write` adds `# necropsy:quarantine since=YYYY-MM-DD`.
+When the configured quarantine window expires and no alive evidence appears,
+the finding is raised to `certain`.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/exe/necropsy

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'necropsy/cli'
+
+exit Necropsy::CLI.run(ARGV)

data/lib/necropsy/analyzer.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Necropsy
+  class Analyzer
+    def analyze(_graph, _project)
+      raise NotImplementedError, "#{self.class} must implement #analyze"
+    end
+
+    def profile
+      raise NotImplementedError, "#{self.class} must implement #profile"
+    end
+
+    private
+
+    def evidence(kind:, details:, analyzer: profile.name, weight: 1.0, metadata: {})
+      Evidence.new(analyzer: analyzer, kind: kind, weight: weight, details: details, metadata: metadata)
+    end
+  end
+end

data/lib/necropsy/analyzers/dynamic/coverage_collector.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require 'coverage'
+require 'fileutils'
+require 'time'
+require 'yaml'
+
+module Necropsy
+  module Analyzers
+    module Dynamic
+      class CoverageCollector
+        def self.record(root:, output:, &)
+          new(root: root, output: output).record(&)
+        end
+
+        def self.install_at_exit(root:, output:, merge: false, run_id: nil)
+          new(root: root, output: output, merge: merge, run_id: run_id).install_at_exit
+        end
+
+        def initialize(root:, output:, merge: false, run_id: nil)
+          @root = File.expand_path(root)
+          @output = output
+          @merge = merge
+          @run_id = run_id
+        end
+
+        def record
+          started_at = Time.now.utc
+          Coverage.start(methods: true)
+          yield
+          write_payload(result: Coverage.result, started_at: started_at, finished_at: Time.now.utc)
+        ensure
+          Coverage.result(stop: true, clear: true) if Coverage.running?
+        end
+
+        def install_at_exit
+          started_at = Time.now.utc
+          started = start_coverage
+
+          at_exit do
+            finished_at = Time.now.utc
+            result = coverage_result(started: started)
+            write_payload(result: result, started_at: started_at, finished_at: finished_at)
+          rescue StandardError => e
+            warn "Necropsy coverage collector failed: #{e.message}"
+          end
+        end
+
+        private
+
+        attr_reader :root, :output, :run_id
+
+        def merge?
+          @merge
+        end
+
+        def start_coverage
+          return false if Coverage.running?
+
+          Coverage.start(methods: true)
+          true
+        end
+
+        def coverage_result(started:)
+          return Coverage.result(stop: true, clear: true) if started && Coverage.running?
+          return Coverage.peek_result if Coverage.respond_to?(:peek_result) && Coverage.running?
+
+          {}
+        end
+
+        def write_payload(result:, started_at:, finished_at:)
+          payload = {
+            'nodes' => executed_nodes(result).sort,
+            'observation' => {
+              'started_at' => started_at.iso8601,
+              'finished_at' => finished_at.iso8601,
+              'days' => [((finished_at - started_at) / 86_400.0).ceil, 1].max,
+              'collector' => 'coverage'
+            }.tap { |observation| observation['run_id'] = run_id if run_id }
+          }
+          FileUtils.mkdir_p(File.dirname(output))
+          merge? ? write_merged_payload(payload) : File.write(output, payload.to_yaml)
+        end
+
+        def write_merged_payload(payload)
+          File.open(output, File::RDWR | File::CREAT, 0o644) do |file|
+            file.flock(File::LOCK_EX)
+            existing = payload_for_current_run(read_payload(file), payload)
+            merged = merge_payload(existing, payload)
+            file.rewind
+            file.truncate(0)
+            file.write(merged.to_yaml)
+            file.flush
+          end
+        end
+
+        def read_payload(file)
+          file.rewind
+          content = file.read
+          return {} if content.empty?
+
+          YAML.load(content) || {}
+        rescue Psych::Exception
+          {}
+        end
+
+        def payload_for_current_run(existing, payload)
+          current_run = payload.dig('observation', 'run_id')
+          return existing unless current_run
+          return existing if empty_payload?(existing)
+          return existing if existing.dig('observation', 'run_id') == current_run
+
+          {}
+        end
+
+        def empty_payload?(payload)
+          Array(payload['nodes']).empty? && payload.fetch('observation', {}).empty?
+        end
+
+        def merge_payload(left, right)
+          observation = merge_observation(left.fetch('observation', {}), right.fetch('observation', {}))
+          {
+            'nodes' => (Array(left['nodes']) + Array(right['nodes'])).uniq.sort,
+            'observation' => observation
+          }
+        end
+
+        def merge_observation(left, right)
+          started_at = [left['started_at'], right['started_at']].compact.min
+          finished_at = [left['finished_at'], right['finished_at']].compact.max
+          observation = left.merge(right)
+          observation['started_at'] = started_at if started_at
+          observation['finished_at'] = finished_at if finished_at
+          observation['days'] = merged_days(left, right, started_at, finished_at)
+          observation['collector'] = 'coverage'
+          observation['processes'] = process_count(left) + process_count(right)
+          observation
+        end
+
+        def merged_days(left, right, started_at, finished_at)
+          observed_days = [left['days'].to_i, right['days'].to_i, days_between(started_at, finished_at)].max
+          [observed_days, 1].max
+        end
+
+        def days_between(started_at, finished_at)
+          return 0 unless started_at && finished_at
+
+          [((Time.parse(finished_at) - Time.parse(started_at)) / 86_400.0).ceil, 1].max
+        rescue ArgumentError
+          0
+        end
+
+        def process_count(observation)
+          return observation['processes'].to_i if observation['processes']
+          return 0 if observation.empty?
+
+          1
+        end
+
+        def executed_nodes(result)
+          result.flat_map do |path, coverage|
+            next [] unless project_path?(path)
+
+            coverage.fetch(:methods, {}).filter_map do |method_key, count|
+              next unless count.to_i.positive?
+
+              node_id_for(method_key)
+            end
+          end
+        end
+
+        def project_path?(path)
+          File.expand_path(path).start_with?("#{root}/")
+        end
+
+        def node_id_for(method_key)
+          owner = method_key[0]
+          method_name = method_key[1]
+          owner_name, separator = owner_and_separator(owner)
+          return nil unless owner_name
+
+          "#{owner_name}#{separator}#{method_name}"
+        end
+
+        def owner_and_separator(owner)
+          return [owner.name, '#'] if owner.respond_to?(:name) && owner.name
+
+          singleton_owner = owner.inspect[/\A#<Class:(.+)>\z/, 1]
+          return [singleton_owner, '.'] if singleton_owner
+
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/necropsy/analyzers/dynamic/coverage_importer.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'yaml'
+
+module Necropsy
+  module Analyzers
+    module Dynamic
+      class CoverageImporter < Analyzer
+        def initialize(config)
+          @config = config || {}
+        end
+
+        def analyze(_graph, project)
+          source = config['source']
+          return AnalyzerResult.empty unless source
+
+          payload = load_payload(File.expand_path(source, project.root))
+          alive = Array(payload['executed'] || payload['nodes']).map do |node_id|
+            AliveEvidence.new(
+              node_id: node_id,
+              evidence: evidence(kind: :alive, details: "Coverage marked #{node_id} as executed",
+                                 metadata: payload['observation'] || {})
+            )
+          end
+
+          edge_evidences = Array(payload['edges']).map do |edge|
+            caller_id = edge['caller_id'] || edge[:caller_id]
+            callee_id = edge['callee_id'] || edge[:callee_id]
+            EdgeEvidence.new(
+              caller_id: caller_id,
+              callee_id: callee_id,
+              evidence: evidence(kind: :call_edge, details: "Coverage observed #{caller_id} -> #{callee_id}")
+            )
+          end
+
+          AnalyzerResult.new(
+            edge_evidences: edge_evidences,
+            alive_evidences: alive,
+            uncertainties: {},
+            observation: { 'coverage' => payload['observation'] || {} }
+          )
+        end
+
+        def profile
+          AnalyzerProfile.new(
+            name: :coverage,
+            kind: :dynamic,
+            soundness: :observational,
+            description: 'Imports method execution and observed edges from Ruby Coverage output.'
+          )
+        end
+
+        private
+
+        attr_reader :config
+
+        def load_payload(path)
+          case File.extname(path)
+          when '.json'
+            JSON.parse(File.read(path))
+          else
+            YAML.load_file(path) || {}
+          end
+        end
+      end
+    end
+  end
+end