necropsy 0.1.0 → 0.2.0

data/lib/necropsy/guardrail/baseline.rb

@@ -9,10 +9,10 @@ module Necropsy
       attr_reader :path, :fingerprints
 
       def self.load(path)
-        return new(path: path, fingerprints: []) unless File.exist?(path)
+        return new(path: path, findings: []) unless File.exist?(path)
 
-        payload = YAML.load_file(path) || {}
-        new(path: path, fingerprints: Array(payload['findings']).map { |finding| finding['fingerprint'] })
+        payload = YAML.safe_load_file(path, aliases: false) || {}
+        new(path: path, findings: Array(payload['findings']))
       end
 
       def self.write(report, path:)
@@ -34,14 +34,23 @@ module Necropsy
         File.write(path, payload.to_yaml)
       end
 
-      def initialize(path:, fingerprints:)
+      def initialize(path:, findings:)
         @path = path
-        @fingerprints = fingerprints
+        @findings = findings
+        @fingerprints = findings.filter_map { |finding| finding['fingerprint'] }.to_set
       end
 
       def include?(finding)
         fingerprints.include?(finding.fingerprint)
       end
+
+      def count_at_least(confidence)
+        threshold = CONFIDENCE_LEVELS.fetch(confidence)
+        @findings.count do |finding|
+          level = finding['confidence']&.to_sym
+          level && CONFIDENCE_LEVELS.fetch(level, -1) >= threshold
+        end
+      end
     end
   end
 end

data/lib/necropsy/guardrail/diff.rb

@@ -6,8 +6,11 @@ module Necropsy
   module Guardrail
     class Diff
       def self.changed_files(root:, diff_base:)
-        stdout, status = Open3.capture2('git', '-C', root, 'diff', '--name-only', "#{diff_base}...HEAD")
-        return Set.new unless status.success?
+        stdout, stderr, status = Open3.capture3('git', '-C', root, 'diff', '--name-only', "#{diff_base}...HEAD")
+        unless status.success?
+          detail = stderr.strip.empty? ? 'unknown git error' : stderr.strip
+          raise Error, "Could not determine changed files from #{diff_base}: #{detail}"
+        end
 
         stdout.lines.map(&:strip).reject(&:empty?).to_set
       end

data/lib/necropsy/guardrail/quarantine.rb

@@ -26,15 +26,21 @@ module Necropsy
       def write(min_confidence: :high)
         grouped = suggestions(min_confidence: min_confidence).group_by { |suggestion| suggestion[:path] }
         grouped.each do |path, entries|
-          lines = File.readlines(path, chomp: true)
+          source = File.binread(path)
+          newline = source[/\r\n|\n/] || "\n"
+          trailing_newline = source.end_with?("\r\n", "\n")
+          lines = source.split(/\r\n|\n/, -1)
+          lines.pop if trailing_newline
           entries.sort_by { |entry| -entry[:line] }.each do |entry|
             index = [entry[:line] - 1, 0].max
-            next if lines[index - 1]&.include?(ANNOTATION_PREFIX)
+            next if index.positive? && lines[index - 1]&.include?(ANNOTATION_PREFIX)
 
             indent = lines[index][/^\s*/] || ''
             lines.insert(index, "#{indent}#{entry[:annotation]}")
           end
-          File.write(path, "#{lines.join("\n")}\n")
+          rewritten = lines.join(newline)
+          rewritten << newline if trailing_newline
+          File.binwrite(path, rewritten)
         end
       end
 

data/lib/necropsy/models.rb

@@ -3,7 +3,14 @@
 require 'digest'
 
 module Necropsy
-  Node = Data.define(:id, :kind, :file, :line, :end_line, :defined_via, :owner, :name, :test) do
+  CONFIDENCE_LEVELS = {
+    low: 0,
+    medium: 1,
+    high: 2,
+    certain: 3
+  }.freeze
+
+  Node = Data.define(:id, :kind, :file, :line, :end_line, :defined_via, :owner, :name, :test, :visibility) do
     def method?
       kind != :block_entry
     end
@@ -22,7 +29,8 @@ module Necropsy
         'defined_via' => defined_via.to_s,
         'owner' => owner,
         'name' => name,
-        'test' => test
+        'test' => test,
+        'visibility' => visibility.to_s
       }
     end
   end
@@ -127,22 +135,21 @@ module Necropsy
   EdgeEvidence = Data.define(:caller_id, :callee_id, :evidence)
   AliveEvidence = Data.define(:node_id, :evidence)
 
