rspec-path_matchers 0.1.0 → 0.2.0

data/lib/rspec/path_matchers/options/atime.rb

@@ -1,50 +1,16 @@
 # frozen_string_literal: true
 
+require_relative 'file_stat_base'
+
 module RSpec
   module PathMatchers
     module Options
       # atime: <expected>
-      class Atime
+      class Atime < FileStatBase
         def self.key = :atime
-
-        def self.description(expected)
-          RSpec::PathMatchers.matcher?(expected) ? expected.description : expected.inspect
-        end
-
-        def self.validate_expected(expected, failure_messages)
-          return if expected == NOT_GIVEN ||
-                    expected.is_a?(Time) || expected.is_a?(DateTime) ||
-                    RSpec::PathMatchers.matcher?(expected)
-
-          failure_messages <<
-            "expected `#{key}:` to be a Matcher, Time, or DateTime, but was #{expected.inspect}"
-        end
-
-        # Returns nil if the expected value matches the actual value
-        # @param path [String] the path of the entry to check
-        # @return [String, nil]
-        #
-        def self.match(path, expected, failure_messages)
-          actual = File.stat(path).atime
-          case expected
-          when Time, DateTime then match_time(actual, expected, failure_messages)
-          else                     match_matcher(actual, expected, failure_messages)
-          end
-        end
-
-        # private methods
-
-        private_class_method def self.match_time(actual, expected, failure_messages)
-          return if expected.to_time == actual
-
-          failure_messages << "expected #{key} to be #{expected.to_time.inspect}, but was #{actual.inspect}"
-        end
-
-        private_class_method def self.match_matcher(actual, expected, failure_messages)
-          return if expected.matches?(actual)
-
-          failure_messages << "expected #{key} to #{expected.description}, but was #{actual.inspect}"
-        end
+        def self.stat_attribute = :atime
+        def self.valid_expected_types = [Time, DateTime]
+        def self.normalize_expected_literal(expected) = expected.to_time
       end
     end
   end

data/lib/rspec/path_matchers/options/base.rb

