do_not_use 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14e53a6088ff672a43401f6f4e666aebd6d0c833a23f77e3424174f4c24793dc
-  data.tar.gz: 6a72c3d43e71eb4057c9fb550414b5ccd874b861efaf62804e2e9246672c29e9
+  metadata.gz: 6896cabb0a8a7e577ab250ce73f0de5c141c3e5132ca2b3f3c8f90b0f5db2ea1
+  data.tar.gz: 54faf975c3653b9ff23821f42128b5433935f7ade489f5654f68d2741d628a09
 SHA512:
-  metadata.gz: 42ba9e3bdd224b6390f225dbb017941f98622c605e1aa201cd452b8268eddab4c795ce841e0326a9f547abb9a4ec70d7de701db15c39b6894e3e60ccd7f57b20
-  data.tar.gz: 1e07bca4b9e532ff1b948b6edf18be6604b4ba63c82b4a476464b796e0c2acc7852737ef93dbdd6e2fe8ea9410d04b50cda56f7409af37164ba0d3f8b8516b6f
+  metadata.gz: dac8bb46aa616d09192d07e2c26cb573e8278cd45ce3f22e94cb4de8fef301986db16c44de6ddc4789edea378bdb5f48ef2fbe7dd9e354569a6bf64e0785ab49
+  data.tar.gz: c8c79e221519af21ff806786da4ecd432eaedb75dda4920cac68692430ed559df37ed0c4f87a89e4b7f3f43c1f65cfc06c6367b4034d5575d2820123d45c171f

data/README.md

@@ -1,28 +1,122 @@
 # DoNotUse
 
-TODO: Delete this and the text below, and describe your gem
-
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/do_not_use`. To experiment with that code, run `bin/console` for an interactive prompt.
+`DoNotUse` gives teams a hard-stop enforcement layer for Ruby APIs that must no longer be used. It provides a DSL to deprecate methods and raise a descriptive error when a deprecated method is used. It also provides configuration options to lets you manage temporary exceptions in one place.
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+Add the gem to your application:
+
+```ruby
+gem "do_not_use"
+```
 
-Install the gem and add to the application's Gemfile by executing:
+Then install it via:
 
-```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```sh
+bundle install
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+You can also install it directly via RubyGems:
 
-```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```sh
+gem install do_not_use
 ```
 
 ## Usage
 
-TODO: Write usage instructions here
+Imagine you have a Ruby class called `User` with a method `raw_data` that stores part of the user’s data in JSON format. You’ve decided to deprecate this method across the codebase, but you don’t have time to remove all its usages immediately. At the same time, you need to proceed with schema and data migrations before fully eliminating it.
+
+In this case, you can mark the method as deprecated and continue with the migrations. Then, using the `DoNotUse` gem, you can gradually identify and remove its usages across the codebase in an iterative manner while preventing the further logic built on top of it.
+
+```ruby
+class User < ApplicationRecord
+  do_not_use :raw_data
+
+  def raw_data
+    JSON.parse(super)
+  end
+end
+
+class MyService
+  def do_something
+    user.raw_data # => raises DoNotUse::Errors::DeprecatedMethodUseError
+  end
+end
+```
+
+With the following configuration, you can temporarily allow `MyService` to access `User#raw_data` method;
+
+```ruby
+DoNotUse.configure do |config|
+  config.exceptions_yaml_path = Rails.root.join("config", "do_not_use.yaml")
+end
+```
+
+```yaml
+# do_not_use.yaml
+User:
+  instance:
+    raw_data:
+      allowed:
+        - ["MyService#do_something"]
+
+```
+
+If someone introduces a new usage of the deprecated method, a `DeprecatedMethodUseError` will be raised. With `DoNotUse`, you can track not only direct usages of deprecated methods, but also any new execution paths that invoke them.
+
+
+For example, imagine someone creates a new service that calls MyService#do_something;
+
+```ruby
+class AnotherService
+  def self.execute
+    my_service_object.do_something
+  end
+
+  private
+
+  def my_service_object
+    MyService.new
+  end
+end
+
+AnotherService.execute # => raises DoNotUse::Errors::DeprecatedMethodUseError
+```
+
+If you want to allow this new usage, you can register its execution path signature;
+
+```yaml
+# do_not_use.yaml
+User:
+  instance:
+    raw_data:
+      allowed:
+        - ["MyService#do_something"]
+  singleton:
+    raw_data:
+      allowed:
+        - ["AnotherService.execute", "MyService#do_something"]
+
+```
+
+You don’t need to manually generate these signatures, they are included in the exception message, so you can copy and register them as allowed usages.
+
+## Configuration
+
+Call `DoNotUse.configure` with a block to configure the gem;
+
+```ruby
+DoNotUse.configure do |config|
+  config.enabled = !Rails.env.production? # A boolean value is required. It's recommended to disable the gem in production environments.
+  config.tracked_paths << Rails.root # The paths where your application logic lives in.
+  config.ignored_paths << Rails.root.join("spec") # The paths which you don't want to track.
+  config.exceptions_yaml_path = Rails.root.join("exceptions.yaml") # The YAML file path where you specify existing usages of the deprecated APIs.
+  config.signature_generators = {
+    Rails.root.join("spec", "models") => Proc.new { |instruction| ... }
+  } # Helps you configure how the instruction signatures are generated for the ignored paths.
+end
+```
+
 
 ## Development
 