+  ScoreComponent = Data.define(:name, :value, :details) do
+    def to_h
+      { 'name' => name, 'value' => value, 'details' => details }
+    end
+  end
+
   AnalyzerResult = Data.define(:edge_evidences, :alive_evidences, :uncertainties, :observation) do
     def self.empty
       new(edge_evidences: [], alive_evidences: [], uncertainties: {}, observation: {})
     end
   end
 
-  Finding = Data.define(:node, :classification, :confidence, :score, :reasons, :evidences) do
-    LEVELS = {
-      low: 0,
-      medium: 1,
-      high: 2,
-      certain: 3
-    }.freeze
-
+  Finding = Data.define(:node, :classification, :confidence, :score, :score_components, :reasons, :evidences) do
     def at_least?(level)
-      LEVELS.fetch(confidence) >= LEVELS.fetch(level)
+      CONFIDENCE_LEVELS.fetch(confidence) >= CONFIDENCE_LEVELS.fetch(level)
     end
 
     def fingerprint
@@ -155,6 +162,7 @@ module Necropsy
         'classification' => classification.to_s,
         'confidence' => confidence.to_s,
         'score' => score,
+        'score_components' => score_components.map(&:to_h),
         'node' => node.to_h,
         'reasons' => reasons,
         'evidences' => evidences.map(&:to_h)

data/lib/necropsy/project.rb