@@ -0,0 +1,296 @@
+# frozen_string_literal: true
+
+require 'rspec/path_matchers/refinements'
+
+module RSpec
+  module PathMatchers
+    module Options
+      # Abstract base class for all option matchers
+      #
+      # @ api public
+      #
+      class Base
+        using RSpec::PathMatchers::Refinements::ArrayRefinements
+
+        # The option key
+        #
+        # For example, if the option key is `:owner`, then it could be used like this:
+        #
+        # ```ruby
+        # expect(path).to be_file(owner: 'alice')
+        # ```
+        #
+        # @abstract
+        #
+        # @return [Symbol] the key for this option matcher
+        #
+        # @api public
+        #
+        def self.key
+          raise NotImplementedError, 'Subclasses must implement Base.key'
+        end
+
+        # Adds to `failures` if the entry at path does not match the expectation
+        #
+        # Entry is a file, directory, or symlink.
+        #
+        # You can assume that entry at path exists and is the expected type (file,
+        # directory, or symlink).
+        #
+        # This is the main method that the matcher (such as be_dir, be_file, or
+        # be_symlink) calls to run its check for an option.
+        #
+        # @param path [String] the path of the entry to check
+        #
+        # @param expected [Object] the expected value to match against the entry
+        #
+        # @param failures [Array<RSpec::PathMatchers::Failure>] the array to append
+        # failure objects to (if any)
+        #
+        # @return [void]
+        #
+        # @api public
+        #
+        def self.match(path, expected, failures)
+          actual = fetch_actual(path, failures)
+          return if actual == FETCH_ERROR
+        rescue NotImplementedError
+          RSpec.configuration.reporter.message(not_supported_message(path))
+        else
+          if RSpec::PathMatchers.matcher?(expected)
+            match_matcher(actual, expected, failures)
+          else
+            match_literal(actual, expected, failures)
+          end
+        end
+
+        # The description of the expectation for this option
+        #
+        # This is used by RSpec when describing the matcher when tests are run in
+        # documentation format or when generating failure messages.
+        #
+        # @param expected [Object] the expected value to match against the entry
+        #
+        # @return [String] the description of the expectation
+        #
+        # @api public
+        #
+        def self.description(expected)
+          RSpec::PathMatchers.matcher?(expected) ? expected.description : expected.inspect
+        end
+
+        # Adds to `errors` if the value of `expected` is not valid for this option type
+        #
+        # The matcher (such as `be_dir`, `be_file`, or `be_symlink`) calls this
+        # method to validate the expected value before running the matcher.
+        #
+        # It checks that the expected value is a RSpec matcher or one of the types
+        # listed in {valid_expected_types}.
+        #
+        # @param expected [Object] the expected value to validate
+        #
+        # @param errors [Array<String>] the array to append validation errors to
+        #
+        # @return [void]
+        #
+        # @api public
+        #
+        def self.validate_expected(expected, errors)
+          return if expected == NOT_GIVEN ||
+                    RSpec::PathMatchers.matcher?(expected) ||
+                    valid_expected_types.any? { |type| expected.is_a?(type) }
+
+          types = ['Matcher', *valid_expected_types.map(&:name)].to_sentence(conjunction: 'or')
+
+          errors << "expected `#{key}:` to be a #{types}, but was #{expected.inspect}"
+        end
+
+        protected
+
+        # The actual value the expectation will be compared with
+        #
+        # Depending on what is being checked, this could be a file's owner, group,
+        # permissions, content, etc.
+        #
+        # Return `FETCH_ERROR` if the value could not be fetched, which will
+        # cause the matcher to fail.
+        #
+        # @param path [String] the path of the entry to check
+        #
+        # @param failures [Array<RSpec::PathMatchers::Failure>] the array to append
+        # failure objects to (if any)
+        #
+        # @return [Object, FETCH_ERROR] the actual value of the entry at path or FETCH_ERROR
+        #
+        # @api protected
+        #
+        private_class_method def self.fetch_actual(path, failures)
+          raise NotImplementedError, 'Subclasses must implement Base.fetch_actual'
+        end
+
+        # The valid types (in addition to an RSpec matcher) for the option value
+        #
+        # For instance, if the option key is `:owner`, then the option value could be
+        # a `String` specifying the owner name as in `be_file(owner: 'alice')`.
+        #
+        # @example specify that only an RSpec matcher is allowed
+        #   def self.valid_expected_types = []
+        #
+        # @example specify that the option value must be an RSpec matcher or a String
+        #   def self.valid_expected_types = [String]
+        #
+        # @example specify that the option value can be a matcher, String, or Regexp
+        #   def self.valid_expected_types = [String, Regexp]
+        #
+        # @return [Array<Class>] an array of valid types for the option value
+        #
+        # @api protected
+        #
+        private_class_method def self.valid_expected_types = []
+
+        # Converts the expected value to a normalized form for comparison
+        #
+        # This is used to ensure that the expected value is in a consistent format
+        # for comparison, such as converting a DateTime object to a Time object.
+        #
+        # This is NOT called if expected is an RSpec matcher.
+        #
+        # @example normalize the expected value to a Time object
+        #   def self.normalize_expected_literal(expected) = expected.to_time
+        #
+        # @param expected [Object] the expected value to normalize
+        #
+        # @return [Object] the normalized expected value
+        #
+        # @api protected
+        #
+        private_class_method def self.normalize_expected_literal(expected) = expected
+
+        # Checks if the actual value matches the expected value
+        #
+        # This is called whenever expected is not an RSpec matcher. By default,
+        # it does a simple equality check using `==`.
+        #
+        # Option subclasses should override this method to provide custom matching
+        # logic, such as when `expected` is a Regexp.
+        #
+        # @example check if the actual value matches a Regexp or a String
+        #   def self.literal_match?(actual, expected)
+        #     expected.is_a?(Regexp) ? expected.match?(actual) : expected == actual
+        #   end
+        #
+        # @param actual [Object] the actual value fetched from the file system
+        #
+        # @param expected [Object] the expected literal value to match against
+        #
+        # @return [Boolean] true if they match, false otherwise
+        #
+        # @api protected
+        #
+        private_class_method def self.literal_match?(actual, expected) = actual == expected
+
+        # Generates a failure message for a literal match failure
+        #
+        # This is used when the actual value does not match the expected value.
+        # It provides a clear message indicating what was expected and what was
+        # actually found.
+        #
+        # Option subclasses should override this method to provide custom failure
+        # messages for specific types of options.
+        #
+        # @example generate a failure message for a literal match failure
+        #  def self.literal_failure_message(actual, expected)
+        #    if expected.is_a?(Regexp)
+        #      "expected #{key} to match #{expected.inspect}, but was #{actual.inspect}"
+        #    else
+        #      "expected #{key} to be #{expected.inspect}, but was #{actual.inspect}"
+        #    end
+        #  end
+        #
+        # @param actual [Object] the actual value fetched from the file system
+        #
+        # @param expected [Object] the expected literal value to match against
+        #
+        # @return [String] the failure message
+        #
+        # @api protected
+        #
+        private_class_method def self.literal_failure_message(actual, expected)
+          "expected #{key} to be #{expected.inspect}, but was #{actual.inspect}"
+        end
+
+        # Add to `failures` if actual value matches the normalized expected value
+        #
+        # This is called when expected is not an RSpec matcher.
+        #
+        # Option subclasses should override this method to provide custom matching
+        # logic or custom failure messages.
+        #
+        # @param actual [Object] the actual value fetched from the file system
+        #
+        # @param expected [Object] the expected literal value to match against
+        #
+        # @param failures [Array<RSpec::PathMatchers::Failure>] the array to append
+        # failure objects to (if any)
+        #
+        # @return [void]
+        #
+        # @api protected
+        #
+        private_class_method def self.match_literal(actual, expected, failures)
+          expected = normalize_expected_literal(expected)
+
+          return if literal_match?(actual, expected)
+
+          message = literal_failure_message(actual, expected)
+          add_failure(message, failures)
+        end
+
+        private_class_method def self.add_failure(message, failures)
+          failures << RSpec::PathMatchers::Failure.new('.', message)
+        end
+
+        # Add to `failures` if actual value matches the normalized expected value
+        #
+        # This is called when expected is an RSpec matcher.
+        #
+        # Option subclasses should override this method to provide custom matching
+        # logic or custom failure messages.
+        #
+        # @param actual [Object] the actual value fetched from the file system
+        #
+        # @param expected [RSpec::Matchers::Matcher] the expected matcher to match against
+        #
+        # @param failures [Array<RSpec::PathMatchers::Failure>] the array to append
+        # failure objects to (if any)
+        #
+        # @return [void]
+        #
+        # @api protected
+        #
+        private_class_method def self.match_matcher(actual, expected, failures)
+          return if expected.matches?(actual)
+
+          message = "expected #{key} to #{expected.description}, but was #{actual.inspect}"
+          add_failure(message, failures)
+        end
+
+        # Warning message for unsupported expectations
+        #
+        # This is used when the platform or file system does not support the
+        # expectation, such as when trying to check file ownership on a platform that
+        # does not support it.
+        #
+        # @param path [String] the path of the entry that the expectation was attempted on
+        #
+        # @return [String] a warning message indicating that the expectation is not supported
+        #
+        # @api private
+        #
+        private_class_method def self.not_supported_message(path)
+          "WARNING: #{key} expectations are not supported for #{path} and will be skipped"
+        end
+      end
+    end
+  end
+end

