necropsy 0.1.0 → 0.2.0

data/lib/necropsy/configuration.rb

@@ -6,19 +6,41 @@ module Necropsy
   class Configuration
     DEFAULT_FAIL_ON = :high
     DEFAULT_BASELINE = '.necropsy_baseline.yml'
+    TOP_LEVEL_KEYS = %w[
+      analyzers frameworks entry_points ci quarantine bench cache rta resolution paths report logging implicit_callers
+    ].freeze
+    NESTED_KEYS = {
+      'analyzers' => %w[static dynamic custom],
+      'analyzers.dynamic' => %w[coverage coverband trace_point],
+      'entry_points' => %w[extra],
+      'ci' => %w[baseline fail_on],
+      'quarantine' => %w[days],
+      'bench' => %w[precision_threshold recall_threshold],
+      'cache' => %w[enabled path],
+      'rta' => %w[factory_methods],
+      'resolution' => %w[ambiguity_limit],
+      'paths' => %w[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
+    IMPLICIT_CALLER_KEYS = %w[name_pattern owner_ancestors reason].freeze
 
     attr_reader :root, :path, :data
 
     def self.load(root:, path: nil)
       config_path = path ? File.expand_path(path, root) : File.join(root, '.necropsy.yml')
-      data = File.exist?(config_path) ? YAML.load_file(config_path) : {}
+      data = File.exist?(config_path) ? YAML.safe_load_file(config_path, permitted_classes: [Symbol], aliases: true) : {}
       new(root: root, path: config_path, data: data || {})
+    rescue Psych::Exception => e
+      raise Error, "Could not parse configuration #{config_path}: #{e.message}"
     end
 
     def initialize(root:, path:, data:)
       @root = File.expand_path(root)
       @path = path
       @data = stringify_keys(data)
+      validate!
     end
 
     def static_analyzers
@@ -53,7 +75,10 @@ module Necropsy
     end
 
     def fail_on
-      (fetch('ci', 'fail_on') || DEFAULT_FAIL_ON).to_sym
+      level = (fetch('ci', 'fail_on') || DEFAULT_FAIL_ON).to_sym
+      return level if CONFIDENCE_LEVELS.key?(level)
+
+      raise Error, "Invalid ci.fail_on confidence level: #{level}"
     end
 
     def min_observation_days
@@ -81,25 +106,70 @@ module Necropsy
     end
 
     def cache_path
-      fetch('cache', 'path') || '.necropsy_cache/scan.yml'
+      fetch('cache', 'path') || '.necropsy_cache/scan.json'
     end
 
     def scan_cache_key
-      data.except('cache')
+      data.except('cache', 'report')
     end
 
     def factory_methods
       Array(fetch('rta', 'factory_methods') || %w[build create build_stubbed]).map(&:to_s)
     end
 
+    def ambiguity_limit
+      value = fetch('resolution', 'ambiguity_limit')
+      return 4 if value.nil?
+      return Float::INFINITY if value.to_s == 'unlimited'
+
+      limit = Integer(value)
+      return limit if limit.positive?
+
+      raise Error, 'resolution.ambiguity_limit must be a positive integer or unlimited'
+    rescue ArgumentError, TypeError
+      raise Error, 'resolution.ambiguity_limit must be a positive integer or unlimited'
+    end
+
+    def include_paths
+      Array(fetch('paths', 'include')).map(&:to_s)
+    end
+
+    def exclude_paths
+      Array(fetch('paths', 'exclude')).map(&:to_s)
+    end
+
+    def report_include_paths
+      Array(fetch('report', 'include')).map(&:to_s)
+    end
+
+    def report_exclude_paths
+      Array(fetch('report', 'exclude')).map(&:to_s)
+    end
+
+    def implicit_callers
+      @implicit_callers ||= Array(data['implicit_callers']).map do |entry|
+        {
+          name_pattern: Regexp.new(entry.fetch('name_pattern')),
+          owner_ancestors: Array(entry['owner_ancestors']).map(&:to_s),
+          reason: entry['reason']&.to_s
+        }
+      end
+    end
+
+    def verbose?
+      fetch('logging', 'verbose') == true
+    end
+
     private
 
     def fetch(*keys)
-      keys.reduce(data) do |current, key|
-        break nil unless current.is_a?(Hash)
+      current = data
+      keys.each do |key|
+        return nil unless current.is_a?(Hash)
 
-        current[key.to_s]
+        current = current[key.to_s]
       end
+      current
     end
 
     def stringify_keys(value)
@@ -112,5 +182,53 @@ module Necropsy
         value
       end
     end
+
+    def validate!
+      validate_hash_keys(data, TOP_LEVEL_KEYS, 'configuration')
+      NESTED_KEYS.each do |path, allowed|
+        value = fetch(*path.split('.'))
+        validate_hash_keys(value, allowed, path) if value
+      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
+      end
+      validate_custom_analyzers!
+      validate_implicit_callers!
+      ambiguity_limit
+    end
+
+    def validate_hash_keys(value, allowed, location)
+      raise Error, "#{location} must be a mapping" unless value.is_a?(Hash)
+
+      unknown = value.keys - allowed
+      return if unknown.empty?
+
+      raise Error, "Unknown #{location} option#{'s' if unknown.length > 1}: #{unknown.join(', ')}"
+    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)
+
+        validate_hash_keys(entry, %w[class require], 'custom analyzer')
+        raise Error, 'Custom analyzer mapping requires class' unless entry['class']
+      end
+    end
+
+    def validate_implicit_callers!
+      Array(data['implicit_callers']).each do |entry|
+        raise Error, 'Each implicit caller must be a mapping' unless entry.is_a?(Hash)
+
+        validate_hash_keys(entry, IMPLICIT_CALLER_KEYS, 'implicit caller')
+        pattern = entry['name_pattern']
+        raise Error, 'Implicit caller requires name_pattern' unless pattern.is_a?(String)
+
+        Regexp.new(pattern)
+      rescue RegexpError => e
+        raise Error, "Invalid implicit caller name_pattern: #{e.message}"
+      end
+    end
   end
 end

data/lib/necropsy/diagnostics.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Necropsy
+  class Diagnostics
+    FORMATS = %i[human json].freeze
+
+    def initialize(report)
+      raise Error, 'Reachability witnesses are unavailable for this report' unless report.reachability
+
+      @report = report
+    end
+
+    def why(node_id)
+      node = graph.nodes[node_id]
+      return missing_payload(node_id) unless node
+
+      runtime_path = reachability.witness(node_id)
+      return alive_payload(node, runtime_path, :runtime) if runtime_path
+
+      test_path = reachability.witness(node_id, kind: :test)
+      return alive_payload(node, test_path, :test) if test_path
+
+      dead_payload(node)
+    end
+
+    def explain(node_id)
+      node = graph.nodes[node_id]
+      return missing_payload(node_id) unless node
+
+      finding = report.findings.find { |candidate| candidate.node.id == node_id }
+      return { 'status' => 'alive', 'node' => node.to_h } unless finding
+
+      {
+        'status' => 'finding',
+        'node' => node.to_h,
+        'classification' => finding.classification.to_s,
+        'confidence' => finding.confidence.to_s,
+        'score' => finding.score,
+        'components' => finding.score_components.map(&:to_h),
+        'reasons' => finding.reasons
+      }
+    end
+
+    def render(payload, format: :human)
+      normalized = format.to_sym
+      raise Error, "Diagnostics support only human or json output, not #{format}" unless FORMATS.include?(normalized)
+
+      return JSON.pretty_generate(payload) if normalized == :json
+
+      render_human(payload)
+    end
+
+    private
+
+    attr_reader :report
+
+    def graph
+      report.graph
+    end
+
+    def reachability
+      report.reachability
+    end
+
+    def alive_payload(node, path, kind)
+      {
+        'status' => 'alive',
+        'kind' => kind.to_s,
+        'node' => node.to_h,
+        'path' => path.each_with_index.map do |node_id, index|
+          caller_id = index.positive? ? path[index - 1] : nil
+          path_step(node_id, caller_id)
+        end
+      }
+    end
+
+    def path_step(node_id, caller_id)
+      step = { 'node' => graph.nodes.fetch(node_id).to_h }
+      entry = graph.entry_points.find { |candidate| candidate.node_id == node_id }
+      step['entry_reason'] = entry.reason.to_s if entry
+      return step unless caller_id
+
+      evidences = graph.edges_from(caller_id).fetch(node_id, [])
+      step['edge'] = {
+        'caller_id' => caller_id,
+        'callee_id' => node_id,
+        'evidences' => evidences.map(&:to_h)
+      }
+      step
+    end
+
+    def dead_payload(node)
+      finding = report.findings.find { |candidate| candidate.node.id == node.id }
+      {
+        'status' => 'dead',
+        'node' => node.to_h,
+        'classification' => finding&.classification&.to_s,
+        'nearest_alive' => nearest_alive(node.id),
+        'uncertainties' => graph.uncertainties(node.id)
+      }
+    end
+
+    def nearest_alive(node_id)
+      kinds = reachability.runtime_alive.to_h { |id| [id, 'runtime'] }
+      reachability.test_alive.each { |id| kinds[id] ||= 'test' }
+      visited = { node_id => 0 }
+      queue = [node_id]
+
+      until queue.empty?
+        current = queue.shift
+        neighbors(current).each do |neighbor|
+          next if visited.key?(neighbor)
+
+          distance = visited.fetch(current) + 1
+          return { 'node_id' => neighbor, 'kind' => kinds.fetch(neighbor), 'distance' => distance } if kinds.key?(neighbor)
+
+          visited[neighbor] = distance
+          queue << neighbor
+        end
+      end
+      nil
+    end
+
+    def neighbors(node_id)
+      outgoing = graph.edges_from(node_id).keys
+      incoming = graph.incoming_edges(node_id).map(&:caller_id)
+      (outgoing + incoming).uniq.sort
+    end
+
+    def missing_payload(node_id)
+      terms = [node_id, node_id.split(/[.#]/).last].compact.map(&:downcase).reject { |term| term.length < 2 }
+      suggestions = graph.nodes.keys.select do |candidate|
+        terms.any? { |term| candidate.downcase[term] }
+      end.sort.first(10)
+      { 'status' => 'not_found', 'node_id' => node_id, 'suggestions' => suggestions }
+    end
+
+    def render_human(payload)
+      case payload.fetch('status')
+      when 'alive' then render_alive(payload)
+      when 'dead' then render_dead(payload)
+      when 'finding' then render_explanation(payload)
+      when 'not_found' then render_missing(payload)
+      else "#{payload.dig('node', 'id')} is alive and has no dead-code finding."
+      end
+    end
+
+    def render_alive(payload)
+      lines = ["Alive (#{payload.fetch('kind')}): #{payload.dig('node', 'id')}"]
+      payload.fetch('path').each_with_index do |step, index|
+        suffix = step['entry_reason'] ? " entry=#{step['entry_reason']}" : ''
+        lines << "  #{index}. #{step.dig('node', 'id')}#{suffix}"
+        Array(step.dig('edge', 'evidences')).each { |evidence| lines << render_evidence(evidence) }
+      end
+      lines.join("\n")
+    end
+
+    def render_evidence(evidence)
+      metadata = evidence.fetch('metadata', {})
+      location = [metadata['file'], metadata['line']].compact.join(':')
+      suffix = location.empty? ? '' : " at #{location}"
+      "     via #{evidence['analyzer']} weight=#{evidence['weight']}#{suffix}: #{evidence['details']}"
+    end
+
+    def render_dead(payload)
+      lines = ["Dead: #{payload.dig('node', 'id')}"]
+      lines << "Classification: #{payload['classification']}" if payload['classification']
+      nearest = payload['nearest_alive']
+      lines << if nearest
+                 "Nearest alive: #{nearest['node_id']} (#{nearest['kind']}, distance #{nearest['distance']})"
+               else
+                 'Nearest alive: none'
+               end
+      lines << 'Uncertainties: none' if payload.fetch('uncertainties').empty?
+      payload.fetch('uncertainties').each { |message| lines << "Uncertainty: #{message}" }
+      lines.join("\n")
+    end
+
+    def render_explanation(payload)
+      lines = [
+        "#{payload.dig('node', 'id')}: #{payload['classification']}",
+        "Confidence: #{payload['confidence']} (score #{format('%.2f', payload['score'])})"
+      ]
+      payload.fetch('components').each do |component|
+        lines << format(
+          '  %<name>-28s %<value>+0.2f  %<details>s',
+          name: component['name'], value: component['value'], details: component['details']
+        )
+      end
+      lines << format('  %<name>-28s  %<value>0.2f', name: 'total', value: payload['score'])
+      lines.join("\n")
+    end
+
+    def render_missing(payload)
+      lines = ["Node not found: #{payload['node_id']}"]
+      lines << "Suggestions: #{payload['suggestions'].join(', ')}" unless payload['suggestions'].empty?
+      lines.join("\n")
+    end
+  end
+end

data/lib/necropsy/entry_points/plain.rb

@@ -24,13 +24,30 @@ module Necropsy
           end
         end
 
+        api_files = primary_library_files(project)
         graph.method_nodes.each do |node|
-          next unless node.file == 'lib/necropsy.rb'
-          next unless node.kind == :singleton_method && node.owner == 'Necropsy'
+          next unless api_files.include?(node.file)
+          next unless node.kind == :singleton_method && node.visibility == :public
 
           graph.add_entry_point(node.id, :public_api_declared)
         end
       end
+
+      private
+
+      def primary_library_files(project)
+        gem_names(project).flat_map do |name|
+          ["lib/#{name.tr('-', '/')}.rb", "lib/#{name.tr('-', '_')}.rb"]
+        end.uniq.select { |relative| File.file?(File.join(project.root, relative)) }
+      end
+
+      def gem_names(project)
+        Dir.glob(File.join(project.root, '*.gemspec')).filter_map do |path|
+          File.read(path)[/\.name\s*=\s*["']([^"']+)["']/, 1]
+        rescue SystemCallError, EncodingError
+          nil
+        end
+      end
     end
   end
 end