debug_logging 4.0.2 → 4.0.3

data/RUBOCOP.md

@@ -0,0 +1,71 @@
+# RuboCop Usage Guide
+
+## Overview
+
+A tale of two RuboCop plugin gems.
+
+### RuboCop Gradual
+
+This project uses `rubocop_gradual` instead of vanilla RuboCop for code style checking. The `rubocop_gradual` tool allows for gradual adoption of RuboCop rules by tracking violations in a lock file.
+
+### RuboCop LTS
+
+This project uses `rubocop-lts` to ensure, on a best-effort basis, compatibility with Ruby >= 1.9.2.
+RuboCop rules are meticulously configured by the `rubocop-lts` family of gems to ensure that a project is compatible with a specific version of Ruby. See: https://rubocop-lts.gitlab.io for more.
+
+## Checking RuboCop Violations
+
+To check for RuboCop violations in this project, always use:
+
+```bash
+bundle exec rake rubocop_gradual:check
+```
+
+**Do not use** the standard RuboCop commands like:
+- `bundle exec rubocop`
+- `rubocop`
+
+## Understanding the Lock File
+
+The `.rubocop_gradual.lock` file tracks all current RuboCop violations in the project. This allows the team to:
+
+1. Prevent new violations while gradually fixing existing ones
+2. Track progress on code style improvements
+3. Ensure CI builds don't fail due to pre-existing violations
+
+## Common Commands
+
+- **Check violations**
+    - `bundle exec rake rubocop_gradual`
+    - `bundle exec rake rubocop_gradual:check`
+- **(Safe) Autocorrect violations, and update lockfile if no new violations**
+  - `bundle exec rake rubocop_gradual:autocorrect`
+- **Force update the lock file (w/o autocorrect) to match violations present in code**
+  - `bundle exec rake rubocop_gradual:force_update`
+
+## Workflow
+
+1. Before submitting a PR, run `bundle exec rake rubocop_gradual:autocorrect`
+   a. or just the default `bundle exec rake`, as autocorrection is a pre-requisite of the default task.
+2. If there are new violations, either:
+   - Fix them in your code
+   - Run `bundle exec rake rubocop_gradual:force_update` to update the lock file (only for violations you can't fix immediately)
+3. Commit the updated `.rubocop_gradual.lock` file along with your changes
+
+## Never add inline RuboCop disables
+
+Do not add inline `rubocop:disable` / `rubocop:enable` comments anywhere in the codebase (including specs, except when following the few existing `rubocop:disable` patterns for a rule already being disabled elsewhere in the code). We handle exceptions in two supported ways:
+
+- Permanent/structural exceptions: prefer adjusting the RuboCop configuration (e.g., in `.rubocop.yml`) to exclude a rule for a path or file pattern when it makes sense project-wide.
+- Temporary exceptions while improving code: record the current violations in `.rubocop_gradual.lock` via the gradual workflow:
+  - `bundle exec rake rubocop_gradual:autocorrect` (preferred; will autocorrect what it can and update the lock only if no new violations were introduced)
+  - If needed, `bundle exec rake rubocop_gradual:force_update` (as a last resort when you cannot fix the newly reported violations immediately)
+
+In general, treat the rules as guidance to follow; fix violations rather than ignore them. For example, RSpec conventions in this project expect `described_class` to be used in specs that target a specific class under test.
+
+## Benefits of rubocop_gradual
+
+- Allows incremental adoption of code style rules
+- Prevents CI failures due to pre-existing violations
+- Provides a clear record of code style debt
+- Enables focused efforts on improving code quality over time

data/SECURITY.md

@@ -2,15 +2,20 @@
 
 ## Supported Versions
 
-| Version | Supported |
-|---------|-----------|
-| 4.x     | ✅         |
-| 3.x     | ❌         |
-| 2.x     | ❌         |
-| 1.x     | ❌         |
+| Version  | Supported |
+|----------|-----------|
+| 1.latest | ✅         |
 
-## Reporting a Vulnerability
+## Security contact information
 
-Peter Boling is the primary maintainer of this gem. Please find a way
-to [contact him directly](https://railsbling.com/contact) to report the issue. Include as much relevant information as
-possible.
+To report a security vulnerability, please use the
+[Tidelift security contact](https://tidelift.com/security).
+Tidelift will coordinate the fix and disclosure.
+
+## Additional Support
+
+If you are interested in support for versions older than the latest release,
+please consider sponsoring the project / maintainer @ https://liberapay.com/pboling/donate,
+or find other sponsorship links in the [README].
+
+[README]: README.md

data/certs/pboling.pem

@@ -0,0 +1,27 @@
+-----BEGIN CERTIFICATE-----
+MIIEgDCCAuigAwIBAgIBATANBgkqhkiG9w0BAQsFADBDMRUwEwYDVQQDDAxwZXRl
+ci5ib2xpbmcxFTATBgoJkiaJk/IsZAEZFgVnbWFpbDETMBEGCgmSJomT8ixkARkW
+A2NvbTAeFw0yNTA1MDQxNTMzMDlaFw00NTA0MjkxNTMzMDlaMEMxFTATBgNVBAMM
+DHBldGVyLmJvbGluZzEVMBMGCgmSJomT8ixkARkWBWdtYWlsMRMwEQYKCZImiZPy
+LGQBGRYDY29tMIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAruUoo0WA
+uoNuq6puKWYeRYiZekz/nsDeK5x/0IEirzcCEvaHr3Bmz7rjo1I6On3gGKmiZs61
+LRmQ3oxy77ydmkGTXBjruJB+pQEn7UfLSgQ0xa1/X3kdBZt6RmabFlBxnHkoaGY5
+mZuZ5+Z7walmv6sFD9ajhzj+oIgwWfnEHkXYTR8I6VLN7MRRKGMPoZ/yvOmxb2DN
+coEEHWKO9CvgYpW7asIihl/9GMpKiRkcYPm9dGQzZc6uTwom1COfW0+ZOFrDVBuV
+FMQRPswZcY4Wlq0uEBLPU7hxnCL9nKK6Y9IhdDcz1mY6HZ91WImNslOSI0S8hRpj
+yGOWxQIhBT3fqCBlRIqFQBudrnD9jSNpSGsFvbEijd5ns7Z9ZMehXkXDycpGAUj1
+to/5cuTWWw1JqUWrKJYoifnVhtE1o1DZ+LkPtWxHtz5kjDG/zR3MG0Ula0UOavlD
+qbnbcXPBnwXtTFeZ3C+yrWpE4pGnl3yGkZj9SMTlo9qnTMiPmuWKQDatAgMBAAGj
+fzB9MAkGA1UdEwQCMAAwCwYDVR0PBAQDAgSwMB0GA1UdDgQWBBQE8uWvNbPVNRXZ
+HlgPbc2PCzC4bjAhBgNVHREEGjAYgRZwZXRlci5ib2xpbmdAZ21haWwuY29tMCEG
+A1UdEgQaMBiBFnBldGVyLmJvbGluZ0BnbWFpbC5jb20wDQYJKoZIhvcNAQELBQAD
+ggGBAJbnUwfJQFPkBgH9cL7hoBfRtmWiCvdqdjeTmi04u8zVNCUox0A4gT982DE9
+wmuN12LpdajxZONqbXuzZvc+nb0StFwmFYZG6iDwaf4BPywm2e/Vmq0YG45vZXGR
+L8yMDSK1cQXjmA+ZBKOHKWavxP6Vp7lWvjAhz8RFwqF9GuNIdhv9NpnCAWcMZtpm
+GUPyIWw/Cw/2wZp74QzZj6Npx+LdXoLTF1HMSJXZ7/pkxLCsB8m4EFVdb/IrW/0k
+kNSfjtAfBHO8nLGuqQZVH9IBD1i9K6aSs7pT6TW8itXUIlkIUI2tg5YzW6OFfPzq
+QekSkX3lZfY+HTSp/o+YvKkqWLUV7PQ7xh1ZYDtocpaHwgxe/j3bBqHE+CUPH2vA
+0V/FwdTRWcwsjVoOJTrYcff8pBZ8r2MvtAc54xfnnhGFzeRHfcltobgFxkAXdE6p
+DVjBtqT23eugOqQ73umLcYDZkc36vnqGxUBSsXrzY9pzV5gGr2I8YUxMqf6ATrZt
+L9nRqA==
+-----END CERTIFICATE-----

data/lib/debug_logging/argument_printer.rb

@@ -8,7 +8,8 @@ module DebugLogging
     end
 
     def debug_invocation_id_to_s(args: nil, kwargs: nil, start_at: nil, config_proxy: nil)
-      return "" unless (args || kwargs) && config_proxy
+      return "" unless config_proxy
+      return "" unless args || kwargs
 
       if config_proxy.debug_add_invocation_id
         time = start_at ? Util.debug_time(start_at) : Time.now
@@ -63,7 +64,8 @@ module DebugLogging
     end
 
     def debug_signature_to_s(args: nil, kwargs: nil, config_proxy: nil) # rubocop:disable Metrics/CyclomaticComplexity
-      return "" unless (args || kwargs) && config_proxy
+      return "" unless config_proxy
+      return "" unless args || kwargs
 
       printed_args = ""
 
@@ -86,7 +88,7 @@ module DebugLogging
               )
               printed
             else
-              other_args.map(&:inspect).join(", ").tap do |x|
+              debug_args_to_s(other_args).tap do |x|
                 add_other_args_ellipsis = x.length > config_proxy.debug_args_max_length
               end[0..(config_proxy.debug_args_max_length)]
             end
@@ -120,7 +122,7 @@ module DebugLogging
               )
               printed
             else
-              other_args.map(&:inspect).join(", ").tap do |x|
+              debug_args_to_s(other_args).tap do |x|
                 add_other_args_ellipsis = x.length > config_proxy.debug_args_max_length
               end[0..(config_proxy.debug_args_max_length)]
             end
@@ -156,11 +158,11 @@ module DebugLogging
           printed
         elsif args.length == 1 && args[0].is_a?(Hash)
           # handle double splat
-          "**#{args.map(&:inspect).join(", ").tap do |x|
+          "**#{debug_args_to_s(args).tap do |x|
                  add_args_ellipsis = x.length > config_proxy.debug_args_max_length
                end }"[0..(config_proxy.debug_args_max_length)]
         else
