insta 0.2.9 → 0.3.0

data/lib/insta/inline/pending_store.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module Insta
+  module Inline
+    # @rbs!
+    #   type pending_store_entry = { file: String, line: Integer, content: String, old_content: String, type: String }
+
+    module PendingStore
+      FILENAME = ".insta-pending-inline"
+
+      @pending = [] #: Array[Inline::pending_store_entry]
+      @mutex = Mutex.new
+
+      #: (file: String, line: Integer, content: String, old_content: String, type: Symbol) -> void
+      def self.add(file:, line:, content:, old_content:, type:)
+        @mutex.synchronize do
+          @pending << {
+            file: file,
+            line: line,
+            content: content,
+            old_content: old_content,
+            type: type.to_s,
+          }
+        end
+      end
+
+      #: () -> void
+      def self.flush!
+        entries = @mutex.synchronize do
+          result = @pending.dup
+          @pending.clear
+
+          result
+        end
+
+        return if entries.empty?
+
+        manifest_path = File.join(Insta.configuration.snapshot_path, FILENAME)
+        existing = if File.exist?(manifest_path)
+                     JSON.parse(File.read(manifest_path), symbolize_names: true)
+                   else
+                     [] #: Array[Inline::pending_store_entry]
+                   end
+
+        merged = merge_entries(existing, entries)
+
+        FileUtils.mkdir_p(File.dirname(manifest_path))
+        File.write(manifest_path, JSON.pretty_generate(merged))
+      end
+
+      #: () -> Array[Inline::pending_store_entry]
+      def self.load
+        manifest_path = File.join(Insta.configuration.snapshot_path, FILENAME)
+        return [] unless File.exist?(manifest_path)
+
+        JSON.parse(File.read(manifest_path), symbolize_names: true)
+      rescue JSON::ParserError
+        []
+      end
+
+      #: () -> void
+      def self.clean!
+        manifest_path = File.join(Insta.configuration.snapshot_path, FILENAME)
+
+        FileUtils.rm_f(manifest_path)
+      end
+
+      #: (Array[Inline::pending_store_entry]) -> void
+      def self.apply!(entries)
+        grouped = entries.group_by { |entry| entry[:file] }
+
+        grouped.each do |file, file_entries|
+          next unless File.exist?(file)
+
+          pending = file_entries.map { |entry|
+            { line: entry[:line], content: entry[:content], type: entry[:type].to_sym }
+          } #: Array[Inline::pending_entry]
+
+          patched = FilePatcher.patch(file, pending)
+
+          FilePatcher.atomic_write(file, patched)
+        end
+      end
+
+      #: (Array[Inline::pending_store_entry]) -> void
+      def self.remove!(entries)
+        current = self.load
+        return if current.empty?
+
+        remaining = current.reject { |existing|
+          entries.any? { |entry|
+            existing[:file] == entry[:file] && existing[:line] == entry[:line]
+          }
+        }
+
+        manifest_path = File.join(Insta.configuration.snapshot_path, FILENAME)
+
+        if remaining.empty?
+          FileUtils.rm_f(manifest_path)
+        else
+          File.write(manifest_path, JSON.pretty_generate(remaining))
+        end
+      end
+
+      #: () -> bool
+      def self.any?
+        @mutex.synchronize { !@pending.empty? }
+      end
+
+      #: () -> Integer
+      def self.size
+        @mutex.synchronize { @pending.length }
+      end
+
+      #: () -> void
+      def self.clear!
+        @mutex.synchronize { @pending.clear }
+      end
+
+      #: (Array[Inline::pending_store_entry], Array[Inline::pending_store_entry]) -> Array[Inline::pending_store_entry]
+      def self.merge_entries(existing, new_entries)
+        result = existing.dup
+
+        new_entries.each do |entry|
+          index = result.index { |e|
+            e[:file] == entry[:file] && e[:line] == entry[:line]
+          }
+
+          if index
+            result[index] = entry
+          else
+            result << entry
+          end
+        end
+
+        result
+      end
+
+      private_class_method :merge_entries
+    end
+  end
+end

