insta 0.2.9 → 0.3.0

data/lib/insta/redaction/selector.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module Insta
+  module Redaction
+    class Selector
+      Segment = Struct.new(:type, :value, keyword_init: true) #: Struct[Symbol, untyped]
+
+      SEGMENT_TYPES = [:key, :index, :wildcard, :deep_wildcard, :full_range].freeze #: Array[Symbol]
+
+      attr_reader :segments #: Array[Segment]
+
+      #: (String) -> void
+      def initialize(selector_string)
+        @segments = parse(selector_string)
+      end
+
+      #: (Array[{ type: Symbol, value: untyped }]) -> bool
+      def matches?(path)
+        deep_index = segments.index { |segment| segment.type == :deep_wildcard }
+
+        if deep_index
+          deep_wildcard_match?(path, deep_index)
+        else
+          exact_match?(path, segments)
+        end
+      end
+
+      private
+
+      #: (String) -> Array[Segment]
+      def parse(input)
+        raise ArgumentError, "Selector must not be empty" if input.empty?
+        raise ArgumentError, "Selector must start with '.' or '['" unless input.start_with?(".", "[")
+
+        result = [] #: Array[Segment]
+        position = 0
+
+        while position < input.length
+          case input[position]
+          when "."
+            position = parse_dot_segment(input, position + 1, result)
+          when "["
+            position = parse_bracket_segment(input, position + 1, result)
+          else
+            raise ArgumentError, "Unexpected character '#{input[position]}' at position #{position}"
+          end
+        end
+
+        result
+      end
+
+      #: (String, Integer, Array[Segment]) -> Integer
+      def parse_dot_segment(input, position, result)
+        if position < input.length && input[position] == "*"
+          parse_wildcard_segment(input, position + 1, result)
+        else
+          parse_key_segment(input, position, result)
+        end
+      end
+
+      #: (String, Integer, Array[Segment]) -> Integer
+      def parse_wildcard_segment(input, position, result)
+        if position < input.length && input[position] == "*"
+          raise ArgumentError, "Only one deep wildcard (**) allowed per selector" if result.any? { |segment| segment.type == :deep_wildcard }
+
+          result << Segment.new(type: :deep_wildcard, value: nil)
+
+          position + 1
+        else
+          result << Segment.new(type: :wildcard, value: nil)
+
+          position
+        end
+      end
+
+      #: (String, Integer, Array[Segment]) -> Integer
+      def parse_key_segment(input, position, result)
+        key = +""
+
+        while position < input.length && input[position] != "." && input[position] != "["
+          key << input[position].to_s
+          position += 1
+        end
+
+        raise ArgumentError, "Empty key in selector at position #{position}" if key.empty?
+
+        result << Segment.new(type: :key, value: key)
+
+        position
+      end
+
+      #: (String, Integer, Array[Segment]) -> Integer
+      def parse_bracket_segment(input, position, result)
+        if position < input.length && input[position] == "]"
+          result << Segment.new(type: :full_range, value: nil)
+
+          position + 1
+        elsif position < input.length && input[position] == '"'
+          parse_quoted_key_segment(input, position + 1, result)
+        else
+          parse_index_segment(input, position, result)
+        end
+      end
+
+      #: (String, Integer, Array[Segment]) -> Integer
+      def parse_quoted_key_segment(input, position, result)
+        key = +""
+
+        while position < input.length && input[position] != '"'
+          key << input[position].to_s
+          position += 1
+        end
+
+        raise ArgumentError, "Unterminated quoted key in selector" if position >= input.length
+
+        position += 1
+        raise ArgumentError, "Expected ']' after quoted key" if position >= input.length || input[position] != "]"
+
+        result << Segment.new(type: :key, value: key)
+
+        position + 1
+      end
+
+      #: (String, Integer, Array[Segment]) -> Integer
+      def parse_index_segment(input, position, result)
+        digits = +""
+
+        while position < input.length && input[position] =~ /\d/
+          digits << input[position].to_s
+          position += 1
+        end
+
+        raise ArgumentError, "Expected number or ']' in bracket" if digits.empty?
+        raise ArgumentError, "Expected ']' after index" if position >= input.length || input[position] != "]"
+
+        result << Segment.new(type: :index, value: digits.to_i)
+
+        position + 1
+      end
+
+      #: (Array[{ type: Symbol, value: untyped }], Integer) -> bool
+      def deep_wildcard_match?(path, deep_index)
+        before = segments[0...deep_index] || [] #: Array[Segment]
+        after = segments[(deep_index + 1)..] || [] #: Array[Segment]
+
+        return false if path.length < before.length + after.length
+
+        before.each_with_index do |segment, index|
+          return false unless segment_matches?(segment, path[index])
+        end
+
+        return true if after.empty?
+
+        after_length = after.length
+        path_length = path.length
+
+        after.each_with_index do |segment, index|
+          path_index = path_length - after_length + index
+          return false unless segment_matches?(segment, path[path_index])
+        end
+
+        true
+      end
+
+      #: (Array[{ type: Symbol, value: untyped }], Array[Segment]) -> bool
+      def exact_match?(path, expected_segments)
+        return false unless path.length == expected_segments.length
+
+        expected_segments.each_with_index do |segment, index|
+          return false unless segment_matches?(segment, path[index])
+        end
+
+        true
+      end
+
+      #: (Segment, { type: Symbol, value: untyped }) -> bool
+      def segment_matches?(segment, path_entry)
+        case segment.type
+        when :key
+          path_entry[:type] == :key && path_entry[:value].to_s == segment.value
+        when :index
+          path_entry[:type] == :index && path_entry[:value] == segment.value
+        when :wildcard
+          path_entry[:type] == :key
+        when :full_range
+          path_entry[:type] == :index
+        else
+          false
+        end
+      end
+    end
+  end
+end

