necropsy 0.1.0 → 0.3.0

data/lib/necropsy/configuration.rb

@@ -1,30 +1,91 @@
 # 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[
+      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 expiry],
+      'bench' => %w[precision_threshold recall_threshold],
+      'cache' => %w[enabled path],
+      'rta' => %w[factory_methods pruning],
+      'resolution' => %w[ambiguity_limit],
+      'paths' => %w[analyze reference test include exclude],
+      'report' => %w[include exclude],
+      'logging' => %w[verbose]
+    }.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
 
     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
       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
@@ -37,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
@@ -53,26 +116,43 @@ 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
       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?
@@ -81,25 +161,148 @@ 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 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?
+      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 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
+      analyze_paths
+    end
+
+    def legacy_include_paths?
+      !fetch('paths', 'include').nil? && fetch('paths', 'analyze').nil?
+    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 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)
-      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 +315,123 @@ 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)
+        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)
+      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_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|
+        raise Error, 'Each custom analyzer must be a mapping with class and trusted: true' unless entry.is_a?(Hash)
+
+        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
+
+    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/convention_rules.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Necropsy
+  class ConventionRules
+    Rule = Data.define(:id, :family, :method_names, :owner_patterns, :ancestor_patterns, :frameworks) do
+      def initialize(id:, family:, methods: [], owner_patterns: [], ancestor_patterns: [], frameworks: [])
+        id = id.to_s
+        family = family.to_sym
+        raise ArgumentError, 'rule id must not be empty' if id.empty?
+        raise ArgumentError, 'rule family must not be empty' if family.to_s.empty?
+        raise ArgumentError, 'rule methods must be bounded strings' unless Array(methods).all? do |name|
+          name.is_a?(String) && !name.empty? && name.bytesize <= 128
+        end
+        raise ArgumentError, 'rule owner patterns must be bounded strings' unless Array(owner_patterns).all? do |pattern|
+          pattern.is_a?(String) && !pattern.empty? && pattern.bytesize <= 256
+        end
+        raise ArgumentError, 'rule ancestor patterns must be bounded strings' unless Array(ancestor_patterns).all? do |pattern|
+          pattern.is_a?(String) && !pattern.empty? && pattern.bytesize <= 256
+        end
+        raise ArgumentError, 'rule frameworks must be bounded strings' unless Array(frameworks).all? do |name|
+          name.is_a?(String) && !name.empty? && name.bytesize <= 64
+        end
+        raise ArgumentError, 'rules may not be unscoped' if Array(owner_patterns).empty? && Array(ancestor_patterns).empty?
+
+        super(
+          id: id.freeze,
+          family: family,
+          method_names: Array(methods).map(&:to_s).uniq.sort.freeze,
+          owner_patterns: Array(owner_patterns).map(&:to_s).uniq.sort.freeze,
+          ancestor_patterns: Array(ancestor_patterns).map(&:to_s).uniq.sort.freeze,
+          frameworks: Array(frameworks).map(&:to_s).uniq.sort.freeze
+        )
+      end
+    end
+
+    BUILT_IN = [
+      Rule.new(
+        id: 'rubocop.event_callback', family: :ancestor_scoped_hook,
+        ancestor_patterns: ['RuboCop::Cop', 'RuboCop::Cop::Base'], frameworks: ['rubocop']
+      ),
+      Rule.new(
+        id: 'rails.callback_symbol', family: :symbol_argument_method_reference,
+        methods: %w[after_action after_save before_action before_save validate],
+        owner_patterns: ['*Controller', '*Job', '*Mailer', '*Record', '*Validator'], frameworks: ['rails']
+      ),
+      Rule.new(
+        id: 'rails.application_base', family: :ancestor_scoped_hook,
+        methods: %w[after_action after_save before_action before_save validate],
+        ancestor_patterns: %w[ApplicationController ApplicationJob ApplicationMailer ApplicationRecord],
+        frameworks: ['rails']
+      ),
+      Rule.new(
+        id: 'rails.action_cable', family: :framework_runtime_hook,
+        methods: %w[receive subscribed unsubscribed], owner_patterns: ['*Channel'], frameworks: ['rails']
+      ),
+      Rule.new(
+        id: 'rails.active_job', family: :framework_runtime_hook,
+        methods: %w[deserialize perform serialize], owner_patterns: ['*Job'], ancestor_patterns: ['ApplicationJob'],
+        frameworks: ['rails']
+      ),
+      Rule.new(
+        id: 'sidekiq.worker', family: :framework_runtime_hook,
+        methods: ['perform'], ancestor_patterns: %w[Sidekiq::Job Sidekiq::Worker], frameworks: ['sidekiq']
+      ),
+      Rule.new(
+        id: 'graphql.runtime', family: :framework_runtime_hook,
+        methods: %w[authorized? ready? resolve subscribed update],
+        owner_patterns: %w[*Mutation *Resolver *Subscription *Type],
+        ancestor_patterns: %w[GraphQL::Schema::Mutation GraphQL::Schema::Resolver GraphQL::Schema::Subscription],
+        frameworks: ['graphql']
+      ),
+      Rule.new(
+        id: 'active_model_serializers.public_surface', family: :declarative_public_surface,
+        owner_patterns: ['*Serializer'], frameworks: ['active_model_serializers']
+      ),
+      Rule.new(
+        id: 'blueprinter.public_surface', family: :declarative_public_surface,
+        owner_patterns: ['*Blueprint'], frameworks: ['blueprinter']
+      ),
+      Rule.new(
+        id: 'view_component.runtime', family: :framework_runtime_hook,
+        methods: %w[before_render call render?], owner_patterns: ['*Component'], frameworks: ['view_component']
+      )
+    ].freeze
+
+    MAX_RULES = 32
+
+    def initialize(rules: BUILT_IN)
+      @rules = Array(rules).freeze
+      validate_rules!
+    end
+
+    def method_hit(owner:, method_name:, ancestors:, frameworks: [])
+      candidate = @rules.find do |rule|
+        next false unless rule.method_names.empty? || rule.method_names.include?(method_name.to_s)
+        next false unless framework_enabled?(rule, frameworks)
+
+        scoped_match?(rule, owner, ancestors)
+      end
+      hit(candidate, owner: owner, method_name: method_name) if candidate
+    end
+
+    private
+
+    attr_reader :rules
+
+    def validate_rules!
+      raise ArgumentError, "too many convention rules (max #{MAX_RULES})" if rules.length > MAX_RULES
+
+      ids = rules.map(&:id)
+      raise ArgumentError, 'convention rule ids must be unique' unless ids.uniq == ids
+    end
+
+    def framework_enabled?(rule, frameworks)
+      rule.frameworks.empty? || rule.frameworks.intersect?(Array(frameworks).map(&:to_s))
+    end
+
+    def scoped_match?(rule, owner, ancestors)
+      owner = owner.to_s
+      ancestors = Array(ancestors).map(&:to_s)
+      owner_matches = rule.owner_patterns.any? { |pattern| File.fnmatch?(pattern, owner, File::FNM_EXTGLOB) }
+      ancestor_matches = rule.ancestor_patterns.any? do |pattern|
+        ancestors.any? { |candidate| candidate == pattern || candidate.start_with?("#{pattern}::") }
+      end
+      owner_matches || ancestor_matches
+    end
+
+    def hit(rule, owner:, method_name:)
+      {
+        'rule_id' => rule.id,
+        'family' => rule.family.to_s,
+        'owner' => owner.to_s,
+        'method' => method_name.to_s,
+        'reason' => "#{rule.id} matched #{owner}##{method_name}"
+      }.freeze
+    end
+  end
+end