@@ -32,7 +126,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/do_not_use. 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/[USERNAME]/do_not_use/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on gitlab at https://gitlab.com/minac/do_not_use. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://gitlab.com/minac/do_not_use/blob/master/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -40,4 +134,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the DoNotUse project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/do_not_use/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the DoNotUse project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://gitlab.com/minac/do_not_use/blob/master/CODE_OF_CONDUCT.md).

data/lib/do_not_use/configuration.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module DoNotUse
+  class Configuration
+    attr_accessor :exceptions_yaml_path, :tracked_paths, :ignored_paths, :enabled, :signature_generators
+
+    def initialize
+      @tracked_paths = []
+      @ignored_paths = []
+      @enabled = true
+      @signature_generators = {}
+    end
+
+    def exceptions
+      @exceptions ||= YAML.load_file(exceptions_yaml_path)
+    end
+
+    def exceptions_yaml_path
+      @exceptions_yaml_path.to_s unless @exceptions_yaml_path.nil?
+    end
+
+    def exceptions_for(module_name, is_singleton, method_name)
+      config_namespace = config_namespace_for(is_singleton)
+
+      exceptions.dig(module_name, config_namespace, method_name, "allowed").to_a
+    end
+
+    private
+
+    def config_namespace_for(is_singleton)
+      is_singleton ? "singleton" : "instance"
+    end
+  end
+end

data/lib/do_not_use/deprecator.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "binding_of_caller"
+
+module DoNotUse
+  class Deprecator
+    IGNORED_INSTRUCTIONS_COUNT = 3
+
+    def initialize(module_name, method_name, is_singleton)
+      @module_name = module_name
+      @method_name = method_name.to_s
+      @is_singleton = is_singleton
+    end
+
+    def deprecation_warning(...)
+      signature_builder = SignatureBuilder.new(callers)
+
+      return if allowed_usage?(signature_builder.signature)
+
+      raise Errors::DeprecatedMethodUseError.new(deprecated_method_signature, signature_builder.signature)
+    end
+
+    private
+
+    attr_reader :module_name, :method_name, :is_singleton
+
+    delegate :configuration, to: DoNotUse, private: true
+    delegate :exceptions, to: :configuration, private: true
+
+    def allowed_usage?(signature)
+      allowed_usages.include?(signature)
+    end
+
+    def allowed_usages
+      @allowed_usages ||= configuration.exceptions_for(module_name, is_singleton, method_name)
+    end
+
+    def deprecated_method_signature
+      @deprecated_method_signature ||= "#{module_name}#{method_type_identifier}#{method_name}"
+    end
+
+    def method_type_identifier
+      is_singleton ? '.' : '#'
+    end
+
+    def callers
+      binding.callers[IGNORED_INSTRUCTIONS_COUNT..]
+    end
+  end
+end

data/lib/do_not_use/errors/deprecated_method_use_error.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module DoNotUse
+  module Errors
+    class DeprecatedMethodUseError < RuntimeError
+      def initialize(method_signature, stacktrace)
+        super <<~ERR
+          `#{method_signature}` method is deprecated and will be removed soon.
+
+          Using this method is strongly discouraged, as it introduces additional technical
+          debt that will need to be addressed later.
+
+          If you believe this usage is essential and provides sufficient value to justify
+          the added technical debt, please update exceptions YAML file with the following
+          stack trace signature. Be aware that this is only a short-term allowance; the
+          technical debt introduced here must be addressed and removed promptly.
+
+          #{stacktrace.inspect}
+        ERR
+      end
+    end
+  end
+end

