purist 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0eb6e6c4be218cd0e3d351a6767860f6a5da8952f15e3ee740aec9ff1c28882b
+  data.tar.gz: 7a539fd18fc3361183007c48daca2a226267a1b93189a16cdb23bfff4ef7bc6b
+SHA512:
+  metadata.gz: d9e7453e526c7db2f523e70a9c6c90cc11bfc2045aeea49ff0d6e921c76127f55c76f6ba06ebaad684f15bd7b6574312a4cc781d013763c43ae042c3128a35b8
+  data.tar.gz: 3f4a5994752f455d13831dcdf5317f6a8b71c1748f2c4a38857199250ba1674337388fd3399ae3b4da1221ab39819b1dc90ee1243106bf3b192de650c911c982

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 viralpraxis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,117 @@
+# Purst
+
+Purist is a tool designed to help detecting impure ruby code in runtime.
+
+Ruby's stdlib and corelibs include a bunch of impure methods, including
+
+1. randomization: `Kernel.rand`, `Random.rand`, `SecureRandom.hex` and so on
+
+2. IO-related methods like `Kernel.readline` or `IO.popen`
+
+3. specialized side-effects like `Kernel.fork` or `Kernel.syscall`
+
+Purist hooks into ruby's `tracepoint` API to detect any invocation of these methods.
+You can see the full list of target methods in `configuration.rb` source file.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add purist
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install purist
+
+## Usage
+
+To check if your code is pure, simply pass it into `Purist.trace` method:
+
+```ruby
+Purist.trace { 3 * 3 } # 9
+```
+
+If provided block is impure, an exception will be raised:
+
+```ruby
+irb(main):001> Purist.trace { p "I'm impure" }
+gems/purist/lib/purist/handler.rb:23:in `call': {:path=>"(irb)", :lineno=>1, :module_name=>Kernel, :method_name=>:p} (Purist::Errors::PurityViolationError)
+```
+
+You can retrieve exception details like this:
+
+```ruby
+exception = Purist.trace { p 1 } rescue $!
+
+p exception.trace_point
+
+{
+  :path => ".../zeitwerk-2.6.13/lib/zeitwerk/kernel.rb",
+  :lineno => 23,
+  :module_name => Kernel,
+  :method_name => :require,
+  :backtrace => [...]
+}
+```
+
+### RSpec integration
+
+Purist comes with built-in `RSpec` integration. To enable it, add `require "purist/integrations/rspec"` to your
+`spec_helper.rb` and manually include `Purist::Integrations::RSpec::Matchers`:
+
+```ruby
+require "purist/integrations/rspec"
+
+...
+
+RSpec.configure do |config|
+  ...
+  config.include Purist::Integrations::RSpec::Matchers
+  ...
+end
+```
+
+And not `be_pure` and `be_impure` matchers are available:
+
+```ruby
+expect { Module.new }.to be_pure
+expect { User.where(name: :john) }.to be_impure
+```
+
+### Caveats
+
+1. Passing `Purist.trace` check does not mean your function is totally pure, for instance
+
+```ruby
+def foo(n)
+  if n > 0 # pure branch
+    n.succ
+  else # impure branch
+    p n
+  end
+end
+
+Purist.trace { foo(3) } # 4
+```
+
+2. Ruby stdlib/corelib is quite big, I'm pretty sure some impure functions are missing from the list.
+
+3. Obviously, Purist is unable to detect anything within 3rd-party C extensions.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/viralpraxis/purist. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/viralpraxis/purist/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Purist project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/viralpraxis/purist/blob/main/CODE_OF_CONDUCT.md).

data/lib/purist/configuration.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require 'singleton'
+
+module Purist
+  class Configuration # rubocop:disable Metrics/ClassLength
+    include Singleton
+
+    Subject = Class.new do
+      def self.from_module(module_name:, method_names:, with_singleton_class: false)
+        targets = {}
+
+        method_names.each do |method_name|
+          targets[[module_name, method_name]] = true
+          targets[[module_name.singleton_class, method_name]] = true if with_singleton_class
+        end
+
+        targets
+      end
+    end
+
+    STDLIB_RANDOM_CLASS =
+      if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('3.0.0')
+        Random::Base
+      else
+        Random
+      end
+
+    TRACE_TARGETS = {
+      **Subject.from_module(
+        module_name: Kernel,
+        with_singleton_class: true,
+        method_names: %i[
+          abort
+          at_exit
+          exit
+          exit!
+
+          pp
+          gets
+          open
+          p
+          print
+          printf
+          putc
+          puts
+          readline
+          readlines
+          select
+
+          set_trace_func
+          trace_var
+          untrace_var
+
+          `
+          exec
+          fork
+          spawn
+          system
+
+          load
+          require
+          require_relative
+
+          rand
+          srand
+
+          sleep
+          sprintf
+          syscall
+          trap
+
+          autoload
+          warn
+        ]
+      ),
+      **Subject.from_module(
+        module_name: IO.singleton_class,
+        method_names: %i[
+          new
+          for_fd
+          open
+          pipe
+          popen
+          select
+
+          binread
+          read
+          readlines
+
+          binwrite
+          write
+
+          foreach
+
+          copy_stream
+          try_convert
+
+          sysopen
+        ]
+      ),
+      **Subject.from_module(
+        module_name: IO,
+        method_names: %i[
+          getbyte
+          getc
+          gets
+          pread
+          read
+          read_nonblock
+          readbyte
+          readchar
+          readline
+          readlines
+          readpartial
+
+          print
+          printf
+          putc
+          puts
+          pwrite
+          write
+          write_nonblock
+
+          pos
+          pos=
+          ropen
+          rewind
+          seek
+
+          each
+          each_byte
+          each_char
+          each_codepoint
+
+          autoclose=
+          binmode
+          close
+          close_on_exec
+          close_read
+          close_write
+          set_encoding
+          set_encoding_by_bom
+          sync=
+
+          fdatasync
+          flush
+          fsync
+          ungetbyte
+          ungetc
+
+          advise
+          fcntl
+          ioctl
+          sysread
+          sysseek
+          syswrite
+        ]
+      ),
+      **Subject.from_module(
+        module_name: Random.singleton_class,
+        with_singleton_class: true,
+        method_names: %i[
+          bytes
+          rand
+          srand
+          urandom
+        ]
+      ),
+      **Subject.from_module(
+        module_name: STDLIB_RANDOM_CLASS,
+        method_names: %i[
+          bytes
+          rand
+        ]
+      )
+    }.freeze
+
+    def trace_targets
+      TRACE_TARGETS
+    end
+
+    def action_on_purity_violation
+      :raise
+    end
+  end
+end