data/lib/insta/rspec/hooks.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Insta
+  module RSpec
+    module Hooks
+      #: () -> void
+      def self.install!
+        ::RSpec.configure do |config|
+          config.include(Matchers)
+
+          config.after(:suite) do
+            PendingReporter.flush_and_report!
+          end
+        end
+      end
+    end
+  end
+end

data/lib/insta/rspec/matchers.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require "rspec/expectations"
+
+module Insta
+  module RSpec
+    module Matchers
+      class MatchSnapshot
+        include ::RSpec::Matchers::Composable
+
+        attr_reader :failure_message #: String?
+
+        #: (String?, ?serializer: Symbol?, ?redact: Hash[String, untyped]?) -> void
+        def initialize(name = nil, serializer: nil, redact: nil)
+          @name = name
+          @serializer = serializer
+          @redact = redact
+          @failure_message = nil
+        end
+
+        #: (untyped) -> bool
+        def matches?(actual)
+          @actual = actual
+          expression = actual.class.name
+
+          actual = Redaction::Applicator.apply(actual, @redact) if @redact
+          serializer_name = @serializer || Insta.configuration.default_serializer
+          serialized = Serializers.serialize(serializer_name, actual)
+          content = SnapshotContent.normalize(serialized)
+
+          example = ::RSpec.current_example
+          return record_failure("Could not determine current RSpec example") unless example
+
+          test_class = example.example_group.description || "Anonymous"
+          test_method = example.description || "unknown"
+
+          snapshot_file = resolve_snapshot_file(example, test_class, test_method)
+          path = @name ? snapshot_file.named_path(@name) : snapshot_file.path_for
+
+          metadata = { "source" => "#{test_class} #{test_method}", "expression" => expression }
+          existing = snapshot_file.read(path)
+
+          return handle_new_snapshot(snapshot_file, path, content, metadata) unless existing
+
+          if existing.expression && existing.expression != expression
+            return handle_type_mismatch(snapshot_file, path, content, metadata, existing, expression, example)
+          end
+
+          expected = SnapshotContent.normalize(existing.content)
+          return true if content == expected
+
+          caller_line = example.location
+          handle_mismatch(snapshot_file, path, content, metadata, expected, "#{test_class} #{test_method}", caller_line)
+        end
+
+        #: () -> String
+        def description
+          @name ? "match snapshot \"#{@name}\"" : "match snapshot"
+        end
+
+        private
+
+        #: (untyped, String, String) -> SnapshotFile
+        def resolve_snapshot_file(example, test_class, test_method)
+          if @name
+            SnapshotFile.new(Insta.configuration.snapshot_path, test_class, test_method)
+          else
+            example.metadata[:_insta_snapshot_file] ||= SnapshotFile.new(
+              Insta.configuration.snapshot_path,
+              test_class,
+              test_method
+            )
+          end
+        end
+
+        #: (SnapshotFile, Pathname, String, Snapshot::snapshot_metadata) -> bool
+        def handle_new_snapshot(snapshot_file, path, content, metadata)
+          if Insta.configuration.resolved_update_mode == :no
+            return record_failure("Snapshot file does not exist: #{path}\nRun with INSTA_UPDATE=force to create it.")
+          end
+
+          if Insta.configuration.new_snapshot == :review
+            pending_path = snapshot_file.pending_path(path)
+            snapshot_file.write(pending_path, content, metadata)
+
+            example = ::RSpec.current_example
+            caller_line = example&.location
+            PendingLocations.add(pending_path.to_s, caller_line) if caller_line
+
+            return true if ENV["INSTA_FORCE_PASS"]
+
+            return record_failure("New snapshot pending review: #{path}\nRun `bundle exec insta review` to accept.")
+
+          end
+
+          snapshot_file.write(path, content, metadata)
+
+          true
+        end
+
+        #: (SnapshotFile, Pathname, String, Snapshot::snapshot_metadata, Snapshot, String?, untyped) -> bool
+        def handle_type_mismatch(snapshot_file, path, content, metadata, existing, expression, example)
+          expected = SnapshotContent.normalize(existing.content)
+          caller_line = example.location
+          result = SnapshotMismatchHandler.handle(snapshot_file, path, content, metadata, expected, caller_line: caller_line)
+
+          case result
+          when :updated, :force_passed
+            true
+          else
+            record_failure(
+              "Snapshot type mismatch: snapshot was #{existing.expression} but got #{expression}\n" \
+              "Run `bundle exec insta review` or delete the snapshot file and re-run the test to update it."
+            )
+          end
+        end
+
+        #: (SnapshotFile, Pathname, String, Snapshot::snapshot_metadata, String, String, String?) -> bool
+        def handle_mismatch(snapshot_file, path, content, metadata, expected, label, caller_line = nil)
+          result = SnapshotMismatchHandler.handle(snapshot_file, path, content, metadata, expected,
+                                                  caller_line: caller_line)
+
+          case result
+          when :updated, :force_passed
+            true
+          else
+            @failure_message = SnapshotMismatchHandler.failure_message(expected, content, label, path,
+                                                                       caller_line: caller_line)
+
+            false
+          end
+        end
+
+        #: (String) -> false
+        def record_failure(msg)
+          @failure_message = msg
+
+          false
+        end
+      end
+
+      class MatchInlineSnapshot
+        include ::RSpec::Matchers::Composable
+
+        attr_reader :failure_message #: String?
+
+        #: (String?, ?serializer: Symbol?, ?redact: Hash[String, untyped]?) -> void
+        def initialize(expected = nil, serializer: nil, redact: nil)
+          @expected = expected
+          @serializer = serializer
+          @redact = redact
+          @failure_message = nil
+        end
+
+        #: (untyped) -> bool
+        def matches?(actual)
+          @actual = actual
+
+          actual = Redaction::Applicator.apply(actual, @redact) if @redact
+          serializer_name = @serializer || Insta.configuration.default_serializer
+          serialized = Serializers.serialize(serializer_name, actual)
+          content = SnapshotContent.normalize(serialized)
+
+          location = (caller_locations || []).find { |location| location.path && !location.path.include?("lib/insta") && !location.path.include?("lib/rspec") }
+          return record_failure("Could not determine caller location") unless location
+
+          file = location.path
+          line = location.lineno
+
+          return record_failure("Could not determine source file") unless file
+          return handle_new_inline_snapshot(file, line, content) if @expected.nil?
+
+          expected_normalized = SnapshotContent.normalize(@expected.to_s)
+          return true if content == expected_normalized
+
+          handle_inline_mismatch(file, line, content, expected_normalized)
+        end
+
+        #: () -> String
+        def description
+          "match inline snapshot"
+        end
+
+        private
+
+        #: (String, Integer, String) -> bool
+        def handle_new_inline_snapshot(file, line, content)
+          if Insta.configuration.new_snapshot == :review
+            Inline::PendingStore.add(file: file, line: line, content: content, old_content: "", type: :insert)
+
+            return true if ENV["INSTA_FORCE_PASS"]
+
+            return record_failure("New inline snapshot pending review at #{file}:#{line}\nRun `bundle exec insta review` to accept.")
+          end
+
+          Inline::PendingRegistry.add(file: file, line: line, content: content, type: :insert)
+
+          true
+        end
+
+        #: (String, Integer, String, String) -> bool
+        def handle_inline_mismatch(file, line, content, expected_normalized)
+          mode = Insta.configuration.resolved_update_mode
+
+          case mode
+          when :force
+            Inline::PendingRegistry.add(file: file, line: line, content: content, type: :replace)
+
+            true
+          when :no
+            @failure_message = Diff.failure_message(expected_normalized, content, "inline snapshot at #{file}:#{line}")
+
+            false
+          else
+            Inline::PendingStore.add(file: file, line: line, content: content, old_content: expected_normalized,
+                                     type: :replace)
+
+            if ENV["INSTA_FORCE_PASS"]
+              true
+            else
+              @failure_message = Diff.failure_message(expected_normalized, content,
+                                                      "inline snapshot at #{file}:#{line}")
+
+              false
+            end
+          end
+        end
+
+        #: (String) -> false
+        def record_failure(msg)
+          @failure_message = msg
+
+          false
+        end
+      end
+
+      #: (?String?, ?serializer: Symbol?, ?redact: Hash[String, untyped]?) -> MatchSnapshot
+      def match_snapshot(name = nil, serializer: nil, redact: nil)
+        MatchSnapshot.new(name, serializer: serializer, redact: redact)
+      end
+
+      #: (?String?, ?serializer: Symbol?, ?redact: Hash[String, untyped]?) -> MatchInlineSnapshot
+      def match_inline_snapshot(expected = nil, serializer: nil, redact: nil)
+        MatchInlineSnapshot.new(expected, serializer: serializer, redact: redact)
+      end
+    end
+  end
+end