data/lib/do_not_use/instruction.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module DoNotUse
+  class Instruction
+    def initialize(binding)
+      @binding = binding
+    end
+
+    def receiver
+      singleton? ? binding.receiver : binding.receiver.class
+    end
+
+    def singleton?
+      binding.receiver.is_a?(Module)
+    end
+
+    def method_name
+      binding.eval('__method__')
+    end
+
+    def method_owner
+      return unless frame_type == :method
+
+      meth = singleton? ? receiver.method(method_name) : receiver.instance_method(method_name)
+
+      meth.owner
+    end
+
+    def track?
+      location.track? || (inherited_method? && receiver_location&.track?)
+    end
+
+    def inherited_method_from_ignored_paths?
+      !location.track? && inherited_method?
+    end
+
+    delegate :frame_type, to: :binding
+    delegate :signature_generator, to: :location
+
+    private
+
+    attr_reader :binding
+
+    # The receiver location may differ from the original definition
+    # if the method is inherited.
+    #
+    # It can also be nil when the receiver location cannot be determined,
+    # such as for constants defined internally by the VM in C.
+    def receiver_location
+      return unless receiver_source_path
+
+      Location.new(receiver_source_path.first)
+    end
+
+    def location
+      @location ||= Location.new(source_path)
+    end
+
+    def inherited_method?
+      receiver != method_owner
+    end
+
+    def source_path
+      @source_path ||= binding.source_location.first
+    end
+
+    def receiver_source_path
+      @receiver_source_path ||= Object.const_source_location(receiver.name)
+    end
+  end
+end

data/lib/do_not_use/location.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module DoNotUse
+  class Location
+    def initialize(source_path)
+      @source_path ||= source_path.to_s
+    end
+
+    def track?
+      located_in_tracked_path? && !located_in_ignored_path?
+    end
+
+    # Custom signature generators registered via gem configuration.
+    # These generators are only used for instructions located in ignored paths.
+    #
+    # This allows users to define signatures for those instructions as they see fit.
+    def signature_generator
+      signature_generators.find { |path, _| source_path.starts_with?(path) }&.second
+    end
+
+    private
+
+    attr_reader :source_path
+
+    delegate :configuration, to: DoNotUse, private: true
+    delegate :tracked_paths, :ignored_paths, :signature_generators, to: :configuration, private: true
+
+    def located_in_tracked_path?
+      tracked_paths.any? { |path| source_path.starts_with?(path.to_s) }
+    end
+
+    def located_in_ignored_path?
+      ignored_paths.any? { |path| source_path.starts_with?(path.to_s) }
+    end
+  end
+end

data/lib/do_not_use/patches/module_patch.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/module/deprecation"
+
+module DoNotUse
+  module Patches
+    module ModulePatch
+      def do_not_use(*method_names)
+        return unless DoNotUse.enabled?
+
+        method_names.each do |method_name|
+          deprecator = Deprecator.new(do_not_use_name, method_name, singleton_class?)
+
+          deprecate(method_name, deprecator: deprecator)
+        end
+      end
+
+      def do_not_use_name
+        singleton_class? ? attached_object.name : name
+      end
+    end
+  end
+end
+
+Module.prepend(DoNotUse::Patches::ModulePatch)

data/lib/do_not_use/signature_builder.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module DoNotUse
+  class SignatureBuilder
+    def initialize(bindings)
+      @bindings = bindings
+    end
+
+    def signature
+      @signature ||= signatures.uniq.reverse
+    end
+
+    private
+
+    attr_reader :bindings
+
+    def signatures
+      instructions.each_with_object([]) do |instruction, memo|
+        if instruction.track?
+          signature = Signatures::TrackedCode.new(instruction).signature
+
+          memo << signature if signature
+        else
+          memo << Signatures::IgnoredCode.new(instruction).signature if memo.empty?
+
+          break memo
+        end
+      end
+    end
+
+    def instructions
+      @instructions ||= bindings.map { |binding| Instruction.new(binding) }
+    end
+  end
+end

data/lib/do_not_use/signatures/abstract_code.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module DoNotUse
+  module Signatures
+    class AbstractCode
+      def initialize(instruction)
+        @instruction = instruction
+      end
+
+      private
+
+      attr_reader :instruction
+    end
+  end
+end

