necropsy 0.2.0 → 0.3.0

data/lib/necropsy/confidence/scorer.rb

@@ -10,7 +10,7 @@ module Necropsy
         const_missing method_missing respond_to_missing?
       ].freeze
       RUBY_PROTOCOLS = %w[
-        == eql? hash <=> to_s to_str to_a to_h to_proc inspect each call coerce
+        == eql? hash <=> to_s to_str to_a to_h to_proc inspect coerce
         succ initialize_copy marshal_dump marshal_load
       ].freeze
       BUILTIN_IMPLICIT_CALLERS = [
@@ -21,21 +21,25 @@ module Necropsy
         }
       ].freeze
 
-      def initialize(graph:, reachability:, project:)
+      def initialize(graph:, reachability:, project:, clock: Clock.new)
         @graph = graph
         @reachability = reachability
         @project = project
+        @clock = clock
         @source_lines = {}
       end
 
       def findings
         graph.method_nodes.filter_map do |node|
           next if node.test
+          next unless graph.analyze_source?(node.file)
+          next if rails_generated?(node)
 
-          classification = classification_for(node)
+          blockers = graph.matching_blockers(node)
+          classification = classification_for(node, blockers)
           next unless classification
 
-          score, level, reasons, score_components = score_for(node, classification)
+          score, level, reasons, score_components = score_for(node, classification, blockers)
           Finding.new(
             node: node,
             classification: classification,
@@ -43,35 +47,41 @@ module Necropsy
             score: score,
             score_components: score_components,
             reasons: reasons,
-            evidences: graph.incoming_edges(node.id).flat_map(&:evidences) + graph.alive_evidences(node.id)
+            evidences: graph.incoming_edges(node.graph_id).flat_map(&:evidences) + graph.alive_evidences(node.graph_id),
+            blockers: blockers
           )
         end
       end
 
       private
 
-      attr_reader :graph, :reachability, :project
+      attr_reader :graph, :reachability, :project, :clock
 
-      def classification_for(node)
-        return nil if graph.dynamic_alive?(node.id)
-
-        if reachability.runtime_paths.key?(node.id)
-          return :unused if graph.dynamic_enabled? && !generated_accessor?(node)
+      def classification_for(node, blockers)
+        return nil if graph.dynamic_alive?(node.graph_id)
 
+        if reachability.runtime_paths.key?(node.graph_id) || reachability.external_paths.key?(node.graph_id)
           nil
-        elsif reachability.test_paths.key?(node.id)
+        elsif blockers.any?
+          :blocked
+        elsif reachability.test_paths.key?(node.graph_id)
           :test_only_reachable
         else
           :unreachable
         end
       end
 
-      def score_for(node, classification)
+      def score_for(node, classification, blockers)
         reasons = []
         score = base_score(classification)
         components = [score_component("base(#{classification})", score, 'Base classification score')]
 
-        if graph.uncertainties(node.id).any?
+        if blockers.any?
+          components << score_component('matching_blocker', 0.0, 'Incomplete runtime dispatch matches this definition')
+          reasons << "Blocked by #{blockers.length} unresolved runtime dispatch#{'es' unless blockers.one?}."
+        end
+
+        if graph.uncertainties(node.graph_id).any?
           score -= 0.35
           components << score_component('near_metaprogramming', -0.35, 'Unresolved metaprogramming nearby')
           reasons << 'Lowered because this node is near unresolved metaprogramming.'
@@ -95,29 +105,9 @@ module Necropsy
           reasons << "Lowered because #{reason}."
         end
 
-        if classification == :unreachable && graph.dynamic_enabled? && !graph.dynamic_alive?(node.id)
-          score += 0.25
-          components << score_component('absent_from_dynamic', 0.25, 'Absent from dynamic observations')
-          reasons << 'Static unreachable and absent from dynamic observations.'
-        end
+        add_runtime_unobserved_annotation(node, reasons, components)
 