data/lib/purist/errors.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Purist
+  module Errors
+    class Error < StandardError; end
+
+    class PurityViolationError < Error
+      attr_reader :trace_point
+
+      def initialize(message = nil, trace_point:)
+        @trace_point = trace_point
+
+        super(message || trace_point.reject { |key| key == :backtrace }.inspect)
+      end
+    end
+  end
+end

data/lib/purist/handler.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'trace_point_slice'
+
+module Purist
+  module Handler
+    def self.build(mode)
+      case mode&.to_sym
+      when :raise then Raise.new
+      when nil then nil
+      else raise ArgumentError, "Unexpected mode `#{mode.inspect}`"
+      end
+    end
+
+    class Base; end # rubocop:disable Lint/EmptyClass
+
+    class Raise < Base
+      def call(trace_point)
+        raise Purist::Errors::PurityViolationError.new(
+          trace_point: TracePointSlice.call(trace_point)
+        )
+      end
+    end
+  end
+end

data/lib/purist/integrations/rspec/be_impure.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+RSpec::Matchers.define_negated_matcher :be_impure, :be_pure

data/lib/purist/integrations/rspec/be_pure.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Purist
+  module Integrations
+    module RSpec
+      class BePure
+        def supports_value_expectations?
+          false
+        end
+
+        def supports_block_expectations?
+          true
+        end
+
+        def matches?(block)
+          Purist.trace { block.call }
+
+          true
+        rescue Purist::Errors::PurityViolationError => e
+          @purist_exception = e
+
+          false
+        end
+
+        def description
+          'block to be pure'
+        end
+
+        def description_when_negated
+          'block to be impure'
+        end
+
+        def failure_message
+          "expected #{description}, detected impure #{purist_exception.trace_point.inspect}"
+        end
+
+        def failure_message_when_negated
+          "expected #{description_when_negated}, but no side-effects were detected"
+        end
+
+        private
+
+        attr_reader :purist_exception
+      end
+    end
+  end
+end