data/lib/insta/rspec.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "insta"
+require "insta/rspec/matchers"
+require "insta/rspec/hooks"
+
+Insta::RSpec::Hooks.install!

data/lib/insta/serializers/base.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Insta
+  module Serializers
+    class Base
+      #: (untyped) -> String
+      def self.serialize(value)
+        raise NotImplementedError, "#{name} must implement .serialize"
+      end
+    end
+
+    REGISTRY = {} #: Hash[Symbol, singleton(Base)] # rubocop:disable Style/MutableConstant
+
+    #: (Symbol, singleton(Base)) -> void
+    def self.register(name, serializer)
+      REGISTRY[name] = serializer
+    end
+
+    #: (Symbol) -> singleton(Base)
+    def self.fetch(name)
+      REGISTRY.fetch(name) do
+        raise ArgumentError, "Unknown serializer: #{name.inspect}. Available: #{REGISTRY.keys.join(", ")}"
+      end
+    end
+
+    #: (Symbol, untyped) -> String
+    def self.serialize(name, value)
+      fetch(name).serialize(value)
+    end
+  end
+end

data/lib/insta/serializers/inspect.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Insta
+  module Serializers
+    class InspectSerializer < Base
+      #: (untyped) -> String
+      def self.serialize(value)
+        value.inspect
+      end
+    end
+
+    register(:inspect, InspectSerializer)
+  end
+end