data/lib/rspec/path_matchers/options/birthtime.rb

@@ -1,59 +1,16 @@
 # frozen_string_literal: true
 
+require_relative 'file_stat_base'
+
 module RSpec
   module PathMatchers
     module Options
       # birthtime: <expected>
-      class Birthtime
+      class Birthtime < FileStatBase
         def self.key = :birthtime
-
-        def self.description(expected)
-          RSpec::PathMatchers.matcher?(expected) ? expected.description : expected.inspect
-        end
-
-        def self.validate_expected(expected, failure_messages)
-          return if expected == NOT_GIVEN ||
-                    expected.is_a?(Time) || expected.is_a?(DateTime) ||
-                    RSpec::PathMatchers.matcher?(expected)
-
-          failure_messages <<
-            "expected `#{key}:` to be a Matcher, Time, or DateTime, but was #{expected.inspect}"
-        end
-
-        # Returns nil if the expected birthtime matches the actual birthtime
-        # @param path [String] the path of the entry to check
-        # @param expected [Object] the expected value to match against the actual value
-        # @param failure_messages [Array<String>] the array to append failure messages to
-        # @return [Void]
-        #
-        def self.match(path, expected, failure_messages) # rubocop:disable Metrics/MethodLength
-          begin
-            actual = File.stat(path).birthtime
-          rescue NotImplementedError
-            message = "WARNING: #{key} expectations are not supported for #{path} and will be skipped"
-            RSpec.configuration.reporter.message(message)
-            return
-          end
-
-          case expected
-          when Time, DateTime then match_time(actual, expected, failure_messages)
-          else                     match_matcher(actual, expected, failure_messages)
-          end
-        end
-
-        # private methods
-
-        private_class_method def self.match_time(actual, expected, failure_messages)
-          return if expected.to_time == actual
-
-          failure_messages << "expected #{key} to be #{expected.to_time.inspect}, but was #{actual.inspect}"
-        end
-
-        private_class_method def self.match_matcher(actual, expected, failure_messages)
-          return if expected.matches?(actual)
-
-          failure_messages << "expected #{key} to #{expected.description}, but was #{actual.inspect}"
-        end
+        def self.stat_attribute = :birthtime
+        def self.valid_expected_types = [Time, DateTime]
+        def self.normalize_expected_literal(expected) = expected.to_time
       end
     end
   end

data/lib/rspec/path_matchers/options/content.rb

@@ -1,58 +1,29 @@
 # frozen_string_literal: true
 
+require_relative 'base'
+
 module RSpec
   module PathMatchers
     module Options
       # content: <expected>
-      class Content
+      class Content < Base
         def self.key = :content
+        def self.fetch_actual(path, _failures) = File.read(path)
+        def self.valid_expected_types = [String, Regexp]
 
-        def self.description(expected)
-          RSpec::PathMatchers.matcher?(expected) ? expected.description : expected.inspect
-        end
-
-        def self.validate_expected(expected, failure_messages)
-          return if expected == NOT_GIVEN ||
-                    expected.is_a?(String) ||
-                    expected.is_a?(Regexp) ||
-                    RSpec::PathMatchers.matcher?(expected)
+        def self.literal_match?(actual, expected)
+          return expected.match?(actual) if expected.is_a?(Regexp)
 
-          failure_messages <<
-            "expected `#{key}:` to be a String, Regexp, or Matcher, but was #{expected.inspect}"
+          super
         end
 
-        # Returns nil if the path matches the expected content
-        # @param path [String] the path of the entry to check
-        # @return [String, nil]
-        #
-        def self.match(path, expected, failure_messages)
-          actual = File.read(path)
-          case expected
-          when String then match_string(actual, expected, failure_messages)
-          when Regexp then match_regexp(actual, expected, failure_messages)
-          else             match_matcher(actual, expected, failure_messages)
+        def self.literal_failure_message(actual, expected)
+          if expected.is_a?(Regexp)
+            "expected content to match #{expected.inspect}, but got #{actual.inspect}"
+          else
+            super
           end
         end
-
-        # private methods
-
-        private_class_method def self.match_string(actual, expected, failure_messages)
-          return if expected == actual
-
-          failure_messages << "expected content to be #{expected.inspect}"
-        end
-
-        private_class_method def self.match_regexp(actual, expected, failure_messages)
-          return if expected.match?(actual)
-
-          failure_messages << "expected content to match #{expected.inspect}"
-        end
-
-        private_class_method def self.match_matcher(actual, expected, failure_messages)
-          return if expected.matches?(actual)
-
-          failure_messages << "expected content to #{expected.description}"
-        end
       end
     end
   end

data/lib/rspec/path_matchers/options/ctime.rb

@@ -1,50 +1,16 @@
 # frozen_string_literal: true
 
+require_relative 'file_stat_base'
+
 module RSpec
   module PathMatchers
     module Options
       # ctime: <expected>
-      class Ctime
+      class Ctime < FileStatBase
         def self.key = :ctime
-
-        def self.description(expected)
-          RSpec::PathMatchers.matcher?(expected) ? expected.description : expected.inspect
-        end
-
-        def self.validate_expected(expected, failure_messages)
-          return if expected == NOT_GIVEN ||
-                    expected.is_a?(Time) || expected.is_a?(DateTime) ||
-                    RSpec::PathMatchers.matcher?(expected)
-
-          failure_messages <<
-            "expected `#{key}:` to be a Matcher, Time, or DateTime, but was #{expected.inspect}"
-        end
-
-        # Returns nil if the path matches the expected size
-        # @param path [String] the path of the entry to check
-        # @return [String, nil]
-        #
-        def self.match(path, expected, failure_messages)
-          actual = File.stat(path).ctime
-          case expected
-          when Time, DateTime then match_time(actual, expected, failure_messages)
-          else                     match_matcher(actual, expected, failure_messages)
-          end
-        end
-
-        # private methods
-
-        private_class_method def self.match_time(actual, expected, failure_messages)
-          return if expected.to_time == actual
-
-          failure_messages << "expected ctime to be #{expected.to_time.inspect}, but was #{actual.inspect}"
-        end
-
-        private_class_method def self.match_matcher(actual, expected, failure_messages)
-          return if expected.matches?(actual)
-
-          failure_messages << "expected ctime to #{expected.description}, but was #{actual.inspect}"
-        end
+        def self.stat_attribute = :ctime
+        def self.valid_expected_types = [Time, DateTime]
+        def self.normalize_expected_literal(expected) = expected.to_time
       end
     end
   end

data/lib/rspec/path_matchers/options/etc_base.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'file_stat_base'
+
+module RSpec
+  module PathMatchers
+    module Options
+      # Base class for options that use the Etc module (owner, group)
+      class EtcBase < FileStatBase
+        def self.valid_expected_types = [String]
+
+        # Overrides the base match method to first check if the platform
+        # supports Etc lookups before proceeding
+        def self.match(path, expected, failures)
+          # Skip the check entirely if the platform doesn't support it
+          return unless supported_platform?
+
+          super
+        end
+
+        private_class_method def self.supported_platform?
+          return true if Etc.respond_to?(etc_method)
+
+          RSpec.configuration.reporter.message(
+            "WARNING: #{key} expectations are not supported on this platform and will be skipped."
+          )
+          false
+        end
+
+        # Fetches the UID/GID from stat and looks up the name via Etc
+        private_class_method def self.fetch_actual(path, _failures)
+          Etc.public_send(etc_method, super).name
+        end
+
+        # Abstract method for subclasses to define :getpwuid or :getgrgid
+        private_class_method def self.etc_method
+          raise NotImplementedError, 'Subclasses must implement EtcBase.etc_method'
+        end
+      end
+    end
+  end
+end

data/lib/rspec/path_matchers/options/file_stat_base.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module RSpec
+  module PathMatchers
+    module Options
+      # Base class for options whose actual value comes from File::Stat
+      class FileStatBase < Base
+        # Implements fetch_actual by calling a specified method on a File::Stat object.
+        #
+        def self.fetch_actual(path, _failures)
+          File.public_send(stat_source_method, path).public_send(stat_attribute)
+        end
+
+        # The method used on a File object to get the stat information
+        #
+        # This should be `:stat` to follow symlinks and `:lstat` for symbolic links.
+        #
+        # The default is `:stat`, which means it will follow symbolic links.
+        #
+        # @return [Symbol]
+        #
+        # @api protected
+        #
+        private_class_method def self.stat_source_method = :stat
+
+        # The name of the File::Stat attribute used to get the actual value
+        #
+        # @example getting file size
+        #   def self.stat_attribute = :size
+        #
+        # @return [Symbol]
+        #
+        # @raise [NotImplementedError] if not implemented in subclass
+        #
+        # @abstract
+        #
+        # @api protected
+        #
+        private_class_method def self.stat_attribute
+          raise NotImplementedError, 'Subclasses must implement FileStatBase.stat_attribute'
+        end
+      end
+    end
+  end
+end