rspec-path_matchers 0.1.1 → 0.2.1

data/lib/rspec/path_matchers.rb

@@ -3,31 +3,200 @@
 require 'rspec'
 
 module RSpec
-  # RSpec::PathMatchers is a collection of matchers for testing directory entries
+  # A collection of matchers for testing directory entries
+  #
+  # This module provides the main DSL methods for use in RSpec tests.
+  #
+  # @example
+  #   require 'rspec/path_matchers'
+  #
+  #   RSpec.configure do |config|
+  #     config.include RSpec::PathMatchers
+  #   end
+  #
+  #   RSpec.describe '/var/log' do
+  #     it { is_expected.to be_dir.containing(file('syslog')) }
+  #   end
+  #
   module PathMatchers
     # Returns true if object is a matcher
+    # @api private
     def self.matcher?(object)
       object.respond_to?(:matches?) && object.respond_to?(:description)
     end
+
+    # A simple, immutable structure to hold failure data internally.
+    # @api private
+    Failure = Data.define(:relative_path, :message)
+
+    # @!group Top-Level Matchers
+
+    # Creates a matcher that tests if the subject path is a directory
+    #
+    # @param options_hash [Hash] A hash of attribute matchers (e.g., mode:, owner:).
+    #
+    # @return [RSpec::PathMatchers::Matchers::DirectoryMatcher] The matcher instance.
+    #
+    # @example Basic existence check
+    #   expect('/var/log').to be_dir
+    #
+    # @example Checking attributes
+    #   expect('/tmp').to be_dir(mode: '1777')
+    #
+    def be_dir(**options_hash)
+      RSpec::PathMatchers::Matchers::DirectoryMatcher.new('', matcher_name: __method__, **options_hash)
+    end
+
+    # Creates a matcher that tests if the subject path is a file
+    #
+    # @param options_hash [Hash] A hash of attribute matchers (e.g., content:, size:).
+    # @return [RSpec::PathMatchers::Matchers::FileMatcher] The matcher instance.
+    #
+    # @example
+    #   expect('/etc/hosts').to be_file(content: include('localhost'))
+    #
+    def be_file(**options_hash)
+      RSpec::PathMatchers::Matchers::FileMatcher.new('', matcher_name: __method__, **options_hash)
+    end
+
+    # Creates a matcher that tests if the subject path is a symbolic link
+    #
+    # @param options_hash [Hash] A hash of attribute matchers (e.g., target:).
+    # @return [RSpec::PathMatchers::Matchers::SymlinkMatcher] The matcher instance.
+    #
+    # @example
+    #   expect('/usr/bin/ruby').to be_symlink(target: a_string_ending_with('ruby3.2'))
+    #
+    def be_symlink(**options_hash)
+      RSpec::PathMatchers::Matchers::SymlinkMatcher.new('', matcher_name: __method__, **options_hash)
+    end
+
+    # @!endgroup
+
+    # @!group Top-Level Child Matchers
+
+    # A matcher to test if the subject path has a child directory with the given name
+    #
+    # @param entry_name [String] The name of the expected child directory.
+    # @param options_hash [Hash] A hash of attribute matchers.
+    # @return [RSpec::PathMatchers::Matchers::DirectoryMatcher]
+    #
+    # @example
+    #   expect('/tmp').to have_dir('new_project', owner: 'root')
+    #
+    def have_dir(entry_name, **options_hash) # rubocop:disable Naming/PredicatePrefix
+      RSpec::PathMatchers::Matchers::DirectoryMatcher.new(entry_name, matcher_name: __method__, **options_hash)
+    end
+
+    # A matcher to test if the subject path has a child file with the given name
+    #
+    # @param entry_name [String] The name of the expected child file.
+    # @param options_hash [Hash] A hash of attribute matchers.
+    # @return [RSpec::PathMatchers::Matchers::FileMatcher]
+    #
+    # @example
+    #   expect('/etc').to have_file('hosts', content: /localhost/)
+    #
+    def have_file(entry_name, **options_hash) # rubocop:disable Naming/PredicatePrefix
+      RSpec::PathMatchers::Matchers::FileMatcher.new(entry_name, matcher_name: __method__, **options_hash)
+    end
+
+    # A matcher to test if the subject path has a child symlink with the given name
+    #
+    # @param entry_name [String] The name of the expected child symlink.
+    # @param options_hash [Hash] A hash of attribute matchers.
+    # @return [RSpec::PathMatchers::Matchers::SymlinkMatcher]
+    #
+    # @example
+    #   expect('/usr/local/bin').to have_symlink('ruby')
+    #
+    def have_symlink(entry_name, **options_hash) # rubocop:disable Naming/PredicatePrefix
+      RSpec::PathMatchers::Matchers::SymlinkMatcher.new(entry_name, matcher_name: __method__, **options_hash)
+    end
+
+    # @!endgroup
+
+    # @!group Nested Entry Declarations
+
+    # Declares an expectation for a file within a directory
+    #
+    # Intended for use as an argument to #containing or #containing_exactly.
+    #
+    # @param name [String] The name of the expected file.
+    # @param options_hash [Hash] A hash of attribute matchers (e.g., content:, size:).
+    # @return [RSpec::PathMatchers::Matchers::FileMatcher] The matcher object.
+    #
+    def file(name, **options_hash)
+      RSpec::PathMatchers::Matchers::FileMatcher.new(name, matcher_name: __method__, **options_hash)
+    end
+
+    # Declares an expectation for a directory within a directory
+    #
+    # Intended for use as an argument to #containing or #containing_exactly.
+    #
+    # @param name [String] The name of the expected directory.
+    # @param options_hash [Hash] A hash of attribute matchers (e.g., mode:, owner:).
+    # @return [RSpec::PathMatchers::Matchers::DirectoryMatcher] The matcher object.
+    #
+    def dir(name, **options_hash)
+      RSpec::PathMatchers::Matchers::DirectoryMatcher.new(name, matcher_name: __method__, **options_hash)
+    end
+
+    # Declares an expectation for a symbolic link within a directory
+    #
+    # Intended for use as an argument to #containing or #containing_exactly.
+    #
+    # @param name [String] The name of the expected symlink.
+    # @param options_hash [Hash] A hash of attribute matchers (e.g., target:).
+    # @return [RSpec::PathMatchers::Matchers::SymlinkMatcher] The matcher object.
+    #
+    def symlink(name, **options_hash)
+      RSpec::PathMatchers::Matchers::SymlinkMatcher.new(name, matcher_name: __method__, **options_hash)
+    end
+
+    # Declares an expectation that a directory with the given name does NOT exist
+    #
+    # Intended for use as an argument to #containing or #containing_exactly.
+    #
+    # @param name [String] The name of the directory that should be absent.
+    # @return [RSpec::PathMatchers::Matchers::NoEntryMatcher]
+    #
+    def no_dir_named(name)
+      RSpec::PathMatchers::Matchers::NoEntryMatcher.new(name, matcher_name: __method__, entry_type: :directory)
+    end
+
+    # Declares an expectation that a file with the given name does NOT exist
+    #
+    # Intended for use as an argument to #containing or #containing_exactly.
+    #
+    # @param name [String] The name of the file that should be absent.
+    # @return [RSpec::PathMatchers::Matchers::NoEntryMatcher]
+    #
+    def no_file_named(name)
+      RSpec::PathMatchers::Matchers::NoEntryMatcher.new(name, matcher_name: __method__, entry_type: :file)
+    end
+
+    # Declares an expectation that a symlink with the given name does NOT exist
+    #
+    # Intended for use as an argument to #containing or #containing_exactly.
+    #
+    # @param name [String] The name of the symlink that should be absent.
+    # @return [RSpec::PathMatchers::Matchers::NoEntryMatcher]
+    #
+    def no_symlink_named(name)
+      RSpec::PathMatchers::Matchers::NoEntryMatcher.new(name, matcher_name: __method__, entry_type: :symlink)
+    end
+
+    # @!endgroup
   end
 end
 
 require_relative 'path_matchers/version'
 require_relative 'path_matchers/options'
 
