necropsy 0.2.0 → 0.3.0

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

data/lib/necropsy/definition_identity/canonical_digest.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+
+module Necropsy
+  module DefinitionIdentity
+    class CanonicalizationError < StandardError; end
+    class LimitExceeded < CanonicalizationError; end
+    class CycleError < CanonicalizationError; end
+    class UnsupportedTypeError < CanonicalizationError; end
+
+    class CanonicalDigest
+      MAX_DEPTH = 256
+      MAX_ITEMS = 1_000_000
+      MAX_SCALAR_BYTES = 64 * 1024 * 1024
+      MAX_TOTAL_BYTES = 256 * 1024 * 1024
+
+      def initialize(max_depth: MAX_DEPTH, max_items: MAX_ITEMS, max_scalar_bytes: MAX_SCALAR_BYTES,
+                     max_total_bytes: MAX_TOTAL_BYTES)
+        @max_depth = positive_limit(max_depth, :max_depth)
+        @max_items = positive_limit(max_items, :max_items)
+        @max_scalar_bytes = positive_limit(max_scalar_bytes, :max_scalar_bytes)
+        @max_total_bytes = positive_limit(max_total_bytes, :max_total_bytes)
+      end
+
+      def hexdigest(value)
+        reset_state
+        output = DigestOutput.new(byte_budget)
+        process([[:value, value, 0, output]])
+        output.hexdigest
+      end
+
+      def hexdigest_payload(values)
+        reset_state
+        output = DigestOutput.new(byte_budget)
+        output.write('[')
+        values.each_with_index do |value, index|
+          count_item!
+          output.write(',') if index.positive?
+          output.write(payload_scalar(value))
+        end
+        output.write(']')
+        output.hexdigest
+      end
+
+      private
+
+      attr_reader :max_depth, :max_items, :max_scalar_bytes, :max_total_bytes, :active_containers, :byte_budget
+
+      def reset_state
+        @active_containers = {}
+        @items = 0
+        @byte_budget = ByteBudget.new(max_total_bytes)
+      end
+
+      def process(stack)
+        until stack.empty?
+          action, *arguments = stack.pop
+          send("process_#{action}", stack, *arguments)
+        end
+      rescue CanonicalizationError
+        raise
+      rescue SystemStackError => e
+        raise CanonicalizationError, "Could not canonicalize definition: #{e.message}"
+      rescue StandardError => e
+        raise CanonicalizationError, "Could not canonicalize definition: #{e.class}: #{e.message}"
+      end
+
+      def process_value(stack, value, depth, output)
+        count_item!
+        check_depth!(depth)
+        case value
+        when Prism::Node then start_node(stack, value, depth, output)
+        when Prism::Location then output.write('null')
+        when Array then start_array(stack, value, depth, output)
+        when Hash then start_hash(stack, value, depth, output)
+        when Symbol then tagged_scalar(output, 'symbol', value.to_s)
+        when String then tagged_scalar(output, 'string', value)
+        when Integer then tagged_scalar(output, 'integer', value.to_s)
+        when Float then write_float(output, value)
+        when true, false then output.write(%(["boolean",#{value}]))
+        when nil then output.write('["nil"]')
+        else raise UnsupportedTypeError, "Unsupported definition payload type: #{value.class}"
+        end
+      end
+
+      def start_node(stack, node, depth, output)
+        enter_container!(node)
+        fields = node.deconstruct_keys(nil).filter_map do |key, value|
+          [key.to_s, value] unless DefinitionIdentity.send(:excluded_key?, key)
+        end.sort_by(&:first)
+        type = checked_string(node.type.to_s)
+        flags = node.send(:flags) & ~Prism::NodeFlags::NEWLINE
+        output.write("[\"node\",#{json_string(type)},#{flags},[")
+        stack << [:node_field, node, fields, 0, depth, output]
+      end
+
+      def process_node_field(stack, node, fields, index, depth, output)
+        if index >= fields.length
+          output.write(']]')
+          leave_container(node)
+          return
+        end
+
+        key, value = fields.fetch(index)
+        output.write(',') if index.positive?
+        output.write("[#{json_string(checked_string(key))},")
+        stack << [:node_field_complete, node, fields, index, depth, output]
+        stack << [:value, value, depth + 1, output]
+      end
+
+      def process_node_field_complete(stack, node, fields, index, depth, output)
+        output.write(']')
+        stack << [:node_field, node, fields, index + 1, depth, output]
+      end
+
+      def start_array(stack, value, depth, output)
+        enter_container!(value)
+        output.write('["array",[')
+        stack << [:array_next, value, 0, depth, output]
+      end
+
+      def process_array_next(stack, value, index, depth, output)
+        if index >= value.length
+          output.write(']]')
+          leave_container(value)
+          return
+        end
+
+        output.write(',') if index.positive?
+        stack << [:array_next, value, index + 1, depth, output]
+        stack << [:value, value.fetch(index), depth + 1, output]
+      end
+
+      def start_hash(stack, value, depth, output)
+        enter_container!(value)
+        stack << [:hash_next, value, value.each_pair, [], depth, output]
+      end
+
+      def process_hash_next(stack, value, iterator, pairs, depth, output)
+        key, item = iterator.next
+        pair = StringOutput.new(byte_budget)
+        pair.write('[')
+        stack << [:hash_pair_complete, value, iterator, pairs, depth, output, pair]
+        stack << [:raw, pair, ']']
+        stack << [:value, item, depth + 1, pair]
+        stack << [:raw, pair, ',']
+        stack << [:value, key, depth + 1, pair]
+      rescue StopIteration
+        output.write('["hash",[')
+        pairs.sort.each_with_index do |pair, index|
+          output.write(',') if index.positive?
+          output.write(pair)
+        end
+        output.write(']]')
+        leave_container(value)
+      end
+
+      def process_hash_pair_complete(stack, value, iterator, pairs, depth, output, pair)
+        pairs << pair.to_s
+        stack << [:hash_next, value, iterator, pairs, depth, output]
+      end
+
+      def process_raw(_stack, output, bytes)
+        output.write(bytes)
+      end
+
+      def tagged_scalar(output, tag, value)
+        output.write(%([#{json_string(tag)},#{json_string_or_fingerprint(value)}]))
+      end
+
+      def write_float(output, value)
+        raise UnsupportedTypeError, 'Definition payload contains a non-finite float' unless value.finite?
+
+        tagged_scalar(output, 'float', value.to_s)
+      end
+
+      def payload_scalar(value)
+        case value
+        when String then json_string_or_fingerprint(value)
+        when Integer then value.to_s
+        else raise UnsupportedTypeError, "Unsupported definition identity component: #{value.class}"
+        end
+      end
+
+      def json_string_or_fingerprint(value)
+        checked_string(value)
+        JSON.generate(value)
+      rescue JSON::GeneratorError, EncodingError
+        JSON.generate(['invalid_string', value.encoding.name, value.bytesize, Digest::SHA256.hexdigest(value.b)])
+      end
+
+      def json_string(value)
+        JSON.generate(value)
+      end
+
+      def checked_string(value)
+        return value if value.bytesize <= max_scalar_bytes
+
+        raise LimitExceeded, "Canonical scalar exceeds maximum size #{max_scalar_bytes}"
+      end
+
+      def enter_container!(value)
+        object_id = value.object_id
+        raise CycleError, "Definition payload contains a cycle at #{value.class}" if active_containers.key?(object_id)
+
+        active_containers[object_id] = true
+      end
+
+      def leave_container(value)
+        active_containers.delete(value.object_id)
+      end
+
+      def check_depth!(depth)
+        return if depth <= max_depth
+
+        raise LimitExceeded, "Canonical payload exceeds maximum depth #{max_depth}"
+      end
+
+      def count_item!
+        @items += 1
+        raise LimitExceeded, "Canonical payload exceeds maximum item count #{max_items}" if @items > max_items
+      end
+
+      def positive_limit(value, name)
+        value = Integer(value)
+        raise ArgumentError, "#{name} must be positive" unless value.positive?
+
+        value
+      end
+
+      class DigestOutput
+        def initialize(budget)
+          @budget = budget
+          @digest = Digest::SHA256.new
+        end
+
+        def write(value)
+          @budget.consume(value.bytesize)
+          @digest.update(value.b)
+        end
+
+        def hexdigest
+          @digest.hexdigest
+        end
+      end
+
+      class StringOutput
+        def initialize(budget)
+          @budget = budget
+          @value = String.new(encoding: Encoding::BINARY)
+        end
+
+        def write(value)
+          @budget.consume(value.bytesize)
+          @value << value.b
+        end
+
+        def to_s
+          @value
+        end
+      end
+
+      class ByteBudget
+        def initialize(limit)
+          @limit = limit
+          @bytes = 0
+        end
+
+        def consume(bytes)
+          @bytes += bytes
+          raise LimitExceeded, "Canonical payload exceeds maximum size #{@limit}" if @bytes > @limit
+        end
+      end
+    end
+  end
+end

data/lib/necropsy/definition_identity.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'prism'
+require_relative 'definition_identity/canonical_digest'
+
+module Necropsy
+  module DefinitionIdentity
+    VERSION = 1
+    PREFIX = "def:v#{VERSION}".freeze
+    EXCLUDED_KEYS = %i[node_id location flags].freeze
+
+    module_function
+
+    def body_digest(node, **limits)
+      CanonicalDigest.new(**limits).hexdigest(node)
+    end
+
+    def definition_id(kind:, symbol_id:, relative_path:, body_digest:, ordinal:)
+      ordinal = Integer(ordinal)
+      raise ArgumentError, 'definition ordinal must be positive' unless ordinal.positive?
+
+      payload = [kind.to_s, symbol_id.to_s, relative_path.to_s, body_digest.to_s, ordinal]
+      "#{PREFIX}:#{CanonicalDigest.new.hexdigest_payload(payload)}"
+    end
+
+    def file_root_id(relative_path:)
+      payload = ['file_root', relative_path.to_s]
+      "#{PREFIX}:#{CanonicalDigest.new.hexdigest_payload(payload)}"
+    end
+
+    def excluded_key?(key)
+      name = key.to_s
+      EXCLUDED_KEYS.include?(key.to_sym) || name.end_with?('_loc', 'comment', 'comments')
+    end
+    private_class_method :excluded_key?
+  end
+end