-          args.map(&:inspect).join(", ").tap do |x|
+          debug_args_to_s(args).tap do |x|
             add_args_ellipsis = x.length > config_proxy.debug_args_max_length
           end[0..(config_proxy.debug_args_max_length)]
         end
@@ -187,7 +189,7 @@ module DebugLogging
 
       case config_proxy.debug_add_payload
       when true
-        payload.inspect
+        debug_value_to_s(payload)
       else
         printed_payload = ""
         printed, add_payload_ellipsis = debug_safe_proc(
@@ -204,6 +206,25 @@ module DebugLogging
 
     module_function
 
+    def debug_args_to_s(args)
+      args.map { |arg| debug_value_to_s(arg) }.join(", ")
+    end
+
+    def debug_value_to_s(value)
+      case value
+      when Hash
+        "{#{value.map { |key, inner_value| "#{debug_hash_key_to_s(key)}: #{debug_value_to_s(inner_value)}" }.join(", ")}}"
+      when Array
+        "[#{value.map { |inner_value| debug_value_to_s(inner_value) }.join(", ")}]"
+      else
+        value.inspect
+      end
+    end
+
+    def debug_hash_key_to_s(key)
+      key.is_a?(Symbol) ? key.to_s : key.inspect
+    end
+
     def debug_event_name_to_s(decorated_method: nil)
       "#{decorated_method}.log"
     end

data/lib/debug_logging/colorized_string.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module DebugLogging
+  class ColorizedString < String
+    FOREGROUND_CODES = {
+      black: 30,
+      red: 31,
+      green: 32,
+      yellow: 33,
+      blue: 34,
+      magenta: 35,
+      cyan: 36,
+      white: 37,
+      light_black: 90,
+      light_red: 91,
+      light_green: 92,
+      light_yellow: 93,
+      light_blue: 94,
+      light_magenta: 95,
+      light_cyan: 96,
+      light_white: 97,
+      default: 39,
+    }.freeze
+    BACKGROUND_CODES = FOREGROUND_CODES.transform_values { |code| code + 10 }.merge(default: 49).freeze
+    FORMAT_CODES = {
+      bold: 1,
+      italic: 3,
+      underline: 4,
+      blink: 5,
+      reverse_color: 7,
+      conceal: 8,
+      hide: 8,
+      strikethrough: 9,
+      double_underline: 21,
+    }.freeze
+
+    class << self
+      def [](value)
+        new(value.to_s)
+      end
+    end
+
+    def initialize(value, foreground: nil, background: nil, formats: [])
+      @raw = value.to_s
+      @foreground = foreground
+      @background = background
+      @formats = formats.dup
+      super(render)
+    end
+
+    def colorize(color = nil, options = {})
+      options = color if color.is_a?(Hash)
+      foreground = options.fetch(:color, nil) || options.fetch("color", nil)
+      foreground ||= color unless color.is_a?(Hash)
+      background = options.fetch(:background, nil) || options.fetch("background", nil)
+      formats = Array(options[:mode]) + Array(options[:modes])
+
+      self.class.new(
+        @raw,
+        foreground: foreground ? normalized_color(foreground) : @foreground,
+        background: background ? normalized_color(background) : @background,
+        formats: merge_formats(formats),
+      )
+    end
+
+    def colorized?
+      @foreground || @background || @formats.any?
+    end
+
+    def uncolorize
+      @raw.dup
+    end
+
+    FOREGROUND_CODES.each_key do |color|
+      next if color == :default
+
+      define_method(color) do
+        colorize(color)
+      end
+
+      define_method(:"on_#{color}") do
+        colorize(background: color)
+      end
+    end
+    alias_method :on_gray, :on_light_black
+    alias_method :on_grey, :on_light_black
+
+    FORMAT_CODES.each_key do |format|
+      define_method(format) do
+        self.class.new(@raw, foreground: @foreground, background: @background, formats: merge_formats([format]))
+      end
+    end
+
+    private
+
+    def background_code
+      BACKGROUND_CODES.fetch(@background, 49)
+    end
+
+    def foreground_code
+      FOREGROUND_CODES.fetch(@foreground, 39)
+    end
+
+    def style_codes
+      format_codes = @formats.map { |format| FORMAT_CODES.fetch(format) }
+      format_codes = [0] if format_codes.empty?
+      [*format_codes, foreground_code, background_code]
+    end
+
+    def normalized_color(color)
+      color.to_s.tr(" ", "_").downcase.to_sym
+    end
+
+    def merge_formats(formats)
+      normalized_formats = formats.filter_map do |format|
+        normalized = format.to_sym
+        normalized if FORMAT_CODES.key?(normalized)
+      end
+      @formats | normalized_formats
+    end
+
+    def render
+      return @raw.dup unless colorized?
+
+      "\e[#{style_codes.join(";")}m#{@raw}\e[0m"
+    end
+  end
+end
+
+ColorizedString = DebugLogging::ColorizedString unless Object.const_defined?(:ColorizedString)

data/lib/debug_logging/configuration.rb

@@ -1,6 +1,7 @@
 module DebugLogging
   class Configuration
     include Constants
+
     # For reference, log levels as integers mapped to symbols:
     # LEVELS = { 0 => :debug, 1 => :info, 2 => :warn, 3 => :error, 4 => :fatal, 5 => :unknown }
     attr_accessor(*CONFIG_ATTRS)

data/lib/debug_logging/finalize.rb

@@ -2,15 +2,17 @@
 # License: https://creativecommons.org/licenses/by-sa/4.0/
 module DebugLogging
   module Finalize
-    def self.extended(obj)
-      TracePoint.trace(:end) do |t|
-        if obj == t.self
-          if obj.respond_to?(:debug_finalize)
-            obj.debug_finalize
-          else
-            warn("#{obj} does not define a debug_finalize")
+    class << self
+      def extended(obj)
+        TracePoint.trace(:end) do |t|
+          if obj == t.self
+            if obj.respond_to?(:debug_finalize)
+              obj.debug_finalize
+            else
+              warn("#{obj} does not define a debug_finalize")
+            end
+            t.disable
           end
-          t.disable
         end
       end
     end

data/lib/debug_logging/log_subscriber.rb

@@ -7,36 +7,43 @@ module DebugLogging
     extend DebugLogging::ArgumentPrinter
 
     class << self
-      attr_accessor :event
-    end
-    attach_to :log
+      def event
+        @@event
+      end
 
-    EVENT_FORMAT_STRING = "%<name>s (%<duration>.3f secs) start=%<time>s end=%<end>s args=%<args>s payload=%<payload>s"
+      def event=(value)
+        @@event = value
+      end
 
-    def self.log_event(event)
-      @event = event
-      if event.payload && event.payload[:exception_object]
-        exception = event.payload[:exception_object]
-        "#{event.name} [ERROR] : \n#{exception.class} : #{exception.message}\n" + exception.backtrace.join("\n")
-      else
-        format(EVENT_FORMAT_STRING, event_to_format_options(event))
+      def log_event(event)
+        self.event = event
+        if event.payload && event.payload[:exception_object]
+          exception = event.payload[:exception_object]
+          "#{event.name} [ERROR] : \n#{exception.class} : #{exception.message}\n" + exception.backtrace.join("\n")
+        else
+          format(EVENT_FORMAT_STRING, event_to_format_options(event))
+        end
       end
-    end
 
-    # @param [ActiveSupport::Notifications::Event]
-    # @return [Hash]
-    def self.event_to_format_options(event)
-      args = event.payload[:debug_args]
-      config_proxy = event.payload[:config_proxy]
-      payload = event.payload.reject { |k, _| EXCLUDE_FROM_PAYLOAD.include?(k) }
-      {
-        name: event.name,
-        duration: Rational(event.duration, 1000).to_f,
-        time: debug_event_time_to_s(event.time),
-        end: debug_event_time_to_s(event.end),
-        args: debug_signature_to_s(args: args, config_proxy: config_proxy),
-        payload: debug_payload_to_s(payload: payload, config_proxy: config_proxy),
-      }
+      # @param [ActiveSupport::Notifications::Event]
+      # @return [Hash]
+      def event_to_format_options(event)
+        args = event.payload[:debug_args]
+        config_proxy = event.payload[:config_proxy]
+        payload = event.payload.reject { |k, _| EXCLUDE_FROM_PAYLOAD.include?(k) }
+        {
+          name: event.name,
+          duration: Rational(event.duration, 1000).to_f,
+          time: debug_event_time_to_s(event.time),
+          end: debug_event_time_to_s(event.end),
+          args: debug_signature_to_s(args: args, config_proxy: config_proxy),
+          payload: debug_payload_to_s(payload: payload, config_proxy: config_proxy),
+        }
+      end
     end
+
+    attach_to :log
+
+    EVENT_FORMAT_STRING = "%<name>s (%<duration>.3f secs) start=%<time>s end=%<end>s args=%<args>s payload=%<payload>s"
   end
 end

data/lib/debug_logging/version.rb

@@ -1,5 +1,8 @@
+# frozen_string_literal: true
+
 module DebugLogging
   module Version
-    VERSION = "4.0.2"
+    VERSION = "4.0.3"
   end
+  VERSION = Version::VERSION # Traditional Constant Location
 end

data/lib/debug_logging.rb

@@ -1,10 +1,14 @@
+# frozen_string_literal: true
+
 # Std Lib
 require "logger"
 require "digest"
 
 # External gems
 require "version_gem"
-require "colorized_string"
+require_relative "debug_logging/version"
+
+require "debug_logging/colorized_string"
 
 # This gem
 require "debug_logging/constants"
@@ -116,7 +120,13 @@ module DebugLogging
 
   #### CONFIG ####
   class << self
-    attr_accessor :debug_logging_configuration
+    def debug_logging_configuration
+      @@debug_logging_configuration
+    end
+
+    def debug_logging_configuration=(config)
+      @@debug_logging_configuration = config
+    end
   end
 
   module ConfigClassMethods

data/sig/debug_logging/version.rbs

@@ -0,0 +1,6 @@
+module DebugLogging
+  module Version
+    VERSION: String
+  end
+  VERSION: String
+end