data/lib/purist/integrations/rspec/matchers.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'be_pure'
+require_relative 'be_impure'
+
+module Purist
+  module Integrations
+    module RSpec
+      module Matchers
+        def be_pure
+          BePure.new
+        end
+      end
+    end
+  end
+end

data/lib/purist/integrations/rspec.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative 'rspec/matchers'
+require 'rspec/matchers'

data/lib/purist/matcher.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Purist
+  class Matcher
+    def self.match?(specification, trace_point)
+      specification.key? [trace_point.defined_class, trace_point.callee_id]
+    end
+  end
+end

data/lib/purist/trace_point_slice.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Purist
+  class TracePointSlice
+    def self.call(trace_point)
+      {
+        path: trace_point.path,
+        lineno: trace_point.lineno,
+        module_name: trace_point.defined_class,
+        method_name: trace_point.callee_id,
+        backtrace: trace_point.binding.send(:caller)
+      }
+    end
+  end
+end

data/lib/purist/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Purist
+  VERSION = '1.0.0'
+end

data/lib/purist.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative 'purist/configuration'
+require_relative 'purist/errors'
+require_relative 'purist/handler'
+require_relative 'purist/matcher'
+require_relative 'purist/version'
+
+module Purist
+  TRACE_POINT_TYPES = %i[call c_call].freeze
+  TRACE_HANDLER = proc do |trace_point|
+    next unless Purist::Matcher.match?(configuration.trace_targets, trace_point)
+
+    Purist.handler.call(trace_point)
+  end
+
+  def self.trace(&block)
+    return unless block
+
+    TracePoint
+      .new(*TRACE_POINT_TYPES, &TRACE_HANDLER)
+      .enable(&block)
+  end
+
+  def self.handler
+    @handler ||= Purist::Handler.build(configuration.action_on_purity_violation)
+  end
+
+  def self.configuration
+    @configuration ||= Purist::Configuration.instance
+  end
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: purist
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Yaroslav Kurbatov
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2024-03-10 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Automatic runtime impure ruby methods invocation detection by tracing predifined
+  Ruby stdlib and core libs methods via `tracepoint` API
+email: iaroslav2k@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+- LICENSE.txt
+files:
+- LICENSE.txt
+- README.md
+- lib/purist.rb
+- lib/purist/configuration.rb
+- lib/purist/errors.rb
+- lib/purist/handler.rb
+- lib/purist/integrations/rspec.rb
+- lib/purist/integrations/rspec/be_impure.rb
+- lib/purist/integrations/rspec/be_pure.rb
+- lib/purist/integrations/rspec/matchers.rb
+- lib/purist/matcher.rb
+- lib/purist/trace_point_slice.rb
+- lib/purist/version.rb
+homepage: https://github.com/viralpraxis/purist
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/viralpraxis/purist
+  source_code_uri: https://github.com/viralpraxis/purist/tree/main
+  changelog_uri: https://github.com/viralpraxis/purist/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key: 
+specification_version: 4
+summary: Automatic runtime impure ruby methods invocation detection
+test_files: []