-require_relative 'path_matchers/matchers/have_file'
-require_relative 'path_matchers/matchers/have_directory'
-require_relative 'path_matchers/matchers/have_symlink'
-require_relative 'path_matchers/matchers/have_no_entry'
+require_relative 'path_matchers/matchers/directory_matcher'
+require_relative 'path_matchers/matchers/file_matcher'
+require_relative 'path_matchers/matchers/no_entry_matcher'
+require_relative 'path_matchers/matchers/symlink_matcher'
 
-def have_file(name, **options_hash) # rubocop:disable Naming/PredicatePrefix
-  RSpec::PathMatchers::Matchers::HaveFile.new(name, **options_hash)
-end
-
-def have_dir(name, **options_hash, &) # rubocop:disable Naming/PredicatePrefix
-  RSpec::PathMatchers::Matchers::HaveDirectory.new(name, **options_hash, &)
-end
-
-def have_symlink(name, **options_hash) # rubocop:disable Naming/PredicatePrefix
-  RSpec::PathMatchers::Matchers::HaveSymlink.new(name, **options_hash)
-end
+require_relative 'path_matchers/refinements'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec-path_matchers
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.1
 platform: ruby
 authors:
 - James Couball
@@ -213,6 +213,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".vscode/settings.json"
+- ".yardopts"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
@@ -221,21 +222,24 @@ files:
 - design.rb
 - lib/rspec/path_matchers.rb
 - lib/rspec/path_matchers/matchers/base.rb
