feat!: change how expectations are nested for have_dir and be_dir

Instead of setting expectations on directory contents using a block like this:

```ruby
expect('lib').to(
  be_dir do
    file('file1.txt')
    file('file2.txt')
  end
)
```

You now call the `#containing` method on the matcher like this:

```ruby
expect('lib').to(
  be_dir.containing(
    file('file1.txt'),
    file('file2.txt')
  )
)
```

BREAKING CHANGE: You must use `#containing` to to set expectations on dir content instead of a block

Author: jcouball

README.md

@@ -8,10 +8,10 @@ Status](https://img.shields.io/github/actions/workflow/status/main-branch/rspec-
 License](https://img.shields.io/badge/license-MIT-green)](https://opensource.org/licenses/MIT)
 
 - [Summary](#summary)
-- [Added Value](#added-value)
+- [Added Value Over Standard RSpec Matchers](#added-value-over-standard-rspec-matchers)
 - [Installation](#installation)
 - [Setup](#setup)
-- [Usage \& Examples](#usage--examples)
+- [Usage And Examples](#usage-and-examples)
   - [Basic Assertions](#basic-assertions)
   - [Negative Assertions (Checking for Absence)](#negative-assertions-checking-for-absence)
   - [File Content Assertions](#file-content-assertions)
@@ -35,43 +35,27 @@ file tree and its properties within your specs. For example:
 ```ruby
 require 'rspec/path_matchers'
 
-RSpec.describe 'Generated Project' do
+RSpec.describe 'The newly generated project' do
   it "should contain project files" do
     project_dir = Dir.pwd
 
     expect(project_dir).to(
-      be_dir do
-        file("README.md", content: /MyProject/, birthtime: within(10_000).of(Time.now))
-        dir("lib", exact: true) do
-          file("my_project.rb")
-          dir("my_project", exact: true) do
+      be_dir.containing(
+        file("README.md", content: include('MyProject'), birthtime: within(10_000).of(Time.now)),
+        dir("lib").containing_exactly(
+          file("my_project.rb"),
+          dir("my_project").containing_exactly(
             file("version.rb", content: include('VERSION = "0.1.0"'), size: be < 1000)
-          end
-        end
-      end
+          )
+        ),
+        no_dir_named('tmp')
+      )
     )
   end
 end
 ```
 
-Coming soon. Plan to change the interface to use `containing` or `containing_exactly` rather than
-nested blocks and the `exact:` option:
-
-```ruby
-expect(project_dir).to(
-  be_dir.containing(
-    file("README.md", content: /MyProject/, birthtime: within(10_000).of(Time.now)),
-    dir("lib").containing_exactly(
-      file("my_project.rb"),
-      dir("my_project").containing_exactly(
-        file("version.rb", content: include('VERSION = "0.1.0"'), size: be < 1000)
-      )
-    )
-  )
-)
-```
-
-## Added Value
+## Added Value Over Standard RSpec Matchers
 
 Here’s a breakdown of the value this API provides over what is available in standard
 RSpec.
@@ -153,15 +137,17 @@ With this API:
 
 ```ruby
 # This is a clear, hierarchical specification of the directory's contents.
-expect('/etc/service').to(have_dir('nginx') do
-    file('run')
-    dir('log')
-    no_file('down')
-end)
+expect('/etc/service/nginx').to(
+  be_dir.containing(
+    file('run'),
+    dir('log'),
+    no_file_named('down')
+  )
+)
 ```
 
-The nested block is a leap in expressiveness and power, allowing you to write
-complex integration and infrastructure tests with ease.
+The nested `containing` matchers allows you to write tests that humans
+can make sense of.
 
 <h3>4. Descriptive and Intelligible Failure Messages</h3>
 
@@ -183,8 +169,18 @@ what went wrong.
 You get a detailed, hierarchical report that shows the full expectation and
 clearly marks what failed.
 
+For this expectation:
+
+```ruby
+expect('config').to(
+  be_dir.containing(
+    file('database.xml', owner: 'db_user', mode: '0600')
+  )
+)
+```
+
 ```text
-the entry 'my-app' at '/tmp/d20250622-12345-abcdef' was expected to satisfy the following but did not:
+'/tmp/d20250622-12345-abcdef/my-app' was expected to satisfy the following but did not:
 - have directory "config" containing:
     - have file "database.yml" with owner "db_user" and mode "0600"
     - expected owner to be "db_user", but was "root"
@@ -222,7 +218,7 @@ Require the gem in your `spec/spec_helper.rb` file:
 require 'rspec/path_matchers'
 ```
 
-## Usage & Examples
+## Usage And Examples
 
 All matchers operate on a base path, making your tests clean and portable.
 
@@ -359,7 +355,7 @@ end
 
 The block syntax is the most powerful feature. It allows you to describe and verify
 an entire file tree, including both the presence and *absence* of entries using
-methods like `no_file`, `no_dir`, and `no_symlink`.
+methods like `no_dir_named`, `no_file_named`, and `no_symlink_named`.
 
 ```ruby
 before do
@@ -395,7 +391,7 @@ it "validates a nested directory structure" do
     dir "log"
 
     # Assert the absence of other entries at the root of 'my-app'
-    no_dir "tmp"
+    no_dir_named "tmp"
     no_file "README.md"
   end)
 end

design.rb

@@ -47,17 +47,17 @@
 
 # Nested directory checks ()
 expect(path).to(
-  have_dir(name) do
-    file('nested_file.txt', content: 'expected content')
-    dir('nested_dir') do
+  have_dir(name).containing(
+    file('nested_file.txt', content: 'expected content'),
+    symlink('nested_symlink', target: 'expected_target'),
+    no_file_named('non_existent_file.txt'),
+    no_dir_named('non_existent_dir'),
+    no_symlink_named('non_existent_symlink'),
+    no_entry_named('non_existent_entry'),
+    dir('nested_dir').containing_exactly(
       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
+    )
+  )
 )
 
 ########################################

lib/rspec/path_matchers.rb

@@ -22,18 +22,41 @@ def self.matcher?(object)
 
 require_relative 'path_matchers/refinements'
 
-def be_dir(**options_hash, &)
-  RSpec::PathMatchers::Matchers::HaveDirectory.new('', matcher_name: __method__, **options_hash, &)
-end
+module RSpec
+  # RSpec::PathMatchers is a collection of matchers for testing directory entries
+  module PathMatchers
+    def be_dir(**options_hash)
+      RSpec::PathMatchers::Matchers::HaveDirectory.new('', matcher_name: __method__, **options_hash)
+    end
 
-def have_file(name, **options_hash) # rubocop:disable Naming/PredicatePrefix
-  RSpec::PathMatchers::Matchers::HaveFile.new(name, matcher_name: __method__, **options_hash)
-end
+    def have_file(name, **options_hash) # rubocop:disable Naming/PredicatePrefix
+      RSpec::PathMatchers::Matchers::HaveFile.new(name, matcher_name: __method__, **options_hash)
+    end
 
-def have_dir(name, **options_hash, &) # rubocop:disable Naming/PredicatePrefix
-  RSpec::PathMatchers::Matchers::HaveDirectory.new(name, matcher_name: __method__, **options_hash, &)
-end
+    alias file have_file
+
+    def have_dir(name, **options_hash) # rubocop:disable Naming/PredicatePrefix
+      RSpec::PathMatchers::Matchers::HaveDirectory.new(name, matcher_name: __method__, **options_hash)
+    end
 
-def have_symlink(name, **options_hash) # rubocop:disable Naming/PredicatePrefix
-  RSpec::PathMatchers::Matchers::HaveSymlink.new(name, matcher_name: __method__, **options_hash)
+    alias dir have_dir
+
+    def have_symlink(name, **options_hash) # rubocop:disable Naming/PredicatePrefix
+      RSpec::PathMatchers::Matchers::HaveSymlink.new(name, matcher_name: __method__, **options_hash)
+    end
+
+    alias symlink have_symlink
+
+    def no_dir_named(name)
+      RSpec::PathMatchers::Matchers::HaveNoEntry.new(name, entry_type: :directory)
+    end
+
+    def no_file_named(name)
+      RSpec::PathMatchers::Matchers::HaveNoEntry.new(name, entry_type: :file)
+    end
+
+    def no_symlink_named(name)
+      RSpec::PathMatchers::Matchers::HaveNoEntry.new(name, entry_type: :symlink)
+    end
+  end
 end

lib/rspec/path_matchers/matchers/directory_contents_inspector.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative 'directory_contents_inspector'
 
 module RSpec
   module PathMatchers
@@ -21,7 +20,35 @@ class HaveDirectory < Base
 
         def entry_type = :directory
 
-        attr_reader :nested_matchers, :exact
+        # 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<Array<RSpec::PathMatchers::Matchers::Base>>]
+        #
+        def nested_matchers
+          @nested_matchers.first || []
+        end
+
+        # @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
         #
@@ -33,21 +60,27 @@ def entry_type = :directory
         #
         # @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)
+        def initialize(name, **options_hash)
+          super
 
-          @exact = exact
+          @exact = false
           @nested_matchers = []
-          return unless specification_block
+        end
+
+        def containing(*matchers)
+          @nested_matchers << matchers
+          @exact = false
+          self
+        end
 
-          inspector = DirectoryContentsInspector.new
-          inspector.instance_eval(&specification_block)
-          @nested_matchers = inspector.nested_matchers
+        def containing_exactly(*matchers)
+          @nested_matchers << matchers
+          @exact = true
+          self
         end
 
         def description
           desc = super
-          desc += ' exactly' if exact
           return desc if nested_matchers.empty?
 
           nested_descriptions = nested_matchers.map do |matcher|
@@ -56,20 +89,22 @@ def description
             end.join("\n")
           end
 
-          "#{desc} containing:\n  #{nested_descriptions.join("\n  ")}"
+          "#{desc} containing#{' exactly' if exact}:\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"
+          errors << "The matcher `not_to #{matcher_name}(...)` cannot have expectations on its contents"
         end
 
         def collect_validation_errors(errors)
           super
 
-          errors << "`exact:` must be true or false, but was #{exact.inspect}" unless [true, false].include?(exact)
+          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) }