rspec-path_matchers 0.1.0 → 0.2.0

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

@@ -4,41 +4,134 @@ module RSpec
   module PathMatchers
     module Matchers
       # The base class for matchers
+      #
+      # Implements the [RSpec matcher
+      # protocol](https://rspec.info/documentation/3.13/rspec-expectations/RSpec/Matchers/MatcherProtocol.html)
+      # for value expectations including:
+      #
+      # - `#matches?(base_path)` - checks if the matcher matches the given base_path
+      # - `#failure_message` - returns a human-readable failure message
+      # - `#actual` - returns the actual value that was matched against
+      # - `#expected` - returns the expected value that was matched against
+      # - `#description` - returns a human-readable description of the matcher
+      # - `#does_not_match?(base_path)` - checks if the matcher does not match the given base_path
+      # - `#failure_message_when_negated` - returns a human-readable failure message for negative matches
+      #
       class Base # rubocop:disable Metrics/ClassLength
-        def initialize(name, **options_hash)
+        # Create a new matcher instance
+        #
+        # Subclasses may override this to provide additional arguments or options.
+        # They should call `super` to ensure the base class is initialized correctly.
+        #
+        # @param entry_name [String] The name of the entry to match against
+        #
+        #   - If entry_name is empty, the matcher will match against the base_path
+        #     directly (this is the path passed to `matches?` or `does_not_match?`).
+        #   - If entry_name is NOT empty, the matcher will match against
+        #     File.join(base_path, entry_name)
+        #
+        # @param matcher_name [Symbol] The matcher name (e.g. :have_dir, :have_file,
+        #   etc.) to use in descriptions and messages
+        #
+        # @param options_hash [Hash] Options for the matcher passed to the options
+        #   factory to get an options object
+        #
+        def initialize(entry_name, matcher_name:, **options_hash)
           super()
-          @name = name.to_s
+          @entry_name = entry_name.to_s
+          @matcher_name = matcher_name
           @options = options_factory(*option_keys, **options_hash)
+          @failures = []
         end
 
-        attr_reader :name, :options, :base_path, :path
+        # @attribute [r] options
+        #
+        # The matcher options loaded from the options_hash passed to the initializer
+        #
+        # @return [Object] A Data object containing the options
+        #
+        attr_reader :options
+
+        # @attribute [r] base_path
+        #
+        # The base path against which the matcher is applied
+        #
+        # @return [String]
+        #
+        attr_reader :base_path
+
+        # @attribute [r] path
+        #
+        # The full path to the entry being matched against
+        #
+        # @return [String]
+        #
+        attr_reader :path
+
+        # @attribute [r] matcher_name
+        #
+        # The name of this matcher, used for descriptions and messages
+        #
+        # @return [Symbol] The matcher name (e.g. :have_dir, :have_file, etc.)
+        #
+        attr_reader :matcher_name
+
+        # @attribute [r] failures
+        #
+        # An array of failures that describe why the matcher did not match the actual
+        # value
+        #
+        # Only populated after `matches?` or `execute_match` is called
+        #
+        # @return [Array<RSpec::PathMatchers::Failure>]
+        #
+        attr_reader :failures
+
+        # @attribute [r] entry_name
+        #
+        # The name of the entry being matched against or an empty String
+        #
+        # If `entry_name` is empty, the matcher will match against the base_path
+        # directly. If `entry_name` is not empty, the matcher will match against
+        # `File.join(base_path, entry_name)`.
+        #
+        # @return [String]
+        #
+        def entry_name
+          @entry_name || base_path.basename
+        end
 
         # A human-readable description of the matcher's expectation
         #
-        # This is used by RSpec to build the failure message when an `expect(...).to`
-        # expectation is not met. For example, if a test asserts `expect(path).to
-        # have_file("foo")` and the file does not exist, the failure message will
-        # include the output of this method: "expected to have file \"foo\"".
+        # This description is used by RSpec formatters (e.g., `--format
+        # documentation`) to provide output about the specification itself. It is NOT
+        # used to build the detailed failure message when an expectation fails.
+        #
+        # Subclasses can override this method to add to or provide a more specific
+        # description based on the entry type, options, or other factors.
         #
-        # @return [String] A description of the matcher
+        # @return [String]
         #
         def description
-          desc = "have #{entry_type} #{name.inspect}"
+          desc = (@entry_name.empty? ? "be a #{entry_type}" : "have #{entry_type} #{entry_name.inspect}")
           options_description = build_options_description
           desc += " with #{options_description}" unless options_description.empty?
           desc
         end
 