-- lib/rspec/path_matchers/matchers/directory_contents_inspector.rb
-- lib/rspec/path_matchers/matchers/have_directory.rb
-- lib/rspec/path_matchers/matchers/have_file.rb
-- lib/rspec/path_matchers/matchers/have_no_entry.rb
-- lib/rspec/path_matchers/matchers/have_symlink.rb
+- lib/rspec/path_matchers/matchers/directory_matcher.rb
+- lib/rspec/path_matchers/matchers/file_matcher.rb
+- lib/rspec/path_matchers/matchers/no_entry_matcher.rb
+- lib/rspec/path_matchers/matchers/symlink_matcher.rb
 - lib/rspec/path_matchers/options.rb
 - lib/rspec/path_matchers/options/atime.rb
+- lib/rspec/path_matchers/options/base.rb
 - lib/rspec/path_matchers/options/birthtime.rb
 - lib/rspec/path_matchers/options/content.rb
 - lib/rspec/path_matchers/options/ctime.rb
+- lib/rspec/path_matchers/options/etc_base.rb
+- lib/rspec/path_matchers/options/file_stat_base.rb
 - lib/rspec/path_matchers/options/group.rb
 - lib/rspec/path_matchers/options/json_content.rb
 - lib/rspec/path_matchers/options/mode.rb
 - lib/rspec/path_matchers/options/mtime.rb
 - lib/rspec/path_matchers/options/owner.rb
+- lib/rspec/path_matchers/options/parsed_content_base.rb
 - lib/rspec/path_matchers/options/size.rb
 - lib/rspec/path_matchers/options/symlink_atime.rb
 - lib/rspec/path_matchers/options/symlink_birthtime.rb
@@ -247,6 +251,7 @@ files:
 - lib/rspec/path_matchers/options/symlink_target_exist.rb
 - lib/rspec/path_matchers/options/symlink_target_type.rb
 - lib/rspec/path_matchers/options/yaml_content.rb
+- lib/rspec/path_matchers/refinements.rb
 - lib/rspec/path_matchers/version.rb
 - package.json
 - release-please-config.json
@@ -256,8 +261,8 @@ licenses:
 metadata:
   homepage_uri: https://github.com/main-branch/rspec-path_matchers
   source_code_uri: https://github.com/main-branch/rspec-path_matchers
-  documentation_uri: https://rubydoc.info/gems/rspec-path_matchers/0.1.1
-  changelog_uri: https://rubydoc.info/gems/rspec-path_matchers/0.1.1/file/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/rspec-path_matchers/0.2.1
+  changelog_uri: https://rubydoc.info/gems/rspec-path_matchers/0.2.1/file/CHANGELOG.md
   allowed_push_host: https://rubygems.org
   rubygems_mfa_required: 'true'
 rdoc_options: []

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

@@ -1,57 +0,0 @@
-# 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

@@ -1,126 +0,0 @@
-# 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_no_entry.rb

@@ -1,49 +0,0 @@
-# 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