-        if classification == :unreachable && quarantine_expired?(node)
-          raised_score = [score, 0.95].max
-          components << score_component('expired_quarantine', raised_score - score, 'Expired without alive evidence')
-          score = raised_score
-          reasons << 'Raised because quarantine annotation has expired without alive evidence.'
-        end
-
-        if classification == :unused
-          days = observation_days
-          if days && days < project.config.min_observation_days
-            score -= 0.3
-            components << score_component('short_observation', -0.3, "Observed for only #{days} days")
-            reasons << "Observation window is #{days} days, below the configured minimum."
-          else
-            reasons << 'Reachable statically but never observed dynamically.'
-          end
-        end
+        add_quarantine_annotation(node, classification, reasons, components)
 
         clamped_score = score.clamp(0.0, 1.0)
         components << score_component('score_clamp', clamped_score - score, 'Clamped to the 0.0–1.0 range') if clamped_score != score
@@ -128,7 +118,17 @@ module Necropsy
         ScoreComponent.new(name: name, value: value.round(4), details: details)
       end
 
+      def add_runtime_unobserved_annotation(node, reasons, components)
+        return unless graph.dynamic_observation?
+        return if graph.dynamic_alive?(node.graph_id)
+
+        components << score_component('runtime_unobserved', 0.0, 'Informational only; deadness is unchanged')
+        reasons << 'Runtime observations did not include this definition; classification and confidence are unchanged.'
+      end
+
       def base_score(classification)
+        return 0.25 if classification == :blocked
+
         case classification
         when :unreachable
           0.62
@@ -145,6 +145,10 @@ module Necropsy
         %i[attr_reader attr_writer attr_accessor struct_new data_define].include?(node.defined_via)
       end
 
+      def rails_generated?(node)
+        node.defined_via.to_s.start_with?('rails_')
+      end
+
       def implicit_call_reason(node)
         return "#{node.name} is a Ruby hook invoked by the VM" if RUBY_HOOKS.include?(node.name)
         return "#{node.name} is a Ruby protocol method invoked implicitly" if RUBY_PROTOCOLS.include?(node.name)
@@ -161,18 +165,20 @@ module Necropsy
         direct_reason = implicit_call_reason(node)
         return direct_reason if direct_reason
 
-        root_id = implicit_paths[node.id]
+        root_id = implicit_paths[node.graph_id]
         "it is reachable from implicitly invoked #{root_id}" if root_id
       end
 
       def implicit_paths
         @implicit_paths ||= begin
-          roots = graph.method_nodes.reject(&:test).select { |node| implicit_call_reason(node) }.map(&:id)
+          roots = graph.method_nodes.reject(&:test).select { |node| implicit_call_reason(node) }.map(&:graph_id)
           paths = roots.to_h { |node_id| [node_id, node_id] }
           queue = roots.dup
+          head = 0
 
-          until queue.empty?
-            node_id = queue.shift
+          while head < queue.length
+            node_id = queue.fetch(head)
+            head += 1
             graph.edges_from(node_id).each_key do |callee_id|
               next if paths.key?(callee_id)
 
@@ -203,32 +209,71 @@ module Necropsy
         :low
       end
 
-      def observation_days
-        graph.observation.values.filter_map do |value|
-          next unless value.is_a?(Hash)
-
-          value['days'] || value[:days] || value['observation_days'] || value[:observation_days]
-        end.map(&:to_i).max
-      end
-
-      def quarantine_expired?(node)
-        since = quarantine_since(node)
-        return false unless since
+      def add_quarantine_annotation(node, classification, reasons, components)
+        status = quarantine_status(node, classification)
+        return unless status
 
-        since <= Date.today - project.config.quarantine_days
+        case status
+        when :review_required
+          components << score_component(
+            'quarantine_review_required', 0.0, 'Quarantine expired; deadness is unchanged'
+          )
+          reasons << 'Quarantine annotation has expired and requires review; classification and confidence are unchanged.'
+        when :invalid
+          components << score_component(
+            'quarantine_invalid_date', 0.0, 'Invalid quarantine date; deadness is unchanged'
+          )
+          reasons << 'Quarantine annotation has an invalid since date; classification and confidence are unchanged.'
+        when :fingerprint_required
+          components << score_component(
+            'quarantine_fingerprint_required', 0.0, 'Legacy quarantine requires an exact physical fingerprint'
+          )
+          reasons << 'Quarantine annotation requires a physical fingerprint before it can apply to this definition.'
+        when :stale_fingerprint
+          components << score_component(
+            'quarantine_stale_fingerprint', 0.0, 'Quarantine fingerprint does not match this physical definition'
+          )
+          reasons << 'Quarantine annotation is stale or belongs to a different physical definition.'
+        end
       end
 