data/lib/do_not_use/signatures/ignored_code.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module DoNotUse
+  module Signatures
+    class IgnoredCode < AbstractCode
+      def signature
+        custom_signature || parent_module.name
+      end
+
+      private
+
+      delegate :receiver, :signature_generator, to: :instruction, private: true
+
+      def parent_module
+        receiver.module_parents[-2] || receiver
+      end
+
+      def custom_signature
+        signature_generator&.call(instruction)
+      end
+    end
+  end
+end

data/lib/do_not_use/signatures/tracked_code.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module DoNotUse
+  module Signatures
+    class TrackedCode < AbstractCode
+      def signature
+        return unless klass_name && method_or_block?
+        return inherited_code_signature if inherited_method_from_ignored_paths?
+
+        self_method_signature
+      end
+
+      private
+
+      delegate :frame_type, :singleton?, :inherited_method_from_ignored_paths?, :receiver, :method_owner,
+        to: :instruction, private: true
+
+      # Objects like ActiveRecord models inherit many methods from the library.
+      # As a result, the stack trace of a simple method call may include numerous
+      # private API calls that can change without notice, potentially triggering
+      # new deprecation warnings.
+      #
+      # Additionally, the specific inherited library methods involved are usually
+      # not relevant when registering exceptions.
+      #
+      # For these reasons, we generate a different signature here.
+      def inherited_code_signature
+        "#{receiver} < #{method_owner}"
+      end
+
+      def self_method_signature
+        "#{klass_name}#{separator}#{instruction_name}"
+      end
+
+      def klass_name
+        @klass_name ||= instruction.receiver.name
+      end
+
+      def instruction_name
+        block? ? 'block' : instruction.method_name
+      end
+
+      def separator
+        if block?
+          '&'
+        elsif singleton?
+          '.'
+        else
+          '#'
+        end
+      end
+
+      def method_or_block?
+        frame_type == :method || frame_type == :block
+      end
+
+      def block?
+        frame_type == :block
+      end
+    end
+  end
+end

data/lib/do_not_use/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DoNotUse
-  VERSION = "0.0.0"
+  VERSION = "0.1.0"
 end

data/lib/do_not_use.rb

@@ -1,8 +1,33 @@
 # frozen_string_literal: true
 
+require "active_support/all"
+
 require_relative "do_not_use/version"
+require_relative "do_not_use/configuration"
+require_relative "do_not_use/deprecator"
+require_relative "do_not_use/instruction"
+require_relative "do_not_use/location"
+require_relative "do_not_use/signature_builder"
+require_relative "do_not_use/signatures/abstract_code"
+require_relative "do_not_use/signatures/ignored_code"
+require_relative "do_not_use/signatures/tracked_code"
+require_relative "do_not_use/errors/deprecated_method_use_error"
+require_relative "do_not_use/patches/module_patch"
 
 module DoNotUse
-  class Error < StandardError; end
-  # Your code goes here...
+  def self.enabled?
+    configuration.enabled
+  end
+
+  def self.configure(&block)
+    block.call(configuration)
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.reset_configuration!
+    @configuration = Configuration.new
+  end
 end

metadata

@@ -1,14 +1,48 @@
 --- !ruby/object:Gem::Specification
 name: do_not_use
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors:
 - Mehmet Emin INAC
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: binding_of_caller
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0
 description: Helps capture deprecated method usages.
 email:
 - mehmetemininac@gmail.com
@@ -21,6 +55,16 @@ files:
 - README.md
 - Rakefile
 - lib/do_not_use.rb
+- lib/do_not_use/configuration.rb
+- lib/do_not_use/deprecator.rb
+- lib/do_not_use/errors/deprecated_method_use_error.rb
+- lib/do_not_use/instruction.rb
+- lib/do_not_use/location.rb
+- lib/do_not_use/patches/module_patch.rb
+- lib/do_not_use/signature_builder.rb
+- lib/do_not_use/signatures/abstract_code.rb
+- lib/do_not_use/signatures/ignored_code.rb
+- lib/do_not_use/signatures/tracked_code.rb
 - lib/do_not_use/version.rb
 homepage: https://gitlab.com/minac/do-not-use
 licenses:
@@ -42,7 +86,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.8
+rubygems_version: 4.0.9
 specification_version: 4
 summary: Marks methods/attributes as deprecated and captures their usages.
 test_files: []