rspec-hermetic 0.1.0

data/lib/rspec/hermetic/verdict.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Hermetic
+    class Verdict
+      Result = Struct.new(:pollutions, :warnings, :ignored, keyword_init: true) do
+        def polluted?
+          pollutions.any?
+        end
+
+        def reportable?
+          polluted? || warnings.any?
+        end
+      end
+
+      def initialize(configuration)
+        @configuration = configuration
+      end
+
+      def call(change_set, example_allowances: [])
+        pollutions = []
+        warnings = []
+        ignored = []
+
+        change_set.changes.each do |change|
+          if @configuration.allowlist.allowed?(change, example_allowances)
+            ignored << change
+          elsif @configuration.allowlist.append_only?(change) && change.append_only?
+            warnings << change
+          else
+            pollutions << change
+          end
+        end
+
+        Result.new(pollutions: pollutions, warnings: warnings, ignored: ignored)
+      end
+    end
+  end
+end

data/lib/rspec/hermetic/verify_task.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "json"
+require "rake"
+
+require_relative "../hermetic"
+require_relative "candidate_report"
+
+module RSpec
+  module Hermetic
+    class VerifyTask
+      extend ::Rake::DSL
+
+      DEFAULT_CANDIDATES = "tmp/rspec_hermetic_candidates.json"
+
+      def self.install(name = "hermetic:verify")
+        task_name = name.to_s
+        namespace_name, short_name = task_name.split(":", 2)
+
+        namespace namespace_name do
+          desc "Verify rspec-hermetic polluter/victim candidates by running victim alone and polluter before victim"
+          task short_name, [:candidates] do |_task, args|
+            new(args[:candidates] || ENV["HERMETIC_CANDIDATES"] || DEFAULT_CANDIDATES).run
+          end
+        end
+      end
+
+      def initialize(candidates_path, output: $stdout)
+        @candidates_path = candidates_path
+        @output = output
+      end
+
+      def run
+        candidates.each do |candidate|
+          polluter = candidate.fetch("polluter")
+          victim = candidate.fetch("victim")
+          verify_pair(polluter, victim)
+        end
+      end
+
+      private
+
+      def candidates
+        raise Errno::ENOENT, @candidates_path unless File.exist?(@candidates_path)
+
+        CandidateReport.new(@candidates_path).read
+      rescue Errno::ENOENT
+        raise Error, "candidate file not found: #{@candidates_path}"
+      rescue JSON::ParserError => error
+        raise Error, "invalid candidate JSON #{@candidates_path}: #{error.message}"
+      end
+
+      def verify_pair(polluter, victim)
+        victim_status = run_rspec([victim])
+        pair_status = run_rspec([polluter, victim])
+        manifest = victim_status && !pair_status
+        @output.puts "#{manifest ? "MANIFEST" : "unconfirmed"} #{polluter} -> #{victim}"
+      end
+
+      def run_rspec(locations)
+        system("bundle", "exec", "rspec", "--order", "defined", *locations)
+      end
+    end
+  end
+end

data/lib/rspec/hermetic/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Hermetic
+    VERSION = "0.1.0"
+  end
+end
+
+module Rspec
+  Hermetic = ::RSpec::Hermetic unless const_defined?(:Hermetic, false)
+end

data/lib/rspec/hermetic.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "hermetic/version"
+require_relative "hermetic/configuration"
+require_relative "hermetic/runner"
+
+module RSpec
+  module Hermetic
+    class Error < StandardError; end
+
+    class << self
+      attr_reader :runner
+
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure(rspec_config = nil)
+        yield configuration if block_given?
+        install!(rspec_config) if rspec_config
+        configuration
+      end
+
+      def install!(rspec_config)
+        @installed_config_ids ||= {}
+        return if @installed_config_ids[rspec_config.object_id]
+
+        @runner = Runner.new(configuration)
+        hook = proc { |example| ::RSpec::Hermetic.runner.call(example, self) }
+
+        if rspec_config.respond_to?(:hooks) && rspec_config.hooks.respond_to?(:register)
+          install_outer_around_hook(rspec_config, hook)
+        elsif rspec_config.respond_to?(:prepend_around)
+          rspec_config.prepend_around(:each, &hook)
+        else
+          rspec_config.around(:each, &hook)
+        end
+
+        @installed_config_ids[rspec_config.object_id] = true
+      end
+
+      private
+
+      def install_outer_around_hook(rspec_config, hook)
+        hook.__id__
+        if rspec_config.respond_to?(:add_hook_to_existing_matching_groups, true)
+          rspec_config.send(:add_hook_to_existing_matching_groups, [], :each) do |group|
+            group.hooks.register(:append, :around, :each, &hook)
+          end
+        end
+        rspec_config.hooks.register(:append, :around, :each, &hook)
+      end
+    end
+  end
+end
+
+module Rspec
+  Hermetic = ::RSpec::Hermetic unless const_defined?(:Hermetic, false)
+end

data/sig/rspec/hermetic.rbs