-        def failure_messages
-          @failure_messages ||= []
-        end
-
+        # Returns `true` if the matcher matches the actual value
+        #
+        # If `false` is returned, the `failures` array will be populated with
+        # human-readable error messages that describe why the match failed.
+        #
+        # @param base_path [Object] The base_path together with entry_name determine the actual value
+        #
+        # @return [Boolean] `true` if the matcher matches, `false` otherwise
+        #
+        # @raise [ArgumentError] if there are errors in the matcher or its options
+        #
         def matches?(base_path)
-          # It is important to reset failure_messages in case this matcher instance
-          # is reused
-          @failure_messages = []
-
-          # Phase 1: Validate all options recursively for syntax errors
+          # Phase 1: Validate all options for syntax errors
           validation_errors = []
           collect_validation_errors(validation_errors)
           raise ArgumentError, validation_errors.join(', ') if validation_errors.any?
@@ -47,24 +140,31 @@ module RSpec
           execute_match(base_path)
         end
 
-        def collect_negative_validation_errors(errors)
-          errors << "The matcher `not_to #{matcher_name}(...)` cannot be given options" if options.any_given?
+        def failure_message
+          header = "#{path} was not as expected:"
+          grouped_failures = failures.group_by(&:relative_path)
+
+          messages = grouped_failures.map do |relative_path, failures_for_path|
+            format_failure_group(relative_path, failures_for_path)
+          end
+
+          "#{header}\n#{messages.join("\n")}"
         end
 
         # This method is called by RSpec for `expect(...).not_to have_...`
         def does_not_match?(base_path) # rubocop:disable Naming/PredicatePrefix
-          # 1. Validate that no options were passed to the negative matcher.
+          # Phase 1: Validate all options for syntax errors (in this case options are not allowed)
           validation_errors = []
           collect_negative_validation_errors(validation_errors)
           raise ArgumentError, validation_errors.join(', ') if validation_errors.any?
 
           @base_path = base_path.to_s
-          @path = File.join(base_path, name)
+          @path = @entry_name.empty? ? base_path : File.join(base_path, entry_name)
 
-          # 2. A negative match SUCCEEDS if the entry of the specified type does NOT exist.
-          #    We delegate the type-specific check to the subclass.
-          #    The method returns `true` if the entry is NOT of the correct type (pass),
-          #    and `false` if it IS of the correct type (fail).
+          # Phase 2: Execute the actual match logic
+          #
+          # A negative match SUCCEEDS if the entry of the specified type does NOT
+          # exist. We delegate the type-specific check to the subclass.
           !correct_type?
         end
 
@@ -73,12 +173,19 @@ module RSpec
           "expected it not to be a #{entry_type}"
         end
 
-        # Recursively gathers all syntax/validation errors
+        protected
+
+        # Add to `errors` if the matcher is not defined correctly
+        #
+        # Subclasses may override this method to provide additional checking. For
+        # instance, BeDirectory extends this to add validation for nested matchers.
         #
-        # Subclasses (like HaveDirectory) may extend this to recurse into nested
-        # matchers.
+        # A nesting matcher (such as BeDirectory) may call this method on the
+        # nested matchers to collect all validation errors before raising an
+        # ArgumentError.
         #
-        # @param errors [Array<String>] An array to append validation error messages to.
+        # @param errors [Array<String>] An array to populate with validation error
+        # messages
         #
         # @return [void]
         #
@@ -88,52 +195,93 @@ module RSpec
           validate_option_values(errors)
         end
 
-        def failure_message
-          header = "the entry '#{name}' at '#{base_path}' was expected to satisfy the following but did not:"
-          # Format single- and multi-line nested messages with proper indentation.
-          messages = failure_messages.map do |msg|
-            msg.lines.map.with_index do |line, i|
-              i.zero? ? "  - #{line.chomp}" : "    #{line.chomp}"
-            end.join("\n")
-          end.join("\n")
-          "#{header}\n#{messages}"
-        end
-
+        # Returns `true` if `path` exists and is of the correct type for this matcher
+        #
+        # Subclasses must implement this method to check the type of the entry. For
+        # example, BeFile checks if the path is a regular file; BeDirectory, a
+        # directory; and BeSymlink, a symlink.
+        #
+        # @return [Boolean]
+        #
+        # @abstract
+        #
         def correct_type?
-          raise NotImplementedError, 'This method should be implemented in a subclass'
+          raise NotImplementedError, 'Subclasses must implement Base#correct_type?'
         end
 
-        def matcher_name
-          raise NotImplementedError, 'This method should be implemented in a subclass'
+        # Add to errors if options were passed to the negative matcher
+        #
+        # This method is called by RSpec for `expect(...).not_to <matcher>...`
+        #
+        # Subclasses can override this to add additional validation.
+        #
+        # @param errors [Array<String>] An array to append validation error messages to
+        #
+        # @return [void]
+        #
+        def collect_negative_validation_errors(errors)
+          errors << "The matcher `not_to #{matcher_name}(...)` cannot be given options" if options.any_given?
         end
 
-        protected
+        # Subclasses should define their own option definitions
+        #
+        # @return [Array<RSpec::PathMatchers::Options::Base>] An array of option definitions
+        #
+        def option_definitions = []
 
+        # The type of entry this matcher is checking for
+        #
+        # @return [Symbol] The entry type (e.g. :file, :directory, :symlink, ...)
+        #
         def entry_type
-          self.class.name.split('::').last.sub(/^Have/, '').downcase
+          raise NotImplementedError, 'Subclasses must implement Base#entry_type'
         end
 
         # Performs the actual matching against the directory entry
         #
         # This method assumes that collect_validation_errors has already been called
-        # and passed. This method is protected so that container matchers (like
-        # HaveDirectory) can call it on nested matchers without using .send.
+        # and passed.
+        #
+        # This method is protected so that container matchers (like BeDirectory)
+        # can call it on nested matchers without using .send.
         #
         def execute_match(base_path) # rubocop:disable Naming/PredicateMethod
+          # It is important to reset failures in case this matcher is reused
+          @failures = []
+
           @base_path = base_path.to_s
-          @path = File.join(base_path, name)
+          @path = @entry_name.empty? ? base_path : File.join(base_path, entry_name)
 
           # Validate existence and type.
-          validate_existance(failure_messages)
-          return false if failure_messages.any?
+          validate_existance
+          return false if failures.any?
 
           # Validate specific options and nested expectations.
           validate_options
-          failure_messages.empty?
+          failures.empty?
         end
 
         private
 
+        # Formats a group of failures for a single relative path.
+        #
+        # @param relative_path [String] The path of the failure relative to the subject.
+        # @param failures_for_path [Array<Failure>] A list of failures for that path.
+        # @return [String] A formatted string block for this group of failures.
+        #
+        def format_failure_group(relative_path, failures_for_path)
+          indented_errors = failures_for_path.map { |f| "      #{f.message}" }.join("\n")
+
+          if relative_path == '.'
+            # For failures on the subject itself, just show the indented errors.
+            indented_errors
+          else
+            # For failures on a child, show the path and then the indented errors.
+            path_line = "  - #{relative_path}"
+            "#{path_line}\n#{indented_errors}"
+          end
+        end
+
         def build_options_description
           descriptions = options.to_h.filter_map do |key, value|
             next if value == RSpec::PathMatchers::Options::NOT_GIVEN
@@ -176,21 +324,27 @@ module RSpec
           end
         end
 
-        def validate_existance(_failure_messages)
-          raise NotImplementedError, 'This method should be implemented in a subclass'
+        def validate_existance
+          raise NotImplementedError, 'Subclasses must implement Base#validate_existance'
         end
 
         # Validate the options for the current matcher
         #
-        # Subclasses will override this to add nested execution.
+        # Subclasses may override this to add additional validation logic. For
+        # instance, BeDirectory extends this to check nested matchers.
+        #
         def validate_options
           options.members.each do |key|
             expected = options.send(key)
             next if expected == RSpec::PathMatchers::Options::NOT_GIVEN
 
-            option_definition(key).match(path, expected, failure_messages)
+            option_definition(key).match(path, expected, failures)
           end
         end
+
+        def add_failure(message, failures)
+          failures << RSpec::PathMatchers::Failure.new('.', message)
+        end
       end
     end
   end

data/lib/rspec/path_matchers/matchers/directory_matcher.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require 'pathname'
+
+module RSpec
+  module PathMatchers
+    module Matchers
+      # An RSpec matcher that checks for the existence and properties of a directory
+      #
+      class DirectoryMatcher < Base
+        OPTIONS = [
+          RSpec::PathMatchers::Options::Atime,
+          RSpec::PathMatchers::Options::Birthtime,
+          RSpec::PathMatchers::Options::Ctime,
+          RSpec::PathMatchers::Options::Group,
+          RSpec::PathMatchers::Options::Mode,
+          RSpec::PathMatchers::Options::Mtime,
+          RSpec::PathMatchers::Options::Owner
+        ].freeze
+
+        # @attribute [r] exact
+        #
+        # If true, the dir must contain only entries given in `containing_exactly`
+        #
+        # The default is false, meaning the directory can contain additional entries.
+        #
+        # @return [Boolean]
+        #
+        attr_reader :exact
+
+        # Initializes the matcher with the directory name and options
+        #
+        # @param entry_name [String] The name of the directory relative to the subject or empty
+        #
+        # @param matcher_name [Symbol] The name of the DSL method used to create this matcher
+        #
+        # @param options_hash [Hash] A hash of attribute matchers (e.g., mode:, owner:)
+        #
+        def initialize(entry_name, matcher_name:, **options_hash)
+          super
+
+          @exact = false
+          @nested_matchers = []
+        end
+
+        def containing(*matchers)
+          @nested_matchers << matchers
+          @exact = false
+          self
+        end
+
+        def containing_exactly(*matchers)
+          @nested_matchers << matchers
+          @exact = true
+          self
+        end
+
+        def description
+          desc = super
+          return desc if nested_matchers.empty?
+
+          nested_descriptions = nested_matchers.map do |matcher|
+            matcher.description.lines.map.with_index do |line, i|
+              i.zero? ? "- #{line.chomp}" : "  #{line.chomp}"
+            end.join("\n")
+          end
+
+          "#{desc} containing#{' exactly' if exact}:\n  #{nested_descriptions.join("\n  ")}"
+        end
+
+        def entry_type = :directory
+        def option_definitions = OPTIONS
+        def correct_type? = File.directory?(path)
+
+        def collect_negative_validation_errors(errors)
+          super
+          return unless nested_matchers.any?
+
+          errors << "The matcher `not_to #{matcher_name}(...)` cannot have expectations on its contents"
+        end
+
+        def collect_validation_errors(errors)
+          super
+
+          if @nested_matchers.size > 1
+            errors << 'Collectively, `#containing` and `#containing_exactly` may be called only once'
+          end
+
+          # Recursively validate nested matchers.
+          nested_matchers.each { |matcher| matcher.collect_validation_errors(errors) }
+        end
+
+        protected
+
+        # Overrides Base to add the exactness check after other validations.
+        def validate_options
+          # Validate this directory's own options (mode, owner, etc.)
+          super
+
+          # Validate the nested entries described in `containing`
+          validate_nested_matchers
+
+          return unless failures.empty?
+
+          # If using `containing_exactly`, check for unexpected entries
+          check_for_unexpected_entries if exact
+        end
+
+        def validate_existance
+          return if File.directory?(path)
+
+          message = (File.exist?(path) ? 'expected it to be a directory' : 'expected it to exist')
+          add_failure(message, failures)
+        end
+
+        private
+
+        # This new private method encapsulates the logic for checking children.
+        def validate_nested_matchers
+          nested_matchers.each do |matcher|
+            next if matcher.execute_match(path)
+
+            matcher.failures.each do |failure|
+              new_relative_path = (Pathname.new(matcher.entry_name) + Pathname.new(failure.relative_path)).to_s
+              failures << RSpec::PathMatchers::Failure.new(new_relative_path, failure.message)
+            end
+          end
+        end
+
+        # An array of nested matchers that define the expected contents of the
+        # directory
+        #
+        # One element is added to the @nested_matchers array for each call to
+        # `containing` or `containing_exactly`. Since `containing` or
+        # `containing_exactly` are allowed only once per matcher, an error will be
+        # logged during validation if the size of this array is greater than one.
+        #
+        # Each element in @nested_matchers is itself an array of the matchers given
+        # in each `containing` or `containing_exactly` call.
+        #
+        # This method returns the first element of @nested_matchers (or an empty
+        # array of @nested_matchers is itself empty).
+        #
+        # @return [Array<RSpec::PathMatchers::Matchers::Base>]
+        #
+        def nested_matchers
+          @nested_matchers.first || []
+        end
+
+        # Checks for any files/directories on disk that were not declared in the block.
+        def check_for_unexpected_entries
+          positively_declared_entries = nested_matchers.reject do |m|
+            m.is_a?(RSpec::PathMatchers::Matchers::NoEntryMatcher)
+          end.map(&:entry_name)
+
+          actual_entries = Dir.children(path)
+          unexpected_entries = actual_entries - positively_declared_entries
+
+          return if unexpected_entries.empty?
+
+          message = build_unexpected_entries_message(unexpected_entries)
+          add_failure(message, failures)
+        end
+
+        def build_unexpected_entries_message(unexpected_entries)
+          "contained unexpected entries #{unexpected_entries.sort.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/rspec/path_matchers/matchers/{have_file.rb → file_matcher.rb}

@@ -6,7 +6,8 @@ module RSpec
   module PathMatchers
     module Matchers
       # An RSpec matcher checks for the existence and properties of a file
-      class HaveFile < Base
+      #
+      class FileMatcher < Base
         OPTIONS = [
           RSpec::PathMatchers::Options::Atime,
           RSpec::PathMatchers::Options::Birthtime,
@@ -21,23 +22,25 @@ module RSpec
           RSpec::PathMatchers::Options::YamlContent
         ].freeze
 
+        def entry_type = :file
+
         def option_definitions = OPTIONS
 
         def correct_type? = File.file?(path)
 
-        def matcher_name = 'have_file'
-
         protected
 
-        def validate_existance(failure_messages)
+        def validate_existance
           return nil if File.file?(path)
 
-          failure_messages <<
+          message =
             if File.exist?(path)
               'expected it to be a regular file'
             else
               'expected it to exist'
             end
+
+          add_failure(message, failures)
         end
       end
     end

data/lib/rspec/path_matchers/matchers/no_entry_matcher.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module RSpec
+  module PathMatchers
+    module Matchers
+      # Asserts that a directory entry of a specific entry_type does NOT exist.
+      # This is a simple, internal matcher-like object.
+      #
+      # @api private
+      class NoEntryMatcher
+        attr_reader :entry_name, :entry_type, :base_path, :path
+
+        # Initializes the matcher with the entry name and type
+        #
+        # @param entry_name [String] The name of the entry to check
+        #
+        # @param matcher_name [Symbol] The name of the DSL method used to create this matcher
+        #
+        # @param entry_type [Symbol] The type of the entry (:file, :directory, or :symlink)
+        #
+        def initialize(entry_name, matcher_name:, entry_type:)
+          @entry_name = entry_name
+          @matcher_name = matcher_name
+          @entry_type = entry_type
+          @base_path = nil
+          @path = nil
+        end
+
+        # The core logic. Returns `true` if the expectation is met (the entry is absent).
+        def execute_match(base_path) # rubocop:disable Naming/PredicateMethod
+          @base_path = base_path
+          @path = File.join(base_path, entry_name)
+
+          case entry_type
+          when :file then !File.file?(path)
+          when :directory then !File.directory?(path)
+          else !File.symlink?(path)
+          end
+        end
+
+        # The failure message if `execute_match` returns `false`.
+        def failure_message
+          "expected #{entry_type} '#{entry_name}' not to be found at '#{base_path}', but it exists"
+        end
+
+        # Returns the failure message in an array as expected by the DirectoryMatcher
+        #
+        # @return [Array<String>]
+        #
+        def failures
+          [RSpec::PathMatchers::Failure.new('.', failure_message)]
+        end
+
+        # Provides a human-readable description for use in test output.
+        def description
+          "not have #{entry_type} #{entry_name.inspect}"
+        end
+
+        # Called by DirectoryMatcher but is not needed for this simple matcher
+        def collect_validation_errors(_errors); end
+      end
+    end
+  end
+end

data/lib/rspec/path_matchers/matchers/{have_symlink.rb → symlink_matcher.rb}

@@ -5,8 +5,9 @@ require_relative 'base'
 module RSpec
   module PathMatchers
     module Matchers
-      # An RSpec matcher checks for the existence and properties of a file
-      class HaveSymlink < Base
+      # An RSpec matcher that checks for the existence and properties of a symlink
+      #
+      class SymlinkMatcher < Base
         OPTIONS = [
           RSpec::PathMatchers::Options::SymlinkAtime,
           RSpec::PathMatchers::Options::SymlinkBirthtime,
@@ -19,23 +20,25 @@ module RSpec
           RSpec::PathMatchers::Options::SymlinkTargetType
         ].freeze
 
+        def entry_type = :symlink
+
         def option_definitions = OPTIONS
 
         def correct_type? = File.symlink?(path)
 
-        def matcher_name = 'have_symlink'
-
         protected
 
-        def validate_existance(failure_messages)
+        def validate_existance
           return nil if File.symlink?(path)
 
-          failure_messages <<
+          message =
             if File.exist?(path)
               'expected it to be a symlink'
             else
               'expected it to exist'
             end
+
+          add_failure(message, failures)
         end
       end
     end