-      def quarantine_since(node)
+      def quarantine_status(node, classification)
         path = File.join(project.root, node.file)
         return nil unless File.exist?(path)
 
         lines = @source_lines[path] ||= File.readlines(path, chomp: true)
-        window = lines[[node.line - 4, 0].max, 4] || []
-        annotation = window.find { |line| line.include?('necropsy:quarantine') && line.match?(/\bsince=/) }
-        return nil unless annotation
+        annotation = node.line > 1 ? lines[node.line - 2] : nil
+        return nil unless annotation&.include?('necropsy:quarantine') && annotation.match?(/\bsince=/)
+
+        fingerprints = quarantine_fingerprints(annotation)
+        fingerprint_status = if fingerprints.nil?
+                               :fingerprint_required
+                             elsif fingerprints.include?(node.physical_fingerprint(classification))
+                               :matched
+                             else
+                               :stale_fingerprint
+                             end
+
+        raw_since = annotation[/\bsince=([^\s]+)/, 1]
+        return :invalid unless raw_since
+
+        since = Date.iso8601(raw_since)
+        return fingerprint_status unless fingerprint_status == :matched
+
+        since <= clock.date - project.config.quarantine_days ? :review_required : :active
+      rescue ArgumentError, TypeError
+        :invalid
+      rescue SystemCallError
+        nil
+      end
+
+      def quarantine_fingerprints(annotation)
+        single = annotation[/\bfingerprint=([0-9a-f]{64})(?:\s|$)/, 1]
+        multiple = annotation[/\bfingerprints=([0-9a-f]{64}(?:,[0-9a-f]{64})*)(?:\s|$)/, 1]
+        return [single] if single
+        return multiple.split(',') if multiple
+        return [] if annotation.match?(/\bfingerprints?=/)
 
-        Date.iso8601(annotation[/\bsince=([0-9-]+)/, 1])
-      rescue ArgumentError, SystemCallError
         nil
       end
     end

data/lib/necropsy/configuration.rb

@@ -1,30 +1,49 @@
 # frozen_string_literal: true
 
 require 'yaml'
+require 'pathname'
+require 'prism'
 
 module Necropsy
   class Configuration
     DEFAULT_FAIL_ON = :high
     DEFAULT_BASELINE = '.necropsy_baseline.yml'
+    RTA_PRUNING_MODES = %w[rank_only legacy].freeze
+    STATIC_ANALYZER_ORDER = %w[name_resolution cha rta].freeze
+    QUARANTINE_EXPIRY_POLICIES = %w[warn fail ignore].freeze
+    WORLD_MODES = %w[application library].freeze
+    LOAD_ROOT_POLICIES = %w[known all].freeze
+    FRAMEWORK_GEMS = {
+      'rails' => 'rails',
+      'rubocop' => 'rubocop',
+      'sidekiq' => 'sidekiq',
+      'graphql' => 'graphql',
+      'view_component' => 'view_component',
+      'active_model_serializers' => 'active_model_serializers',
+      'blueprinter' => 'blueprinter'
+    }.freeze
     TOP_LEVEL_KEYS = %w[
-      analyzers frameworks entry_points ci quarantine bench cache rta resolution paths report logging implicit_callers
+      analysis analyzers frameworks entry_points ci quarantine bench cache rta resolution paths report logging
+      implicit_callers
     ].freeze
     NESTED_KEYS = {
+      'analysis' => %w[world load_roots],
       'analyzers' => %w[static dynamic custom],
       'analyzers.dynamic' => %w[coverage coverband trace_point],
       'entry_points' => %w[extra],
       'ci' => %w[baseline fail_on],
-      'quarantine' => %w[days],
+      'quarantine' => %w[days expiry],
       'bench' => %w[precision_threshold recall_threshold],
       'cache' => %w[enabled path],
-      'rta' => %w[factory_methods],
+      'rta' => %w[factory_methods pruning],
       'resolution' => %w[ambiguity_limit],
-      'paths' => %w[include exclude],
+      'paths' => %w[analyze reference test include exclude],
       'report' => %w[include exclude],
       'logging' => %w[verbose]
     }.freeze
-    DYNAMIC_KEYS = %w[source min_observation_days keys key pattern connect_timeout read_timeout].freeze
+    DYNAMIC_KEYS = %w[source min_observation_days expected_source_revision keys key pattern connect_timeout read_timeout].freeze
     IMPLICIT_CALLER_KEYS = %w[name_pattern owner_ancestors reason].freeze
+    CUSTOM_ANALYZER_KEYS = %w[class require trusted].freeze
 
     attr_reader :root, :path, :data
 
@@ -47,6 +66,26 @@ module Necropsy
       Array(fetch('analyzers', 'static') || %w[name_resolution cha rta]).map(&:to_s)
     end
 
+    def world
+      configured = fetch('analysis', 'world')
+      mode = configured.nil? ? 'application' : configured.to_s
+      return mode.to_sym if WORLD_MODES.include?(mode)
+
+      raise Error, "analysis.world must be one of: #{WORLD_MODES.join(', ')}"
+    end
+
+    def library_world?
+      world == :library
+    end
+
+    def load_roots
+      configured = fetch('analysis', 'load_roots')
+      policy = configured.nil? ? 'known' : configured.to_s
+      return policy.to_sym if LOAD_ROOT_POLICIES.include?(policy)
+
+      raise Error, "analysis.load_roots must be one of: #{LOAD_ROOT_POLICIES.join(', ')}"
+    end
+
     def dynamic_config(name)
       fetch('analyzers', 'dynamic', name.to_s) || {}
     end
@@ -59,15 +98,17 @@ module Necropsy
       Array(fetch('entry_points', 'extra')).compact.map(&:to_s)
     end
 
-    def frameworks
-      Array(data['frameworks']).map(&:to_s)
-    end
+    def frameworks(reference_files: nil)
+      return @frameworks if defined?(@frameworks)
 
-    def rails_enabled?
-      return true if frameworks.include?('rails')
+      reference_files ||= Project.new(root: root, config: self).reference_files
+      configured = Array(data['frameworks']).map(&:to_s)
+      @frameworks = (configured + detected_frameworks(reference_files)).uniq.sort.freeze
+    end
 
-      gemfiles = [File.join(root, 'Gemfile.lock'), File.join(root, 'Gemfile')]
-      gemfiles.any? { |file| File.exist?(file) && File.read(file).match?(/(?:^|\s)rails(?:\s|\z|,)/) }
+    def rails_enabled?(reference_files: nil)
+      reference_files ||= Project.new(root: root, config: self).reference_files
+      frameworks(reference_files: reference_files).include?('rails')
     end
 
     def baseline_path
@@ -84,20 +125,34 @@ module Necropsy
     def min_observation_days
       coverage_days = fetch('analyzers', 'dynamic', 'coverage', 'min_observation_days')
       coverband_days = fetch('analyzers', 'dynamic', 'coverband', 'min_observation_days')
-      (coverage_days || coverband_days || 30).to_i
+      Integer(coverage_days || coverband_days || 30)
     end
 
+    REMOTE_DYNAMIC_KEYS = %w[
+      total_timeout max_response_bytes max_bulk_bytes max_array_elements max_resp_depth max_keys max_payload_depth
+    ].freeze
+    DYNAMIC_TIMEOUT_KEYS = %w[connect_timeout read_timeout total_timeout].freeze
+    DYNAMIC_LIMIT_KEYS = (REMOTE_DYNAMIC_KEYS - %w[total_timeout]).freeze
+
     def quarantine_days
-      (fetch('quarantine', 'days') || 30).to_i
+      Integer(fetch('quarantine', 'days') || 30)
+    end
+
+    def quarantine_expiry
+      configured = fetch('quarantine', 'expiry')
+      policy = configured.nil? ? 'warn' : configured.to_s
+      return policy.to_sym if QUARANTINE_EXPIRY_POLICIES.include?(policy)
+
+      raise Error, "quarantine.expiry must be one of: #{QUARANTINE_EXPIRY_POLICIES.join(', ')}"
     end
 
     def bench_precision_threshold
-      (fetch('bench', 'precision_threshold') || 0.85).to_f
+      Float(fetch('bench', 'precision_threshold') || 0.85)
     end
 
     def bench_recall_threshold
       value = fetch('bench', 'recall_threshold')
-      value&.to_f
+      value && Float(value)
     end
 
     def cache_enabled?
@@ -117,6 +172,14 @@ module Necropsy
       Array(fetch('rta', 'factory_methods') || %w[build create build_stubbed]).map(&:to_s)
     end
 
+    def rta_pruning
+      configured = fetch('rta', 'pruning')
+      mode = configured.nil? ? 'rank_only' : configured.to_s
+      return mode.to_sym if RTA_PRUNING_MODES.include?(mode)
+
+      raise Error, "rta.pruning must be one of: #{RTA_PRUNING_MODES.join(', ')}"
+    end
+
     def ambiguity_limit
       value = fetch('resolution', 'ambiguity_limit')
       return 4 if value.nil?
@@ -130,8 +193,28 @@ module Necropsy
       raise Error, 'resolution.ambiguity_limit must be a positive integer or unlimited'
     end
 
+    def analyze_paths
+      configured = fetch('paths', 'analyze')
+      configured = fetch('paths', 'include') if configured.nil?
+      Array(configured).map(&:to_s)
+    end
+
+    def reference_paths
+      configured = fetch('paths', 'reference')
+      Array(configured.nil? ? ['**/*'] : configured).map(&:to_s)
+    end
+
+    def test_paths
+      configured = fetch('paths', 'test')
+      Array(configured.nil? ? %w[spec/** test/**] : configured).map(&:to_s)
+    end
+
     def include_paths
-      Array(fetch('paths', 'include')).map(&:to_s)
+      analyze_paths
+    end
+
+    def legacy_include_paths?
+      !fetch('paths', 'include').nil? && fetch('paths', 'analyze').nil?
     end
 
     def exclude_paths
@@ -162,6 +245,56 @@ module Necropsy
 
     private
 
+    def detected_frameworks(reference_files)
+      dependency_files = reference_files.select do |file|
+        relative = relative_path_from_root(file)
+        %w[Gemfile Gemfile.lock].include?(relative) || relative.end_with?('.gemspec')
+      end
+      dependencies = dependency_files.flat_map { |file| dependency_names(file) }.to_set
+      FRAMEWORK_GEMS.filter_map do |gem_name, framework|
+        framework if dependencies.include?(gem_name)
+      end
+    end
+
+    def dependency_names(file)
+      source = File.read(file)
+      return locked_dependency_names(source) if File.basename(file) == 'Gemfile.lock'
+
+      ruby_dependency_names(source)
+    rescue SystemCallError, EncodingError
+      []
+    end
+
+    def locked_dependency_names(source)
+      source.each_line.filter_map do |line|
+        line[/\A    ([A-Za-z0-9_.-]+) \(/, 1]
+      end
+    end
+
+    def ruby_dependency_names(source)
+      result = Prism.parse(source)
+      return [] if result.failure?
+
+      pending = [result.value]
+      names = []
+      until pending.empty?
+        node = pending.pop
+        if node.is_a?(Prism::CallNode) &&
+           %i[gem add_dependency add_runtime_dependency add_development_dependency].include?(node.name)
+          argument = Array(node.arguments&.arguments).first
+          names << argument.content if argument.is_a?(Prism::StringNode)
+        end
+        pending.concat(node.child_nodes.compact)
+      end
+      names
+    end
+
+    def relative_path_from_root(file)
+      Pathname.new(File.expand_path(file)).relative_path_from(Pathname.new(root)).to_s
+    rescue ArgumentError
+      file.to_s
+    end
+
     def fetch(*keys)
       current = data
       keys.each do |key|
@@ -191,11 +324,20 @@ module Necropsy
       end
       %w[coverage coverband trace_point].each do |name|
         value = fetch('analyzers', 'dynamic', name)
-        validate_hash_keys(value, DYNAMIC_KEYS, "analyzers.dynamic.#{name}") if value
+        next unless value
+
+        validate_hash_keys(value, DYNAMIC_KEYS + REMOTE_DYNAMIC_KEYS, "analyzers.dynamic.#{name}")
+        validate_dynamic_limits!(value, name)
       end
       validate_custom_analyzers!
       validate_implicit_callers!
+      world
+      load_roots
+      rta_pruning
       ambiguity_limit
+      quarantine_expiry
+      validate_numeric_ranges!
+      validate_static_analyzers!
     end
 
     def validate_hash_keys(value, allowed, location)
@@ -207,13 +349,74 @@ module Necropsy
       raise Error, "Unknown #{location} option#{'s' if unknown.length > 1}: #{unknown.join(', ')}"
     end
 
+    def validate_dynamic_limits!(value, name)
+      DYNAMIC_TIMEOUT_KEYS.each do |key|
+        next unless value.key?(key)
+
+        parsed = Float(value[key])
+        dynamic_limit_error!(name, key) unless parsed.positive? && parsed.finite?
+      rescue ArgumentError, TypeError
+        dynamic_limit_error!(name, key)
+      end
+      DYNAMIC_LIMIT_KEYS.each do |key|
+        next unless value.key?(key)
+
+        dynamic_limit_error!(name, key) unless Integer(value[key]).positive?
+      rescue ArgumentError, TypeError
+        dynamic_limit_error!(name, key)
+      end
+    end
+
+    def validate_numeric_ranges!
+      validate_unit_interval!('bench.precision_threshold', bench_precision_threshold)
+      recall = bench_recall_threshold
+      validate_unit_interval!('bench.recall_threshold', recall) if recall
+      validate_positive_integer!('quarantine.days', fetch('quarantine', 'days') || 30)
+      %w[coverage coverband trace_point].each do |name|
+        value = fetch('analyzers', 'dynamic', name, 'min_observation_days')
+        validate_positive_integer!("analyzers.dynamic.#{name}.min_observation_days", value) unless value.nil?
+      end
+    rescue ArgumentError, TypeError
+      raise Error, 'Numeric configuration values must use their documented finite ranges'
+    end
+
+    def validate_unit_interval!(name, value)
+      raise Error, "#{name} must be a finite number between 0 and 1" unless value.finite? && value.between?(0.0, 1.0)
+    end
+
+    def validate_positive_integer!(name, value)
+      valid_form = value.is_a?(Integer) || (value.is_a?(String) && value.match?(/\A\+?\d+\z/))
+      raise Error, "#{name} must be a positive integer" unless valid_form
+
+      parsed = Integer(value)
+      raise Error, "#{name} must be a positive integer" unless parsed.positive?
+    rescue ArgumentError, TypeError
+      raise Error, "#{name} must be a positive integer"
+    end
+
+    def validate_static_analyzers!
+      configured = static_analyzers
+      duplicates = configured.tally.select { |_name, count| count > 1 }.keys
+      raise Error, "Duplicate static analyzers: #{duplicates.sort.join(', ')}" if duplicates.any?
+
+      unknown = configured - STATIC_ANALYZER_ORDER
+      raise Error, "Unknown static analyzer: #{unknown.first}" if unknown.any?
+
+      positions = configured.map { |name| STATIC_ANALYZER_ORDER.index(name) }
+      raise Error, 'Static analyzers must run in name_resolution, cha, rta dependency order' unless positions == positions.sort
+    end
+
+    def dynamic_limit_error!(name, key)
+      raise Error, "analyzers.dynamic.#{name}.#{key} must be a finite positive number"
+    end
+
     def validate_custom_analyzers!
       custom_analyzers.each do |entry|
-        next if entry.is_a?(String)
-        raise Error, 'Each custom analyzer must be a class name or a mapping with class and require' unless entry.is_a?(Hash)
+        raise Error, 'Each custom analyzer must be a mapping with class and trusted: true' unless entry.is_a?(Hash)
 
-        validate_hash_keys(entry, %w[class require], 'custom analyzer')
+        validate_hash_keys(entry, CUSTOM_ANALYZER_KEYS, 'custom analyzer')
         raise Error, 'Custom analyzer mapping requires class' unless entry['class']
+        raise Error, 'Custom analyzer execution requires trusted: true' unless entry['trusted'] == true
       end
     end