@@ -0,0 +1,112 @@
+module RSpec
+  module Hermetic
+    VERSION: String
+
+    class Error < StandardError
+    end
+
+    def self.configuration: () -> Configuration
+    def self.configure: (?untyped rspec_config) { (Configuration) -> untyped } -> Configuration
+    def self.install!: (untyped rspec_config) -> untyped
+    def self.configure_minitest: () { (Configuration) -> untyped } -> Configuration
+
+    class Configuration
+      attr_accessor probes: Array[Symbol]
+      attr_accessor on_pollution: Symbol
+      attr_accessor root_path: String
+      attr_accessor constant_namespaces: Array[untyped]
+      attr_accessor constant_exclude_patterns: Array[untyped]
+      attr_accessor constants_max_depth: Integer
+      attr_accessor constants_max_entries: Integer
+      attr_accessor constants_graph: bool
+      attr_accessor constants_graph_max_depth: Integer
+      attr_accessor constants_graph_max_nodes: Integer
+      attr_accessor filesystem_paths: Array[String]
+      attr_accessor filesystem_exclude_patterns: Array[String]
+      attr_accessor filesystem_content_hash_bytes: Integer
+      attr_accessor filesystem_max_entries: Integer
+      attr_accessor filesystem_max_depth: Integer?
+      attr_accessor forensic: bool
+      attr_accessor randomness_seed_probe: bool
+      attr_accessor resource_process_probe: bool
+      attr_accessor rails_config_paths: Array[String]
+      attr_accessor probe_sampling: Hash[Symbol, Integer]
+      attr_accessor report_probe_errors: bool
+      attr_accessor candidate_report_path: String?
+      attr_accessor auto_reset: untyped
+      attr_accessor track_resource_origins: bool
+
+      attr_reader allowlist: Allowlist
+
+      def initialize: () -> void
+      def allow: () { (Allowlist) -> untyped } -> untyped
+      def probe_interval: (Symbol) -> Integer
+      def auto_reset_probe?: (Symbol) -> bool
+    end
+
+    class Allowlist
+      def env: (*untyped patterns) -> untyped
+      def path: (*untyped patterns) -> untyped
+      def constant: (*untyped patterns) -> untyped
+      def append_only: (*untyped patterns) -> untyped
+    end
+
+    class CandidateReport
+      def initialize: (String path) -> void
+      def append: (Hash[String, untyped] candidate) -> untyped
+      def read: () -> Array[Hash[String, untyped]]
+    end
+
+    class VerifyTask
+      DEFAULT_CANDIDATES: String
+
+      def self.install: (?String name) -> untyped
+      def initialize: (String candidates_path, ?output: untyped) -> void
+      def run: () -> untyped
+    end
+
+    class Evaluation
+      def initialize: (?output_path: String) -> void
+      def run: () -> Hash[String, untyped]
+    end
+
+    class EvaluationTask
+      DEFAULT_OUTPUT: String
+
+      def self.install: (?String name) -> untyped
+      def self.install_corpus: (?String name) -> untyped
+    end
+
+    class CorpusEvaluation
+      def initialize: (
+        output_path: String,
+        ?project_path: String,
+        ?baseline_command: String?,
+        hermetic_command: String,
+        ?candidate_report_path: String,
+        ?judgments_path: String?
+      ) -> void
+
+      def run: () -> Hash[String, untyped]
+    end
+
+    class Restorer
+      def initialize: (Configuration configuration) -> void
+      def restore: (untyped change_set, untyped before_snapshot, ?context: untyped) -> untyped
+    end
+
+    module ResourceTracker
+      ORIGIN_IVAR: Symbol
+
+      def self.install!: () -> untyped
+      def self.start!: () -> untyped
+      def self.stop!: () -> untyped
+      def self.annotate: (untyped resource) -> untyped
+      def self.origin_for: (untyped resource) -> untyped
+    end
+  end
+end
+
+module Rspec
+  Hermetic: singleton(RSpec::Hermetic)
+end

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification
+name: rspec-hermetic
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.10'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.10'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
+description: rspec-hermetic snapshots process state around each example and reports
+  leaked global state or resources.
+email:
+- t.yudai92@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/rspec/hermetic.rb
+- lib/rspec/hermetic/allowlist.rb
+- lib/rspec/hermetic/candidate_report.rb
+- lib/rspec/hermetic/change.rb
+- lib/rspec/hermetic/configuration.rb
+- lib/rspec/hermetic/corpus_evaluation.rb
+- lib/rspec/hermetic/diff.rb
+- lib/rspec/hermetic/evaluation.rb
+- lib/rspec/hermetic/evaluation_task.rb
+- lib/rspec/hermetic/forensic.rb
+- lib/rspec/hermetic/formatter.rb
+- lib/rspec/hermetic/minitest.rb
+- lib/rspec/hermetic/probe.rb
+- lib/rspec/hermetic/probe/base.rb
+- lib/rspec/hermetic/probe/constants.rb
+- lib/rspec/hermetic/probe/env.rb
+- lib/rspec/hermetic/probe/filesystem.rb
+- lib/rspec/hermetic/probe/globals.rb
+- lib/rspec/hermetic/probe/rails.rb
+- lib/rspec/hermetic/probe/randomness.rb
+- lib/rspec/hermetic/probe/resources.rb
+- lib/rspec/hermetic/probe/ruby_runtime.rb
+- lib/rspec/hermetic/probe/time.rb
+- lib/rspec/hermetic/resource_tracker.rb
+- lib/rspec/hermetic/restorer.rb
+- lib/rspec/hermetic/runner.rb
+- lib/rspec/hermetic/snapshot.rb
+- lib/rspec/hermetic/stable_value.rb
+- lib/rspec/hermetic/verdict.rb
+- lib/rspec/hermetic/verify_task.rb
+- lib/rspec/hermetic/version.rb
+- sig/rspec/hermetic.rbs
+homepage: https://github.com/ydah/rspec-hermetic
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/ydah/rspec-hermetic
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Detect RSpec examples that leave shared state polluted.
+test_files: []