@@ -7,7 +7,6 @@ module Necropsy
     EXCLUDED_DIRECTORIES = %w[
       .bundle
       .git
-      .serena
       coverage
       doc
       node_modules
@@ -36,7 +35,12 @@ module Necropsy
         rake = Dir.glob(File.join(root, '**', '*.rake'))
         executables = Dir.glob(File.join(root, '{bin,exe}', '*')).select { |file| File.file?(file) }
         gemspecs = Dir.glob(File.join(root, '*.gemspec'))
-        (globbed + special + rake + executables + gemspecs).uniq.select { |file| analyzable_file?(file) }.sort
+        candidates = (globbed + special + rake + executables + gemspecs).uniq
+        candidates.select! { |file| analyzable_file?(file) }
+        warn_excluded_entry_points(candidates) if config.include_paths.any?
+        candidates.select! { |file| included_path?(relative_path(file)) } if config.include_paths.any?
+        candidates.reject! { |file| excluded_path?(relative_path(file)) }
+        candidates.sort
       end
     end
 
@@ -57,9 +61,51 @@ module Necropsy
 
     def analyzable_file?(file)
       relative_parts = relative_path(file).split(File::SEPARATOR)
-      !relative_parts.intersect?(EXCLUDED_DIRECTORIES)
+      return false if EXCLUDED_DIRECTORIES.include?(relative_parts.first)
+
+      ruby_source?(file)
     rescue ArgumentError
       false
     end
+
+    def ruby_source?(file)
+      return true if file.end_with?('.rb', '.rake', '.gemspec') || File.basename(file) == 'Rakefile'
+
+      File.open(file, &:readline).match?(/\A#!.*\bruby\b/)
+    rescue EOFError, SystemCallError, EncodingError
+      false
+    end
+
+    def included_path?(relative)
+      config.include_paths.any? { |pattern| path_matches?(pattern, relative) }
+    end
+
+    def excluded_path?(relative)
+      config.exclude_paths.any? { |pattern| path_matches?(pattern, relative) }
+    end
+
+    def path_matches?(pattern, relative)
+      File.fnmatch?(pattern, relative, File::FNM_PATHNAME | File::FNM_EXTGLOB) ||
+        File.fnmatch?(File.join(pattern, '**', '*'), relative, File::FNM_PATHNAME | File::FNM_EXTGLOB)
+    end
+
+    def warn_excluded_entry_points(candidates)
+      excluded = candidates.filter_map do |file|
+        relative = relative_path(file)
+        relative if potential_entry_point_path?(relative) && !included_path?(relative)
+      end
+      return if excluded.empty?
+
+      sample = excluded.sort.first(5)
+      suffix = excluded.length > sample.length ? " and #{excluded.length - sample.length} more" : ''
+      warn "Necropsy paths.include excludes potential entry points: #{sample.join(', ')}#{suffix}. " \
+           'Use report.include to filter findings without narrowing analysis.'
+    end
+
+    def potential_entry_point_path?(relative)
+      relative == 'Rakefile' || relative == 'config/routes.rb' ||
+        relative.start_with?('bin/', 'exe/', 'spec/', 'test/') ||
+        relative.end_with?('.rake', '.gemspec')
+    end
   end
 end

data/lib/necropsy/reachability/engine.rb

@@ -2,7 +2,28 @@
 
 module Necropsy
   module Reachability
-    Result = Data.define(:runtime_alive, :test_alive)
+    Result = Data.define(:runtime_paths, :test_paths) do
+      def runtime_alive
+        runtime_paths.keys
+      end
+
+      def test_alive
+        test_paths.keys
+      end
+
+      def witness(node_id, kind: :runtime)
+        paths = kind == :runtime ? runtime_paths : test_paths
+        return unless paths.key?(node_id)
+
+        chain = []
+        current = node_id
+        while current
+          chain.unshift(current)
+          current = paths[current]
+        end
+        chain
+      end
+    end
 
     class Engine
       def initialize(graph)
@@ -14,8 +35,8 @@ module Necropsy
         test_roots = graph.entry_points.select(&:test?).map(&:node_id)
 
         Result.new(
-          runtime_alive: traverse(runtime_roots),
-          test_alive: traverse(test_roots)
+          runtime_paths: traverse(runtime_roots),
+          test_paths: traverse(test_roots)
         )
       end
 
@@ -24,15 +45,18 @@ module Necropsy
       attr_reader :graph
 
       def traverse(roots)
-        visited = Set.new
+        visited = {}
         queue = roots.compact.uniq
+        queue.each { |node_id| visited[node_id] = nil }
 
         until queue.empty?
           node_id = queue.shift
-          next if visited.include?(node_id)
+          graph.edges_from(node_id).each_key do |callee_id|
+            next if visited.key?(callee_id)
 
-          visited << node_id
-          graph.edges_from(node_id).each_key { |callee_id| queue << callee_id unless visited.include?(callee_id) }
+            visited[callee_id] = node_id
+            queue << callee_id
+          end
         end
 
         visited

data/lib/necropsy/report.rb

@@ -5,46 +5,76 @@ require 'yaml'
 
 module Necropsy
   class Report
-    attr_reader :root, :graph, :findings
+    attr_reader :root, :graph, :findings, :reachability
 
-    def initialize(root:, graph:, findings:)
+    def initialize(root:, graph:, findings:, reachability: nil, report_include_paths: [], report_exclude_paths: [])
       @root = root
       @graph = graph
-      @findings = findings
+      @findings = findings.sort_by { |finding| [finding.node.file, finding.node.line, finding.node.id] }
+      @reachability = reachability
+      @report_include_paths = report_include_paths
+      @report_exclude_paths = report_exclude_paths
     end
 
     def dead_methods(min_confidence: :low)
-      findings.select { |finding| finding.at_least?(min_confidence) }
+      reported_findings.select { |finding| finding.at_least?(min_confidence) }
     end
 
-    def to_h
-      {
+    def to_h(include_graph: false)
+      payload = {
         'root' => root,
         'summary' => summary,
-        'findings' => findings.map(&:to_h),
-        'graph' => graph.to_h
+        'findings' => reported_findings.map(&:to_h)
       }
+      payload['graph'] = graph.to_h if include_graph
+      payload
     end
 
-    def to_json(*)
-      JSON.pretty_generate(to_h, *)
+    def to_json(state = nil, include_graph: false)
+      payload = to_h(include_graph: include_graph)
+      return JSON.pretty_generate(payload) unless state
+
+      payload.to_json(state)
     end
 
-    def to_yaml
-      to_h.to_yaml
+    def to_yaml(include_graph: false)
+      to_h(include_graph: include_graph).to_yaml
     end
 
     def summary
-      grouped = findings.group_by(&:classification)
+      grouped = reported_findings.group_by(&:classification)
       {
         'nodes' => graph.nodes.length,
         'edges' => graph.edges.length,
         'entry_points' => graph.entry_points.length,
-        'findings' => findings.length,
+        'findings' => reported_findings.length,
         'unreachable' => grouped.fetch(:unreachable, []).length,
         'unused' => grouped.fetch(:unused, []).length,
         'test_only_reachable' => grouped.fetch(:test_only_reachable, []).length
       }
     end
+
+    private
+
+    attr_reader :report_include_paths, :report_exclude_paths
+
+    def reported_findings
+      @reported_findings ||= findings.select do |finding|
+        included_in_report?(finding.node.file) && !excluded_from_report?(finding.node.file)
+      end
+    end
+
+    def included_in_report?(path)
+      report_include_paths.empty? || report_include_paths.any? { |pattern| path_matches?(pattern, path) }
+    end
+
+    def excluded_from_report?(path)
+      report_exclude_paths.any? { |pattern| path_matches?(pattern, path) }
+    end
+
+    def path_matches?(pattern, path)
+      File.fnmatch?(pattern, path, File::FNM_PATHNAME | File::FNM_EXTGLOB) ||
+        File.fnmatch?(File.join(pattern, '**', '*'), path, File::FNM_PATHNAME | File::FNM_EXTGLOB)
+    end
   end
 end

data/lib/necropsy/reporter.rb

@@ -2,21 +2,27 @@
 
 module Necropsy
   class Reporter
+    FORMATS = %i[human json yaml yml sarif github annotations].freeze
+    DEFAULT_MIN_CONFIDENCE = :medium
+
     def initialize(report)
       @report = report
     end
 
-    def render(format: :human, min_confidence: :low)
-      case format.to_sym
+    def render(format: :human, min_confidence: DEFAULT_MIN_CONFIDENCE, include_graph: false)
+      normalized_format = format.to_sym
+      raise Error, "Unknown report format: #{format}" unless FORMATS.include?(normalized_format)
+
+      case normalized_format
       when :json
-        report.to_json
+        report.to_json(include_graph: include_graph)
       when :sarif
         render_sarif(min_confidence)
       when :github, :annotations
         render_github_annotations(min_confidence)
       when :yaml, :yml
-        report.to_yaml
-      else
+        report.to_yaml(include_graph: include_graph)
+      when :human
         render_human(min_confidence)
       end
     end

data/lib/necropsy/runner.rb

@@ -12,17 +12,28 @@ module Necropsy
 
     def analyze
       project = Project.new(root: root, config: config)
-      graph = CallGraph.new(project.scan_result)
+      graph = CallGraph.new(project.scan_result, ambiguity_limit: config.ambiguity_limit)
+      rta_results = []
 
       apply_entry_points(graph, project)
       configured_analyzers.each do |analyzer|
         graph.add_profile(analyzer.profile)
-        graph.apply_result(analyzer.analyze(graph, project))
+        result = analyzer.analyze(graph, project)
+        graph.apply_result(result)
+        rta_results << result if analyzer.profile.name == :rta
       end
+      rta_results.each { |result| graph.reconcile_rta_result(result) }
 
       reachability = Reachability::Engine.new(graph).call
       findings = Confidence::Scorer.new(graph: graph, reachability: reachability, project: project).findings
-      Report.new(root: root, graph: graph, findings: findings)
+      Report.new(
+        root: root,
+        graph: graph,
+        findings: findings,
+        reachability: reachability,
+        report_include_paths: config.report_include_paths,
+        report_exclude_paths: config.report_exclude_paths
+      )
     end
 
     private
@@ -45,6 +56,8 @@ module Necropsy
           Analyzers::Static::CHA.new
         when 'rta'
           Analyzers::Static::RTA.new
+        else
+          raise Error, "Unknown static analyzer: #{name}"
         end
       end
 
@@ -60,13 +73,29 @@ module Necropsy
     end
 
     def custom_analyzers
-      config.custom_analyzers.map do |class_name|
+      config.custom_analyzers.map do |entry|
+        class_name, required_path = custom_analyzer_definition(entry)
+        require_custom_analyzer(required_path) if required_path
         constantize(class_name).new
       rescue NameError => e
         raise Error, "Could not load custom analyzer #{class_name}: #{e.message}"
+      rescue LoadError => e
+        raise Error, "Could not require custom analyzer #{class_name}: #{e.message}"
       end
     end
 
+    def custom_analyzer_definition(entry)
+      return [entry, nil] unless entry.is_a?(Hash)
+
+      [entry.fetch('class'), entry['require']]
+    end
+
+    def require_custom_analyzer(path)
+      expanded = File.expand_path(path, root)
+      expanded = "#{expanded}.rb" if !File.file?(expanded) && File.file?("#{expanded}.rb")
+      File.file?(expanded) ? require(expanded) : require(path)
+    end
+
     def constantize(class_name)
       class_name.split('::').reduce(Object) { |constant, name| constant.const_get(name) }
     end

data/lib/necropsy/trace_point_runtime.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'necropsy'
+
+root = ENV.fetch('NECROPSY_TRACE_ROOT', nil)
+output = ENV.fetch('NECROPSY_TRACE_OUTPUT', nil)
+sample_rate = ENV.fetch('NECROPSY_TRACE_SAMPLE_RATE', '1.0').to_f
+merge = ENV['NECROPSY_TRACE_MERGE'] == '1'
+run_id = ENV.fetch('NECROPSY_TRACE_RUN_ID', nil)
+
+if root && output
+  Necropsy::Analyzers::Dynamic::TracePointCollector.install_at_exit(
+    root: root,
+    output: output,
+    sample_rate: sample_rate,
+    merge: merge,
+    run_id: run_id
+  )
+end

data/lib/necropsy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Necropsy
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/necropsy.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# Set is built in on supported Rubies, but requiring it keeps direct file loading portable.
+require 'set' # rubocop:disable Lint/RedundantRequireStatement
+
 require_relative 'necropsy/version'
 require_relative 'necropsy/models'
 require_relative 'necropsy/configuration'
@@ -23,6 +26,7 @@ require_relative 'necropsy/reachability/engine'
 require_relative 'necropsy/confidence/scorer'
 require_relative 'necropsy/report'
 require_relative 'necropsy/reporter'
+require_relative 'necropsy/diagnostics'
 require_relative 'necropsy/guardrail/baseline'
 require_relative 'necropsy/guardrail/diff'
 require_relative 'necropsy/guardrail/quarantine'

data/script/measure.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative '../lib/necropsy'
+
+root = File.expand_path(ARGV[0] || '.', Dir.pwd)
+config_path = ARGV[1]
+started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+report = Necropsy.analyze(root: root, config_path: config_path)
+elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+node_count = report.graph.nodes.size
+
+puts({
+  root: root,
+  nodes: node_count,
+  edges: report.graph.edges.size,
+  findings: report.findings.size,
+  ratio: node_count.zero? ? 0.0 : (100.0 * report.findings.size / node_count).round(1),
+  by_confidence: report.findings.group_by(&:confidence).transform_values(&:size),
+  seconds: elapsed.round(2)
+}.inspect)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: necropsy
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Yudai Takada
@@ -16,6 +16,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -23,6 +26,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 description: Necropsy combines static call-graph reachability, optional dynamic evidence,
   and CI guardrails for Ruby dead-code detection.
 email:
@@ -32,7 +38,10 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".rubocop.yml"
+- CHANGELOG.md
 - LICENSE.txt
+- MEASUREMENTS.md
 - README.md
 - Rakefile
 - exe/necropsy
@@ -47,12 +56,20 @@ files:
 - lib/necropsy/analyzers/static/name_resolution.rb
 - lib/necropsy/analyzers/static/rta.rb
 - lib/necropsy/ast_scanner.rb
+- lib/necropsy/ast_scanner/call_recording.rb
+- lib/necropsy/ast_scanner/dsl_macros.rb
+- lib/necropsy/ast_scanner/method_definitions.rb
+- lib/necropsy/ast_scanner/references.rb
+- lib/necropsy/ast_scanner/ruby_semantics.rb
+- lib/necropsy/ast_scanner/traversal.rb
+- lib/necropsy/ast_scanner/value_definitions.rb
 - lib/necropsy/bench/evaluator.rb
 - lib/necropsy/cache/scan_cache.rb
 - lib/necropsy/cli.rb
 - lib/necropsy/confidence/scorer.rb
 - lib/necropsy/configuration.rb
 - lib/necropsy/coverage_runtime.rb
+- lib/necropsy/diagnostics.rb
 - lib/necropsy/entry_points/plain.rb
 - lib/necropsy/entry_points/rails.rb
 - lib/necropsy/entry_points/test.rb
@@ -66,14 +83,17 @@ files:
 - lib/necropsy/report.rb
 - lib/necropsy/reporter.rb
 - lib/necropsy/runner.rb
+- lib/necropsy/trace_point_runtime.rb
 - lib/necropsy/version.rb
+- script/measure.rb
 homepage: https://github.com/ydah/necropsy
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/ydah/necropsy
-  source_code_uri: https://github.com/ydah/necropsy.git
+  source_code_uri: https://github.com/ydah/necropsy/tree/main
+  changelog_uri: https://github.com/ydah/necropsy/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: