rspec-path_matchers 0.1.0

data/Rakefile

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+desc 'Run the same tasks that the CI build will run'
+task default: %w[spec rubocop yard bundle:audit build]
+
+# Bundler Audit
+
+require 'bundler/audit/task'
+Bundler::Audit::Task.new
+
+# Bundler Gem Build
+
+require 'bundler'
+require 'bundler/gem_tasks'
+
+# Make it so that calling `rake release` just calls `rake release:rubygems_push` to
+# avoid creating and pushing a new tag.
+
+Rake::Task['release'].clear
+desc 'Customized release task to avoid creating a new tag'
+task release: 'release:rubygem_push'
+
+# RSpec
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new
+
+CLEAN << 'coverage'
+CLEAN << '.rspec_status'
+CLEAN << 'rspec-report.xml'
+
+# Rubocop
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+# YARD
+
+# yard:build
+
+require 'yard'
+
+YARD::Rake::YardocTask.new('yard:build') do |t|
+  t.files = %w[lib/**/*.rb examples/**/*]
+  t.options = %w[--no-private]
+  t.stats_options = %w[--list-undoc]
+end
+
+CLEAN << '.yardoc'
+CLEAN << 'doc'
+
+# yard:audit
+
+desc 'Run yardstick to show missing YARD doc elements'
+task :'yard:audit' do
+  sh "yardstick 'lib/**/*.rb'"
+end
+
+# yard:coverage
+
+require 'yardstick/rake/verify'
+
+Yardstick::Rake::Verify.new(:'yard:coverage') do |verify|
+  verify.threshold = 100
+end
+
+# yard
+
+desc 'Run all YARD tasks'
+# task yard: %i[yard:build yard:audit yard:coverage]
+task yard: %i[yard:build]