data/lib/insta/minitest/assertions.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+module Insta
+  module Minitest
+    # @rbs module-self: Minitest::Test
+    module Assertions
+      #: (
+      #|   untyped,
+      #|   ?name: String?,
+      #|   ?serializer: Symbol?,
+      #|   ?redact: Hash[String, untyped]?,
+      #|   ?input: String?,
+      #|   ?description: String?,
+      #|   ?info: Hash[String, untyped]?,
+      #|   ?options: Hash[Symbol, untyped]?
+      #| ) -> void
+      def assert_snapshot(actual, name: nil, serializer: nil, redact: nil, input: nil, description: nil, info: nil, options: nil)
+        expression = actual.class.name
+        serializer_name = serializer || Insta.configuration.default_serializer
+        actual = Redaction::Applicator.apply(actual, redact) if redact
+        serialized = Serializers.serialize(serializer_name, actual)
+        content = SnapshotContent.normalize(serialized)
+
+        test_class = self.class.name || "Anonymous"
+        test_method = self.name || "unknown"
+
+        path = if name
+                 snapshot_file = SnapshotFile.new(
+                   Insta.configuration.snapshot_path,
+                   test_class,
+                   test_method
+                 )
+                 snapshot_file.named_path(name)
+               else
+                 snapshot_file = _insta_snapshot_file
+                 snapshot_file.path_for(options || {})
+               end
+
+        metadata = build_metadata(
+          test_class,
+          test_method,
+          expression: expression,
+          input: input,
+          description: description,
+          info: info,
+          options: options
+        )
+
+        existing = snapshot_file.read(path)
+
+        unless existing
+          handle_missing_snapshot(snapshot_file, path, content, metadata)
+          return
+        end
+
+        if existing.expression && existing.expression != expression
+          caller_line = find_test_caller
+          handle_type_mismatch(snapshot_file, path, content, metadata, existing, expression, caller_line)
+          return
+        end
+
+        expected = SnapshotContent.normalize(existing.content)
+
+        if content == expected
+          pass
+          return
+        end
+
+        caller_line = find_test_caller
+        handle_snapshot_mismatch(snapshot_file, path, content, metadata, expected, test_class, test_method, caller_line)
+      end
+
+      #: (
+      #|   untyped,
+      #|   ?String?,
+      #|   ?serializer: Symbol?,
+      #|   ?redact: Hash[String, untyped]?
+      #| ) -> void
+      def assert_inline_snapshot(actual, expected = nil, serializer: nil, redact: nil)
+        serializer_name = serializer || Insta.configuration.default_serializer
+        actual = Redaction::Applicator.apply(actual, redact) if redact
+        serialized = Serializers.serialize(serializer_name, actual)
+        content = SnapshotContent.normalize(serialized)
+
+        location = caller_locations(1, 1)&.first
+        return flunk("Could not determine caller location") unless location
+
+        file = location.path
+        line = location.lineno
+
+        return flunk("Could not determine source file") unless file
+
+        if expected.nil?
+          if Insta.configuration.new_snapshot == :review
+            Inline::PendingStore.add(file: file, line: line, content: content, old_content: "", type: :insert)
+
+            if ENV["INSTA_FORCE_PASS"]
+              pass
+            else
+              flunk "New inline snapshot pending review at #{file}:#{line}\nRun `bundle exec insta review` to accept."
+            end
+          else
+            Inline::PendingRegistry.add(file: file, line: line, content: content, type: :insert)
+            pass
+          end
+
+          return
+        end
+
+        expected_normalized = SnapshotContent.normalize(expected.to_s)
+
+        if content == expected_normalized
+          pass
+          return
+        end
+
+        handle_inline_mismatch(file, line, content, expected_normalized)
+      end
+
+      private
+
+      #: () -> SnapshotFile
+      def _insta_snapshot_file
+        @_insta_snapshot_file ||= SnapshotFile.new(
+          Insta.configuration.snapshot_path,
+          self.class.name || "Anonymous",
+          name || "unknown"
+        )
+      end
+
+      #: () -> String
+      def find_test_caller
+        locations = caller_locations
+        return locations&.first.to_s unless locations
+
+        test_location = locations.find { |location|
+          path = location.path
+
+          path && !path.include?("lib/insta") && path.match?(/_test\.rb\z/)
+        }
+
+        (test_location || locations.first).to_s
+      end
+
+      #: (String, String, ?expression: String?, ?input: String?, ?description: String?,
+      #|   ?info: Hash[String, untyped]?, ?options: Hash[Symbol, untyped]?) -> Snapshot::snapshot_metadata
+      def build_metadata(test_class, test_method, expression: nil, input: nil, description: nil, info: nil, options: nil)
+        metadata = { "source" => "#{test_class}##{test_method}" }
+
+        metadata["expression"] = expression if expression
+        metadata["input"] = input if input
+        metadata["description"] = description if description
+        metadata["options"] = options if options && !options.empty?
+        metadata["info"] = info if info
+
+        metadata
+      end
+
+      #: (SnapshotFile, Pathname, String, Snapshot::snapshot_metadata) -> void
+      def handle_missing_snapshot(snapshot_file, path, content, metadata)
+        mode = Insta.configuration.resolved_update_mode
+
+        if mode == :no
+          flunk "Snapshot file does not exist: #{path}\nRun with INSTA_UPDATE=force to create it."
+          return
+        end
+
+        if Insta.configuration.new_snapshot == :review
+          pending_path = snapshot_file.pending_path(path)
+          snapshot_file.write(pending_path, content, metadata)
+          PendingLocations.add(pending_path.to_s, find_test_caller)
+
+          if ENV["INSTA_FORCE_PASS"]
+            pass
+          else
+            flunk "New snapshot pending review: #{path}\nRun `bundle exec insta review` to accept."
+          end
+
+          return
+        end
+
+        snapshot_file.write(path, content, metadata)
+
+        pass
+      end
+
+      #: (SnapshotFile, Pathname, String, Snapshot::snapshot_metadata, Snapshot, String?, String) -> void
+      def handle_type_mismatch(snapshot_file, path, content, metadata, existing, expression, caller_line)
+        expected = SnapshotContent.normalize(existing.content)
+        result = SnapshotMismatchHandler.handle(snapshot_file, path, content, metadata, expected, caller_line: caller_line)
+
+        case result
+        when :updated, :force_passed
+          pass
+        else
+          flunk "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, String) -> void
+      def handle_snapshot_mismatch(snapshot_file, path, content, metadata, expected, test_class, test_method, caller_line)
+        result = SnapshotMismatchHandler.handle(snapshot_file, path, content, metadata, expected, caller_line: caller_line)
+
+        case result
+        when :updated, :force_passed
+          pass
+        else
+          label = "#{test_class}##{test_method}"
+          flunk SnapshotMismatchHandler.failure_message(expected, content, label, path, caller_line: caller_line)
+        end
+      end
+
+      #: (String, Integer, String, String) -> void
+      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)
+          pass
+        when :no
+          flunk Diff.failure_message(
+            expected_normalized,
+            content,
+            "inline snapshot at #{file}:#{line}",
+            nil,
+            "#{file}:#{line}"
+          )
+        else # :auto, :pending
+          Inline::PendingStore.add(
+            file: file,
+            line: line,
+            content: content,
+            old_content: expected_normalized,
+            type: :replace
+          )
+
+          if ENV["INSTA_FORCE_PASS"]
+            pass
+          else
+            flunk Diff.failure_message(
+              expected_normalized,
+              content,
+              "inline snapshot at #{file}:#{line}",
+              nil,
+              "#{file}:#{line}"
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/insta/minitest/lifecycle.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Insta
+  module Minitest
+    module Lifecycle
+      #: (Module) -> void
+      def self.included(base)
+        base.include(Assertions)
+      end
+    end
+  end
+end

data/lib/insta/minitest.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "minitest"
+require "insta"
+require "minitest/insta_plugin"
+
+Minitest::Test.include(Insta::Minitest::Assertions)
+Minitest::Test.include(Insta::Minitest::Lifecycle)

data/lib/insta/pending_locations.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Insta
+  module PendingLocations
+    FILENAME = ".insta-pending-locations"
+
+    @locations = {} #: Hash[String, String]
+    @mutex = Mutex.new
+
+    #: (String, String) -> void
+    def self.add(path, caller_line)
+      @mutex.synchronize do
+        @locations[path] = caller_line
+      end
+    end
+
+    #: () -> void
+    def self.flush!
+      entries = @mutex.synchronize do
+        result = @locations.dup
+        @locations.clear
+        result
+      end
+
+      return if entries.empty?
+
+      manifest_path = File.join(Insta.configuration.snapshot_path, FILENAME)
+      existing = if File.exist?(manifest_path)
+                   JSON.parse(File.read(manifest_path))
+                 else
+                   {} #: Hash[String, String]
+                 end
+
+      existing.merge!(entries)
+
+      FileUtils.mkdir_p(File.dirname(manifest_path))
+      File.write(manifest_path, JSON.pretty_generate(existing))
+    end
+
+    #: () -> Hash[String, String]
+    def self.load
+      manifest_path = File.join(Insta.configuration.snapshot_path, FILENAME)
+      return {} unless File.exist?(manifest_path)
+
+      JSON.parse(File.read(manifest_path))
+    rescue JSON::ParserError
+      {}
+    end
+
+    #: () -> void
+    def self.clean!
+      manifest_path = File.join(Insta.configuration.snapshot_path, FILENAME)
+
+      FileUtils.rm_f(manifest_path)
+    end
+
+    #: () -> void
+    def self.clear!
+      @mutex.synchronize { @locations.clear }
+    end
+  end
+end

data/lib/insta/pending_reporter.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Insta
+  module PendingReporter
+    #: () -> void
+    def self.flush_and_report!
+      Inline::PendingRegistry.flush!
+      Inline::PendingStore.flush!
+      PendingLocations.flush!
+      ConfigManifest.write!
+
+      report_pending_files!
+      report_pending_inline!
+    end
+
+    #: () -> void
+    def self.report_pending_files!
+      snapshot_path = Insta.configuration.snapshot_path
+      extension = Insta.configuration.snapshot_extension
+      pending_files = Dir.glob(File.join(snapshot_path, "**", "*#{extension}.new"))
+
+      return unless pending_files.any?
+
+      count = pending_files.length
+      noun = count == 1 ? "snapshot" : "snapshots"
+      warn "\n\e[33m●\e[0m #{count} pending file #{noun}:\n\n"
+      pending_files.each { |f| warn "  \e[33m›\e[0m #{f}" }
+      warn "\n  \e[36mbundle exec insta review\e[0m\n\n"
+    end
+
+    #: () -> void
+    def self.report_pending_inline!
+      entries = Inline::PendingStore.load
+      return unless entries.any?
+
+      count = entries.length
+      noun = count == 1 ? "snapshot" : "snapshots"
+      warn "\n\e[33m●\e[0m #{count} pending inline #{noun}:\n\n"
+
+      entries.each do |entry|
+        warn "  \e[33m›\e[0m #{entry[:file]}:#{entry[:line]}"
+      end
+
+      warn "\n  \e[36mbundle exec insta review\e[0m\n\n"
+    end
+  end
+end

data/lib/insta/redaction/applicator.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Insta
+  module Redaction
+    class Applicator
+      #: (untyped, Hash[String, untyped]?) -> untyped
+      def self.apply(value, redactions)
+        return value if redactions.nil? || redactions.empty?
+
+        unless value.is_a?(Hash) || value.is_a?(Array)
+          raise ArgumentError,
+                "Redactions require structured data (Hash or Array), got #{value.class}. " \
+                "Use a structured serializer like `serializer: :json` or `serializer: :yaml` with Hash/Array values."
+        end
+
+        duped = deep_dup(value)
+        parsed = redactions.transform_keys { |key| Selector.new(key) }
+
+        walk(duped, [], parsed)
+
+        duped
+      end
+
+      #: (untyped) -> untyped
+      def self.deep_dup(object)
+        case object
+        when Hash
+          hash = {} #: Hash[untyped, untyped]
+          object.each_with_object(hash) { |(key, value), result| result[key] = deep_dup(value) }
+        when Array
+          object.map { |value| deep_dup(value) }
+        else
+          object
+        end
+      end
+
+      #: (untyped, untyped, Hash[Selector, untyped]) -> void
+      def self.walk(node, path, parsed_redactions)
+        case node
+        when Hash
+          node.each_key do |key|
+            child_path = path + [{ type: :key, value: key }]
+            replacement = find_match(child_path, parsed_redactions)
+
+            if replacement
+              node[key] = apply_replacement(node[key], replacement)
+            else
+              walk(node[key], child_path, parsed_redactions)
+            end
+          end
+        when Array
+          node.each_with_index do |_item, index|
+            child_path = path + [{ type: :index, value: index }]
+            replacement = find_match(child_path, parsed_redactions)
+
+            if replacement
+              node[index] = apply_replacement(node[index], replacement)
+            else
+              walk(node[index], child_path, parsed_redactions)
+            end
+          end
+        end
+      end
+
+      #: (untyped, Hash[Selector, untyped]) -> untyped
+      def self.find_match(path, parsed_redactions)
+        parsed_redactions.each do |selector, replacement|
+          return replacement if selector.matches?(path)
+        end
+
+        nil
+      end
+
+      #: (untyped, untyped) -> untyped
+      def self.apply_replacement(value, replacement)
+        case replacement
+        when Proc
+          replacement.call(value)
+        when :sorted
+          value.is_a?(Array) ? value.sort_by(&:to_s) : value
+        else
+          replacement
+        end
+      end
+
+      private_class_method :deep_dup, :walk, :find_match, :apply_replacement
+    end
+  end
+end