data/lib/insta/serializers/json.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Insta
+  module Serializers
+    class JSONSerializer < Base
+      #: (untyped) -> String
+      def self.serialize(value)
+        JSON.pretty_generate(value)
+      end
+    end
+
+    register(:json, JSONSerializer)
+  end
+end

data/lib/insta/serializers/string.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Insta
+  module Serializers
+    class StringSerializer < Base
+      #: (untyped) -> String
+      def self.serialize(value)
+        value.to_s
+      end
+    end
+
+    register(:to_s, StringSerializer)
+  end
+end

data/lib/insta/serializers/yaml.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Insta
+  module Serializers
+    class YAMLSerializer < Base
+      #: (untyped) -> String
+      def self.serialize(value)
+        YAML.dump(value)
+      end
+    end
+
+    register(:yaml, YAMLSerializer)
+  end
+end

data/lib/insta/snapshot.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Insta
+  class Snapshot
+    # @rbs!
+    #   type snapshot_metadata = Hash[String, untyped]
+
+    SEPARATOR = "---" #: String
+
+    attr_reader :content #: String
+    attr_reader :metadata #: snapshot_metadata
+
+    #: (String, ?snapshot_metadata) -> void
+    def initialize(content, metadata = {})
+      @content = content
+      @metadata = metadata
+    end
+
+    #: (String) -> Snapshot
+    def self.parse(raw)
+      raw = raw.to_s
+
+      if raw.start_with?("#{SEPARATOR}\n")
+        parts = raw.split("#{SEPARATOR}\n", 3)
+
+        if parts.length >= 3
+          metadata = begin
+            YAML.safe_load(parts[1], permitted_classes: [Symbol]) || {}
+          rescue Psych::SyntaxError
+            {} #: snapshot_metadata
+          end
+
+          return new(parts[2].chomp.concat("\n"), metadata)
+        end
+      end
+
+      new(raw, {})
+    end
+
+    #: () -> String
+    def serialize
+      return @content if @metadata.empty?
+
+      YAML.dump(@metadata) + "#{SEPARATOR}\n" + @content
+    end
+
+    #: () -> String?
+    def source
+      @metadata["source"]
+    end
+
+    #: () -> String?
+    def input
+      @metadata["input"]
+    end
+
+    #: () -> String?
+    def description
+      @metadata["description"]
+    end
+
+    #: () -> String?
+    def expression
+      @metadata["expression"]
+    end
+
+    #: () -> Hash[String, untyped]?
+    def info
+      @metadata["info"]
+    end
+  end
+end

data/lib/insta/snapshot_content.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Insta
+  module SnapshotContent
+    #: (String) -> String
+    def self.normalize(content)
+      content
+        .gsub("\r\n", "\n")
+        .gsub("\r", "\n")
+        .sub(/\n+\z/, "")
+        .concat("\n")
+    end
+
+    #: (String, Integer) -> String
+    def self.indent(content, level)
+      prefix = " " * level
+      content.each_line.map { |line|
+        if line.strip.empty?
+          "\n"
+        else
+          "#{prefix}#{line}"
+        end
+      }.join
+    end
+
+    #: (String) -> String
+    def self.strip_indent(content)
+      lines = content.split("\n", -1)
+      non_empty = lines.reject { |l| l.strip.empty? }
+      return content if non_empty.empty?
+
+      min_indent = non_empty.map { |l| l.match(/^(\s*)/).to_a[1].to_s.length }.min || 0
+      return content if min_indent.zero?
+
+      lines.map { |l|
+        if l.strip.empty?
+          ""
+        else
+          l[min_indent..] || ""
+        end
+      }.join("\n")
+    end
+  end
+end