data/design.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+########################################
+# Matchers for directory entries
+expect(path).to have_file(
+  name, content:, json_content:, yaml_content:, size:, mode:, owner:, group:, ctime:, mtime:
+)
+
+expect(path).to have_dir(
+  name, entry_count:, mode:, owner:, group:, ctime:, mtime:, exact:
+)
+
+expect(path).to have_symlink(
+  name, mode:, owner:, group:, ctime:, mtime:, target:, target_type:, dangling:
+)
+
+########################################
+# have_file matcher
+expect(path).to have_file(name)
+
+# Content checks
+expect(path).to have_file(name, content: matcher | String | Regexp) # Matcher is compared to file content as a String
+expect(path).to have_file(name, json_content: matcher | true) # ...the parsed file content as a Hash/Array/Object
+expect(path).to have_file(name, yaml_content: matcher | true) # ...the parsed file content as a Hash/Array/Object
+expect(path).to have_file(name, size: matcher) # ...the file size as an Integer
+
+# Attribute checks
+expect(path).to have_file(name, mode: matcher | String) # ...the file mode as a String (e.g. '0644')
+expect(path).to have_file(name, owner: matcher | String) # ...the file owner as a String
+expect(path).to have_file(name, group: matcher | String) # ...the file group as a String
+expect(path).to have_file(name, ctime: matcher | Time) # ...the file creation time as a Time
+expect(path).to have_file(name, mtime: matcher | Time) # ...the file modification time as a Time
+
+########################################
+# have_dir matcher
+expect(path).to have_dir(name)
+
+# Content checks
+expect(path).to have_dir(name, entry_count: matcher) # Matcher is compared to the number of entries in the directory
+
+# Attribute checks
+expect(path).to have_dir(name, mode: matcher) # ...the directory mode as a String (e.g. '0755')
+expect(path).to have_dir(name, owner: matcher) # ...the directory owner as a String
+expect(path).to have_dir(name, group: matcher) # ...the directory group as a String
+expect(path).to have_dir(name, ctime: matcher) # ...the directory creation time as a Time
+expect(path).to have_dir(name, mtime: matcher) # ...the directory modification time as a Time
+
+# Nested directory checks ()
+expect(path).to(
+  have_dir(name) do
+    file('nested_file.txt', content: 'expected content')
+    dir('nested_dir') do
+      file('deeply_nested_file.txt', content: 'deeply expected content')
+    end
+    symlink('nested_symlink', target: 'expected_target')
+    no_file('non_existent_file.txt')
+    no_dir('non_existent_dir')
+    no_symlink('non_existent_symlink')
+    no_entry('non_existent_entry') # This checks for the absence of any type of entry with the given name
+  end
+)
+
+########################################
+# have_symlink matcher
+expect(path).to have_symlink(name)
+
+# Attribute checks
+expect(path).to have_symlink(name, mode: mode_matcher) # Matcher is compared to symlink mode as a String (e.g. '0777')
+expect(path).to have_symlink(name, owner: owner_matcher) # ...the symlink owner as a String
+expect(path).to have_symlink(name, group: group_matcher) # ...the symlink group as a String
+expect(path).to have_symlink(name, ctime: timestamp_matcher) # ...the symlink creation time as a Time
+expect(path).to have_symlink(name, mtime: timestamp_matcher) # ...the symlink modification time as a Time
+
+expect(path).to have_symlink(name, target: target_matcher) # ...the symlink target as a String
+expect(path).to have_symlink(name, target_type: target_type)
+expect(path).to have_symlink(name, target_exist?: boolean) # Assert whether the symlink is dangling or not

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

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+module RSpec
+  module PathMatchers
+    module Matchers
+      # The base class for matchers
+      class Base # rubocop:disable Metrics/ClassLength
+        def initialize(name, **options_hash)
+          super()
+          @name = name.to_s
+          @options = options_factory(*option_keys, **options_hash)
+        end
+
+        attr_reader :name, :options, :base_path, :path
+
+        # 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\"".
+        #
+        # @return [String] A description of the matcher
+        #
+        def description
+          desc = "have #{entry_type} #{name.inspect}"
+          options_description = build_options_description
+          desc += " with #{options_description}" unless options_description.empty?
+          desc
+        end
+
+        def failure_messages
+          @failure_messages ||= []
+        end
+
+        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
+          validation_errors = []
+          collect_validation_errors(validation_errors)
+          raise ArgumentError, validation_errors.join(', ') if validation_errors.any?
+
+          # Phase 2: Execute the actual match logic
+          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?
+        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.
+          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)
+
+          # 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).
+          !correct_type?
+        end
+
+        # This is the message RSpec will display if `does_not_match?` returns `false`.
+        def failure_message_when_negated
+          "expected it not to be a #{entry_type}"
+        end
+
+        # Recursively gathers all syntax/validation errors
+        #
+        # Subclasses (like HaveDirectory) may extend this to recurse into nested
+        # matchers.
+        #
+        # @param errors [Array<String>] An array to append validation error messages to.
+        #
+        # @return [void]
+        #
+        # @api private
+        #
+        def collect_validation_errors(errors)
+          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
+
+        def correct_type?
+          raise NotImplementedError, 'This method should be implemented in a subclass'
+        end
+
+        def matcher_name
+          raise NotImplementedError, 'This method should be implemented in a subclass'
+        end
+
+        protected
+
+        def entry_type
+          self.class.name.split('::').last.sub(/^Have/, '').downcase
+        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.
+        #
+        def execute_match(base_path) # rubocop:disable Naming/PredicateMethod
+          @base_path = base_path.to_s
+          @path = File.join(base_path, name)
+
+          # Validate existence and type.
+          validate_existance(failure_messages)
+          return false if failure_messages.any?
+
+          # Validate specific options and nested expectations.
+          validate_options
+          failure_messages.empty?
+        end
+
+        private
+
+        def build_options_description
+          descriptions = options.to_h.filter_map do |key, value|
+            next if value == RSpec::PathMatchers::Options::NOT_GIVEN
+
+            "#{key.to_s.chomp('?')} #{option_definition(key).description(value)}"
+          end
+          descriptions.join(' and ')
+        end
+
+        def options_factory(*members, **options_hash)
+          Data.define(*members) do
+            def initialize(**kwargs)
+              # Default every member to the NOT_GIVEN sentinel
+              defaults = self.class.members.to_h { |member| [member, RSpec::PathMatchers::Options::NOT_GIVEN] }
+              final_args = defaults.merge(kwargs)
+              super(**final_args)
+            end
+
+            def any_given?
+              to_h.values.any? { |v| v != RSpec::PathMatchers::Options::NOT_GIVEN }
+            end
+          end.new(**options_hash)
+        end
+
+        def option_definition(key)
+          option_definitions.find { |definition| definition.key == key }
+        end
+
+        def option_keys
+          option_definitions.map(&:key)
+        end
+
+        # Ensure the user provided option-values are of the expected type and format
+        def validate_option_values(errors)
+          options.members.filter_map do |key|
+            expected = options.send(key)
+            next if expected == RSpec::PathMatchers::Options::NOT_GIVEN
+
+            option_definition(key).validate_expected(expected, errors)
+          end
+        end
+
+        def validate_existance(_failure_messages)
+          raise NotImplementedError, 'This method should be implemented in a subclass'
+        end
+
+        # Validate the options for the current matcher
+        #
+        # Subclasses will override this to add nested execution.
+        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)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RSpec
+  module PathMatchers
+    module Matchers
+      # Provides the DSL for the `have_dir` matcher's block
+      #
+      # It is responsible for creating and collecting the nested matchers
+      # without immediately executing them.
+      #
+      # @api private
+      #
+      class DirectoryContentsInspector
+        # By including RSpec::Matchers, we make methods like `be`, `eq`, `include`,
+        # `an_instance_of`, etc., available within the `have_dir` block
+        #
+        include RSpec::Matchers
+
+        def initialize
+          @nested_matchers = []
+        end
+
+        attr_reader :nested_matchers
+
+        # Defines an expectation for a file within the directory.
+        def file(name, **)
+          nested_matchers << RSpec::PathMatchers::Matchers::HaveFile.new(name, **)
+        end
+
+        # Defines an expectation for a nested directory.
+        def dir(name, ...)
+          nested_matchers << RSpec::PathMatchers::Matchers::HaveDirectory.new(name, ...)
+        end
+
+        # Defines an expectation for a symlink within the directory.
+        def symlink(name, **)
+          nested_matchers << RSpec::PathMatchers::Matchers::HaveSymlink.new(name, **)
+        end
+
+        # Defines an expectation that a file does NOT exist within the directory.
+        def no_file(name)
+          nested_matchers << RSpec::PathMatchers::Matchers::HaveNoEntry.new(name, type: :file)
+        end
+
+        # Defines an expectation that a directory does NOT exist within the directory.
+        def no_dir(name)
+          nested_matchers << RSpec::PathMatchers::Matchers::HaveNoEntry.new(name, type: :directory)
+        end
+
+        # Defines an expectation that a symlink does NOT exist within the directory.
+        def no_symlink(name)
+          nested_matchers << RSpec::PathMatchers::Matchers::HaveNoEntry.new(name, type: :symlink)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'directory_contents_inspector'
+
+module RSpec
+  module PathMatchers
+    module Matchers
+      # An RSpec matcher that checks for the existence and properties of a directory
+      #
+      class HaveDirectory < 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
+
+        attr_reader :nested_matchers, :exact
+
+        # Initializes the matcher with the directory name and options
+        #
+        # @param name [String] The name of the directory
+        #
+        # @param exact [Boolean] The directory must contain only entries declared in the specification block
+        #
+        # @param options_hash [Hash] A hash of attribute matchers (e.g., mode:, owner:)
+        #
+        # @param specification_block [Proc] A specification block that defines the expected directory contents
+        #
+        def initialize(name, exact: false, **options_hash, &specification_block)
+          super(name, **options_hash)
+
+          @exact = exact
+          @nested_matchers = []
+          return unless specification_block
+
+          inspector = DirectoryContentsInspector.new
+          inspector.instance_eval(&specification_block)
+          @nested_matchers = inspector.nested_matchers
+        end
+
+        def description
+          desc = super
+          desc += ' exactly' if exact
+          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:\n  #{nested_descriptions.join("\n  ")}"
+        end
+
+        def collect_negative_validation_errors(errors)
+          super
+          return unless nested_matchers.any?
+
+          errors << "The matcher `not_to #{matcher_name}(...)` cannot be given a specification block"
+        end
+
+        def collect_validation_errors(errors)
+          super
+
+          errors << "`exact:` must be true or false, but was #{exact.inspect}" unless [true, false].include?(exact)
+
+          # Recursively validate nested matchers.
+          nested_matchers.each { |matcher| matcher.collect_validation_errors(errors) }
+        end
+
+        def option_definitions = OPTIONS
+        def correct_type? = File.directory?(path)
+        def matcher_name = 'have_dir'
+
+        protected
+
+        # Overrides Base to add the exactness check after other validations.
+        def validate_options
+          super # Validate this directory's own options first.
+
+          nested_matchers.each do |matcher|
+            failure_messages << matcher.failure_message unless matcher.execute_match(path)
+          end
+
+          # If any of the declared expectations failed, we stop here.
+          # The user needs to fix those first.
+          return unless failure_messages.empty?
+
+          check_for_unexpected_entries if exact
+        end
+
+        def validate_existance(failure_messages)
+          return if File.directory?(path)
+
+          failure_messages << (File.exist?(path) ? 'expected it to be a directory' : 'expected it to exist')
+        end
+
+        private
+
+        # 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::HaveNoEntry)
+          end.map(&: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)
+          failure_messages << message
+        end
+
+        def build_unexpected_entries_message(unexpected_entries)
+          "did not expect entries #{unexpected_entries.inspect} to be present"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module RSpec
+  module PathMatchers
+    module Matchers
+      # An RSpec matcher checks for the existence and properties of a file
+      class HaveFile < Base
+        OPTIONS = [
+          RSpec::PathMatchers::Options::Atime,
+          RSpec::PathMatchers::Options::Birthtime,
+          RSpec::PathMatchers::Options::Content,
+          RSpec::PathMatchers::Options::Ctime,
+          RSpec::PathMatchers::Options::Group,
+          RSpec::PathMatchers::Options::JsonContent,
+          RSpec::PathMatchers::Options::Mode,
+          RSpec::PathMatchers::Options::Mtime,
+          RSpec::PathMatchers::Options::Owner,
+          RSpec::PathMatchers::Options::Size,
+          RSpec::PathMatchers::Options::YamlContent
+        ].freeze
+
+        def option_definitions = OPTIONS
+
+        def correct_type? = File.file?(path)
+
+        def matcher_name = 'have_file'
+
+        protected
+
+        def validate_existance(failure_messages)
+          return nil if File.file?(path)
+
+          failure_messages <<
+            if File.exist?(path)
+              'expected it to be a regular file'
+            else
+              'expected it to exist'
+            end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# In lib/rspec/path_matchers/matchers/have_no_entry.rb
+# frozen_string_literal: true
+
+module RSpec
+  module PathMatchers
+    module Matchers
+      # Asserts that a directory entry of a specific type does NOT exist.
+      # This is a simple, internal matcher-like object.
+      #
+      # @api private
+      class HaveNoEntry
+        attr_reader :name
+
+        def initialize(name, type:)
+          @name = name
+          @type = 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, @name)
+
+          case @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 #{@type} '#{@name}' not to be found at '#{@base_path}', but it exists"
+        end
+
+        # Provide a description for the `have_dir` block's output.
+        def description
+          "not have #{@type} #{@name.inspect}"
+        end
+
+        # Provide a stub for this method, which is called by HaveDirectory
+        # 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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module RSpec
+  module PathMatchers
+    module Matchers
+      # An RSpec matcher checks for the existence and properties of a file
+      class HaveSymlink < Base
+        OPTIONS = [
+          RSpec::PathMatchers::Options::SymlinkAtime,
+          RSpec::PathMatchers::Options::SymlinkBirthtime,
+          RSpec::PathMatchers::Options::SymlinkCtime,
+          RSpec::PathMatchers::Options::SymlinkGroup,
+          RSpec::PathMatchers::Options::SymlinkMtime,
+          RSpec::PathMatchers::Options::SymlinkOwner,
+          RSpec::PathMatchers::Options::SymlinkTarget,
+          RSpec::PathMatchers::Options::SymlinkTargetExist,
+          RSpec::PathMatchers::Options::SymlinkTargetType
+        ].freeze
+
+        def option_definitions = OPTIONS
+
+        def correct_type? = File.symlink?(path)
+
+        def matcher_name = 'have_symlink'
+
+        protected
+
+        def validate_existance(failure_messages)
+          return nil if File.symlink?(path)
+
+          failure_messages <<
+            if File.exist?(path)
+              'expected it to be a symlink'
+            else
+              'expected it to exist'
+            end
+        end
+      end
+    end
+  end
+end