fix 0.19 → 0.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e44836a2e867dcb513bc3daffa30c6c319e18602be1c4cf0e098d14f7ae4f9b
-  data.tar.gz: 70029c70b7efd078c5d4cafdcdacd1921a2c081e1637f7f2cbc867bfde839781
+  metadata.gz: a61d6e74ba8d919c935036f602b4ac3bdf4ec121a9880cb6168d16893384e194
+  data.tar.gz: 1060db9d560d9288af75686c51bf6acbc38fb29606b3d451493f39548795744f
 SHA512:
-  metadata.gz: f18450b4cc887e269471c529e95816537f620e342733a3441091b01709feaf44d7f1fe46e7ea2b228f5eca154f410de0e03456f238aa642e2a35ff1d55aa5376
-  data.tar.gz: 3854f42a81ddece26f7e9b7d33d347caf37c885cb65ea1e17910032c279c249aefa6ff73d3b7dccfd205d5824812d72564c79d2b76cc7d0afd2e2c51ad08428e
+  metadata.gz: 19f6f8612289b9e23bcda11fd20ee039591a8270b1dbec962474261f45e72784ed6e4ab414ecb2e13280095ca349017eb56c3076f4bddf8bc1b5144a44a6880a
+  data.tar.gz: 1a8a4b2181814fbd064559a726cd7a41f6fa1079c9f58fc8babc4d54f539ead621ede997a24754e404e5dc64a37a2e138db07e52df1a9bfb9c6d8c939815abcd

data/lib/fix/doc.rb

@@ -3,50 +3,109 @@
 require_relative "error/invalid_specification_name"
 
 module Fix
-  # Module for storing and managing specification documents.
+  # The Doc module serves as a central registry for storing and managing test specifications.
+  # It provides functionality for:
+  # - Storing specification classes in a structured way
+  # - Managing the lifecycle of specification documents
+  # - Extracting test specifications from context objects
+  # - Validating specification names
   #
-  # This module acts as a registry for specification classes and handles
-  # the extraction of test specifications from context objects.
+  # The module acts as a namespace for specifications, allowing them to be:
+  # - Registered with unique names
+  # - Retrieved by name when needed
+  # - Protected from name collisions
+  # - Organized in a hierarchical structure
+  #
+  # @example Registering a new specification
+  #   Fix::Doc.add(:Calculator, calculator_specification_class)
+  #
+  # @example Retrieving specification contexts
+  #   contexts = Fix::Doc.fetch(:Calculator)
+  #   specifications = Fix::Doc.extract_specifications(*contexts)
   #
   # @api private
   module Doc
-    # Retrieves the contexts array for a named specification.
+    # Retrieves the array of test contexts associated with a named specification.
+    # These contexts define the test environment and requirements for the specification.
     #
-    # @param name [String, Symbol] The constant name of the specification
+    # @param name [Symbol] The name of the specification to retrieve
     # @return [Array<Fix::Dsl>] Array of context classes for the specification
-    # @raise [NameError] If specification constant is not found
+    # @raise [NameError] If the specification name doesn't exist in the registry
+    #
+    # @example Retrieving contexts for a calculator specification
+    #   contexts = Fix::Doc.fetch(:Calculator)
+    #   contexts.each do |context|
+    #     # Process each context...
+    #   end
+    #
+    # @api private
     def self.fetch(name)
       const_get("#{name}::CONTEXTS")
     end
 
-    # Extracts test specifications from a list of context classes.
-    # Each specification consists of an environment and its associated test data.
+    # Extracts complete test specifications from a list of context classes.
+    # This method processes contexts to build a list of executable test specifications.
+    #
+    # Each extracted specification contains:
+    # - The test environment
+    # - The source file location
+    # - The requirement level (MUST, SHOULD, or MAY)
+    # - The list of challenges to execute
     #
     # @param contexts [Array<Fix::Dsl>] List of context classes to process
-    # @return [Array<Array>] Array of arrays where each sub-array contains:
-    #   - [0] environment: The test environment instance
-    #   - [1] location: The test file location (as "path:line")
-    #   - [2] requirement: The test requirement (MUST, SHOULD, or MAY)
-    #   - [3] challenges: Array of test challenges to execute
+    # @return [Array<Array>] Array of specification arrays where each contains:
+    #   - [0] environment [Fix::Dsl] The test environment instance
+    #   - [1] location [String] The test file location ("path:line")
+    #   - [2] requirement [Object] The test requirement (MUST, SHOULD, or MAY)
+    #   - [3] challenges [Array] Array of test challenges to execute
+    #
+    # @example Extracting specifications from contexts
+    #   contexts = Fix::Doc.fetch(:Calculator)
+    #   specifications = Fix::Doc.extract_specifications(*contexts)
+    #   specifications.each do |env, location, requirement, challenges|
+    #     # Process each specification...
+    #   end
+    #
+    # @api private
     def self.extract_specifications(*contexts)
       contexts.flat_map do |context|
         extract_context_specifications(context)
       end
     end
 
-    # Registers a new specification class under the given name.
+    # Registers a new specification class under the given name in the registry.
+    # The name must be a valid Ruby constant name to ensure proper namespace organization.
     #
-    # @param name [String, Symbol] Name to register the specification under
+    # @param name [Symbol] The name to register the specification under
     # @param klass [Class] The specification class to register
     # @raise [Fix::Error::InvalidSpecificationName] If name is not a valid constant name
     # @return [void]
-    def self.spec_set(name, klass)
+    #
+    # @example Adding a new specification
+    #   class CalculatorSpec < Fix::Dsl
+    #     # specification implementation...
+    #   end
+    #   Fix::Doc.add(:Calculator, CalculatorSpec)
+    #
+    # @example Invalid name handling
+    #   # This will raise Fix::Error::InvalidSpecificationName
+    #   Fix::Doc.add(:"invalid-name", some_class)
+    #
+    # @api private
+    def self.add(name, klass)
       const_set(name, klass)
     rescue ::NameError => _e
       raise Error::InvalidSpecificationName, name
     end
 
-    # @private
+    # Extracts test specifications from a single context class.
+    # This method processes public methods in the context to build
+    # a list of executable test specifications.
+    #
+    # @param context [Fix::Dsl] The context class to process
+    # @return [Array<Array>] Array of specification arrays
+    #
+    # @api private
     def self.extract_context_specifications(context)
       env = context.new
       env.public_methods(false).map do |public_method|

data/lib/fix/error/missing_subject_block.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Fix
+  module Error
+    # Error raised when attempting to test a specification without providing a subject block
+    class MissingSubjectBlock < ::ArgumentError
+      MISSING_BLOCK_ERROR = "Subject block is required for testing a specification. " \
+                            "Use: test { subject } or match? { subject }"
+
+      def initialize
+        super(MISSING_BLOCK_ERROR)
+      end
+    end
+  end
+end

data/lib/fix/set.rb

@@ -1,67 +1,224 @@
 # frozen_string_literal: true
 
-require "English"
-
 require_relative "doc"
+require_relative "dsl"
 require_relative "run"
+require_relative "error/missing_subject_block"
 
 module Fix
-  # Collection of specifications.
+  # A Set represents a collection of test specifications that can be executed as a test suite.
+  # It manages the lifecycle of specifications, including:
+  # - Building and loading specifications from contexts
+  # - Executing specifications in isolation using process forking
+  # - Reporting test results
+  # - Managing test execution flow and exit status
+  #
+  # @example Creating and running a simple test set
+  #   set = Fix::Set.build(:Calculator) do
+  #     on(:add, 2, 3) do
+  #       it MUST eq 5
+  #     end
+  #   end
+  #   set.test { Calculator.new }
+  #
+  # @example Loading and running a registered test set
+  #   set = Fix::Set.load(:Calculator)
+  #   set.match? { Calculator.new } #=> true
   #
   # @api private
   class Set
-    # @return [Array] A list of specifications.
-    attr_reader :specs
+    # Builds a new Set from a specification block.
+    #
+    # This method:
+    # 1. Creates a new DSL class for the specification
+    # 2. Evaluates the specification block in this context
+    # 3. Optionally registers the specification under a name
+    # 4. Returns a Set instance ready for testing
+    #
+    # @param name [Symbol, nil] Optional name to register the specification under
+    # @yield Block containing the specification definition using Fix DSL
+    # @return [Fix::Set] A new specification set ready for testing
+    #
+    # @example Building a named specification
+    #   Fix::Set.build(:Calculator) do
+    #     on(:add, 2, 3) { it MUST eq 5 }
+    #   end
+    #
+    # @example Building an anonymous specification
+    #   Fix::Set.build(nil) do
+    #     it MUST be_positive
+    #   end
+    #
+    # @api private
+    def self.build(name, &block)
+      klass = ::Class.new(Dsl)
+      klass.const_set(:CONTEXTS, [klass])
+      klass.instance_eval(&block)
+      Doc.const_set(name, klass) unless name.nil?
+      new(*klass.const_get(:CONTEXTS))
+    end
 
-    # Load specifications from a constant name.
+    # Loads a previously registered specification set by name.
     #
-    # @param name [String, Symbol] The constant name of the specifications.
-    # @return [Set] A new Set instance containing the loaded specifications.
+    # @param name [Symbol] The name of the registered specification
+    # @return [Fix::Set] The loaded specification set
+    # @raise [NameError] If the specification name is not found
     #
-    # @api public
+    # @example Loading a registered specification
+    #   Fix::Set.load(:Calculator)  #=> #<Fix::Set:...>
+    #
+    # @api private
     def self.load(name)
       new(*Doc.fetch(name))
     end
 
-    # Initialize a new Set with given contexts.
+    # Initializes a new Set with given test contexts.
     #
-    # @param contexts [Array<::Fix::Dsl>] The list of contexts document.
+    # The contexts are processed to extract test specifications and
+    # randomized to ensure test isolation and catch order dependencies.
+    #
+    # @param contexts [Array<Fix::Dsl>] List of specification contexts to include
+    #
+    # @example Creating a set with multiple contexts
+    #   Fix::Set.new(base_context, admin_context, guest_context)
     def initialize(*contexts)
-      @specs = Doc.extract_specifications(*contexts).shuffle
+      @expected = Doc.extract_specifications(*contexts).shuffle
     end
 
-    # Run the test suite against the provided subject.
+    # Verifies if a subject matches all specifications without exiting.
+    #
+    # This method is useful for:
+    # - Conditional testing where exit on failure is not desired
+    # - Integration into larger test suites
+    # - Programmatic test result handling
+    #
+    # @yield Block that returns the subject to test
+    # @yieldreturn [Object] The subject to test against specifications
+    # @return [Boolean] true if all tests pass, false otherwise
+    # @raise [Error::MissingSubjectBlock] If no subject block is provided
+    #
+    # @example Basic matching
+    #   set.match? { Calculator.new }  #=> true
     #
-    # @yield The block of code to be tested
-    # @yieldreturn [Object] The result of the code being tested
-    # @return [Boolean] true if all tests pass, exits with false otherwise
-    # @raise [::SystemExit] The test set failed!
+    # @example Conditional testing
+    #   if set.match? { user_input }
+    #     process_valid_input(user_input)
+    #   else
+    #     handle_invalid_input
+    #   end
     #
     # @api public
-    def test(&)
-      suite_passed?(&) || ::Kernel.exit(false)
+    def match?(&subject)
+      raise Error::MissingSubjectBlock unless subject
+
+      expected.all? { |spec| run_spec(*spec, &subject) }
     end
 
-    private
+    # Executes the complete test suite against a subject.
+    #
+    # This method provides a comprehensive test run that:
+    # - Executes all specifications in random order
+    # - Runs each test in isolation via process forking
+    # - Reports results for each specification
+    # - Exits with appropriate status code
+    #
+    # @yield Block that returns the subject to test
+    # @yieldreturn [Object] The subject to test against specifications
+    # @return [Boolean] true if all tests pass
+    # @raise [SystemExit] Exits with status 1 if any test fails
+    # @raise [Error::MissingSubjectBlock] If no subject block is provided
+    #
+    # @example Basic test execution
+    #   set.test { Calculator.new }
+    #
+    # @example Testing with dependencies
+    #   set.test {
+    #     calc = Calculator.new
+    #     calc.precision = :high
+    #     calc
+    #   }
+    #
+    # @api public
+    def test(&subject)
+      match?(&subject) || exit_with_failure
+    end
 
-    def suite_passed?(&subject)
-      specs.all? { |spec| run_spec(*spec, &subject) }
+    # Returns a string representation of the test set.
+    #
+    # @return [String] Human-readable description of the test set
+    #
+    # @example
+    #   set.to_s #=> "fix [<specification list>]"
+    #
+    # @api public
+    def to_s
+      "fix #{expected.inspect}"
     end
 
+    private
+
+    # List of specifications to be tested.
+    # Each specification is an array containing:
+    # - [0] environment: Fix::Dsl instance for test context
+    # - [1] location: String indicating source file and line
+    # - [2] requirement: Test requirement (MUST, SHOULD, or MAY)
+    # - [3] challenges: Array of test challenges to execute
+    #
+    # @return [Array<Array>] List of specification arrays
+    attr_reader :expected
+
+    # Executes a single specification in an isolated process.
+    #
+    # @param env [Fix::Dsl] Test environment instance
+    # @param location [String] Source location (file:line)
+    # @param requirement [Object] Test requirement
+    # @param challenges [Array] Test challenges
+    # @yield Block returning the subject to test
+    # @return [Boolean] true if specification passed
     def run_spec(env, location, requirement, challenges, &subject)
-      ::Process.fork { lab(env, location, requirement, challenges, &subject) }
-      ::Process.wait
-      $CHILD_STATUS.success?
+      child_pid = ::Process.fork { execute_spec(env, location, requirement, challenges, &subject) }
+      _pid, process_status = ::Process.wait2(child_pid)
+      process_status.success?
+    end
+
+    # Executes a specification in the current process.
+    #
+    # @param env [Fix::Dsl] Test environment instance
+    # @param location [String] Source location (file:line)
+    # @param requirement [Object] Test requirement
+    # @param challenges [Array] Test challenges
+    # @yield Block returning the subject to test
+    # @return [void]
+    def execute_spec(env, location, requirement, challenges, &subject)
+      result = Run.new(env, requirement, *challenges).test(&subject)
+      report_result(location, result)
+      exit_with_status(result.passed?)
     end
 
-    def lab(env, location, requirement, challenges, &)
-      result = Run.new(env, requirement, *challenges).test(&)
-      report!(location, result)
-      ::Kernel.exit(result.passed?)
+    # Reports the result of a specification execution.
+    #
+    # @param location [String] Source location (file:line)
+    # @param result [Object] Test execution result
+    # @return [void]
+    def report_result(location, result)
+      puts "#{location} #{result.colored_string}"
     end
 
-    def report!(path, result)
-      puts "#{path} #{result.colored_string}"
+    # Exits the process with a failure status.
+    #
+    # @return [void]
+    # @raise [SystemExit] Always exits with status 1
+    def exit_with_failure
+      ::Kernel.exit(false)
+    end
+
+    # Exits the process with the given status.
+    #
+    # @param status [Boolean] Exit status to use
+    # @return [void]
+    # @raise [SystemExit] Always exits with provided status
+    def exit_with_status(status)
+      ::Kernel.exit(status)
     end
   end
 end

data/lib/fix.rb

@@ -1,93 +1,179 @@
 # frozen_string_literal: true
 
 require_relative "fix/doc"
+require_relative "fix/error/missing_specification_block"
 require_relative "fix/error/specification_not_found"
 require_relative "fix/set"
 require_relative "kernel"
 
-# Namespace for the Fix framework.
+# The Fix framework namespace provides core functionality for managing and running test specifications.
+# Fix offers a unique approach to testing by clearly separating specifications from their implementations.
 #
-# Provides core functionality for managing and running test specifications.
-# Fix supports two modes of operation:
-# 1. Named specifications that can be referenced later
-# 2. Anonymous specifications for immediate testing
+# Fix supports two primary modes of operation:
+# 1. Named specifications that can be stored and referenced later
+# 2. Anonymous specifications for immediate one-time testing
 #
-# @example Creating and running a named specification
-#   Fix :Answer do
-#     it MUST equal 42
+# Available matchers through the Matchi library include:
+# - Basic Comparison: eq, eql, be, equal
+# - Type Checking: be_an_instance_of, be_a_kind_of
+# - State & Changes: change(object, method).by(n), by_at_least(n), by_at_most(n), from(old).to(new), to(new)
+# - Value Testing: be_within(delta).of(value), match(regex), satisfy { |value| ... }
+# - Exceptions: raise_exception(class)
+# - State Testing: be_true, be_false, be_nil
+# - Predicate Matchers: be_*, have_*  (e.g., be_empty, have_key)
+#
+# @example Creating and running a named specification with various matchers
+#   Fix :Calculator do
+#     on(:add, 0.1, 0.2) do
+#       it SHOULD be 0.3                     # Technically true but fails due to floating point precision
+#       it MUST be_an_instance_of(Float)     # Type checking
+#       it MUST be_within(0.0001).of(0.3)    # Proper floating point comparison
+#     end
+#
+#     on(:divide, 1, 0) do
+#       it MUST raise_exception ZeroDivisionError  # Exception testing
+#     end
+#   end
+#
+#   Fix[:Calculator].test { Calculator.new }
+#
+# @example Using state change matchers
+#   Fix :UserAccount do
+#     on(:deposit, 100) do
+#       it MUST change(account, :balance).by(100)
+#       it SHOULD change(account, :updated_at)
+#     end
+#
+#     on(:update_status, :premium) do
+#       it MUST change(account, :status).from(:basic).to(:premium)
+#     end
+#   end
+#
+# @example Using predicate matchers
+#   Fix :Collection do
+#     with items: [] do
+#       it MUST be_empty          # Tests empty?
+#       it MUST_NOT have_errors   # Tests has_errors?
+#     end
 #   end
 #
-#   Fix[:Answer].test { 42 }
+# @example Complete specification with multiple matchers
+#   Fix :Product do
+#     let(:price) { 42.99 }
 #
-# @example Creating and running an anonymous specification
-#   Fix do
-#     it MUST be_positive
-#   end.test { 42 }
+#     it MUST be_an_instance_of Product     # Type checking
+#     it MUST_NOT be_nil                    # Nil checking
 #
-# @see Fix::Set
-# @see Fix::Builder
+#     on(:price) do
+#       it MUST be_within(0.01).of(42.99)   # Floating point comparison
+#     end
+#
+#     with category: "electronics" do
+#       it MUST satisfy { |p| p.valid? }    # Custom validation
+#
+#       on(:save) do
+#         it MUST change(product, :updated_at)  # State change
+#         it SHOULD_NOT raise_exception         # Exception checking
+#       end
+#     end
+#   end
+#
+# @see Fix::Set For managing collections of specifications
+# @see Fix::Doc For storing and retrieving specifications
+# @see Fix::Dsl For the domain-specific language used in specifications
+# @see Fix::Matcher For the complete list of available matchers
 #
 # @api public
 module Fix
-  class << self
-    # Retrieves and loads a built specification for testing.
-    #
-    # @example Run a named specification
-    #   Fix[:Answer].test { 42 }
-    #
-    # @param name [String, Symbol] The constant name of the specification
-    # @return [Fix::Set] The loaded specification set ready for testing
-    # @raise [Fix::Error::SpecificationNotFound] If the named specification doesn't exist
-    def [](name)
-      name = normalize_name(name)
-      validate_specification_exists!(name)
-      Set.load(name)
-    end
+  # Creates a new specification set, optionally registering it under a name.
+  #
+  # @param name [Symbol, nil] Optional name to register the specification under.
+  #   If nil, creates an anonymous specification for immediate use.
+  # @yieldreturn [void] Block containing the specification definition using Fix DSL
+  # @return [Fix::Set] A new specification set ready for testing
+  # @raise [Fix::Error::MissingSpecificationBlock] If no block is provided
+  #
+  # @example Create a named specification
+  #   Fix :StringValidator do
+  #     on(:validate, "hello@example.com") do
+  #       it MUST be_valid_email
+  #       it MUST satisfy { |result| result.errors.empty? }
+  #     end
+  #   end
+  #
+  # @example Create an anonymous specification
+  #   Fix do
+  #     it MUST be_positive
+  #     it MUST be_within(0.1).of(42.0)
+  #   end.test { 42 }
+  #
+  # @api public
+  def self.spec(name = nil, &block)
+    raise Error::MissingSpecificationBlock if block.nil?
 
-    # Lists all defined specification names.
-    #
-    # @example Get all specification names
-    #   Fix.specification_names #=> [:Answer, :Calculator, :UserProfile]
-    #
-    # @return [Array<Symbol>] Sorted array of specification names
-    def specification_names
-      Doc.constants.sort
-    end
-
-    # Checks if a specification is defined.
-    #
-    # @example Check for specification existence
-    #   Fix.spec_defined?(:Answer) #=> true
-    #
-    # @param name [String, Symbol] Name of the specification to check
-    # @return [Boolean] true if specification exists, false otherwise
-    def spec_defined?(name)
-      specification_names.include?(normalize_name(name))
-    end
+    Set.build(name, &block)
+  end
 
-    private
+  # Retrieves a previously registered specification by name.
+  #
+  # @param name [Symbol] The constant name of the specification to retrieve
+  # @return [Fix::Set] The loaded specification set ready for testing
+  # @raise [Fix::Error::SpecificationNotFound] If the named specification doesn't exist
+  #
+  # @example
+  #   # Define a specification with multiple matchers
+  #   Fix :EmailValidator do
+  #     on(:validate, "test@example.com") do
+  #       it MUST be_valid
+  #       it MUST_NOT raise_exception
+  #       it SHOULD satisfy { |result| result.score > 0.8 }
+  #     end
+  #   end
+  #
+  #   # Later, retrieve and use it
+  #   Fix[:EmailValidator].test { MyEmailValidator }
+  #
+  # @see #spec For creating new specifications
+  # @see Fix::Set#test For running tests against a specification
+  # @see Fix::Matcher For available matchers
+  #
+  # @api public
+  def self.[](name)
+    raise Error::SpecificationNotFound, name unless key?(name)
 
-    # Converts any specification name into a symbol.
-    # This allows for consistent name handling regardless of input type.
-    #
-    # @param name [String, Symbol] The name to normalize
-    # @return [Symbol] The normalized name
-    # @example
-    #   normalize_name("Answer") #=> :Answer
-    #   normalize_name(:Answer)  #=> :Answer
-    def normalize_name(name)
-      String(name).to_sym
-    end
+    Set.load(name)
+  end
 
-    # Verifies the existence of a specification and raises an error if not found.
-    # This ensures early failure when attempting to use undefined specifications.
-    #
-    # @param name [Symbol] The specification name to validate
-    # @raise [Fix::Error::SpecificationNotFound] If specification doesn't exist
-    def validate_specification_exists!(name)
-      return if spec_defined?(name)
+  # Lists all defined specification names.
+  #
+  # @return [Array<Symbol>] Sorted array of registered specification names
+  #
+  # @example
+  #   Fix :First do; end
+  #   Fix :Second do; end
+  #
+  #   Fix.keys #=> [:First, :Second]
+  #
+  # @api public
+  def self.keys
+    Doc.constants.sort
+  end
 
-      raise Error::SpecificationNotFound, name
-    end
+  # Checks if a specification is registered under the given name.
+  #
+  # @param name [Symbol] The name to check for
+  # @return [Boolean] true if a specification exists with this name, false otherwise
+  #
+  # @example
+  #   Fix :Example do
+  #     it MUST be_an_instance_of(Example)
+  #   end
+  #
+  #   Fix.key?(:Example)  #=> true
+  #   Fix.key?(:Missing)  #=> false
+  #
+  # @api public
+  def self.key?(name)
+    keys.include?(name)
   end
 end

data/lib/kernel.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
-require_relative "fix/builder"
-
 # Extension of the global Kernel module to provide the Fix method.
-# This allows Fix to be called from anywhere in the application
-# without explicit namespace qualification.
+# This module provides a global entry point to the Fix testing framework,
+# allowing specifications to be defined and managed from anywhere in the application.
+#
+# The Fix method can be used in two main ways:
+# 1. Creating named specifications for reuse
+# 2. Creating anonymous specifications for immediate testing
 #
 # @api public
 module Kernel
@@ -14,35 +16,87 @@ module Kernel
   # both a namespace and a method name, following Ruby conventions for DSLs.
 
   # Defines a new test specification or creates an anonymous specification set.
-  # When a name is provided, the specification is registered globally and can
-  # be referenced later using Fix[name]. Anonymous specifications are executed
+  # When a name is provided, the specification is registered globally and can be
+  # referenced later using Fix[name]. Anonymous specifications are executed
   # immediately and cannot be referenced later.
   #
-  # @example Creating a named specification for later use
+  # Specifications can use three levels of requirements, following RFC 2119:
+  # - MUST/MUST_NOT: Absolute requirements or prohibitions
+  # - SHOULD/SHOULD_NOT: Strong recommendations that can be ignored with good reason
+  # - MAY: Optional features that can be implemented or not
+  #
+  # Available matchers include:
+  # - Basic Comparison: eq(expected), eql(expected), be(expected), equal(expected)
+  # - Type Checking: be_an_instance_of(class), be_a_kind_of(class)
+  # - State & Changes: change(object, method).by(n), by_at_least(n), by_at_most(n),
+  #                   from(old).to(new), to(new)
+  # - Value Testing: be_within(delta).of(value), match(regex),
+  #                 satisfy { |value| ... }
+  # - Exceptions: raise_exception(class)
+  # - State Testing: be_true, be_false, be_nil
+  # - Predicate Matchers: be_* (e.g., be_empty), have_* (e.g., have_key)
+  #
+  # @example Creating a named specification with multiple contexts and matchers
   #   Fix :Calculator do
   #     on(:add, 2, 3) do
-  #       it MUST equal 5
+  #       it MUST eq 5
+  #       it MUST be_an_instance_of(Integer)
   #     end
-  #   end
   #
-  #   # Later in the code:
-  #   Fix[:Calculator].test { Calculator.new }
+  #     with precision: :high do
+  #       on(:divide, 10, 3) do
+  #         it MUST be_within(0.001).of(3.333)
+  #       end
+  #     end
+  #
+  #     on(:divide, 1, 0) do
+  #       it MUST raise_exception ZeroDivisionError
+  #     end
+  #   end
   #
   # @example Creating and immediately testing an anonymous specification
   #   Fix do
   #     it MUST be_positive
+  #     it SHOULD be_even
+  #     it MAY be_prime
   #   end.test { 42 }
   #
-  # @param name [String, Symbol, nil] The constant name for the specification
-  # @yield The specification definition block
-  # @yieldreturn [void]
-  # @return [Fix::Set] A collection of specifications ready for testing
+  # @example Testing state changes
+  #   Fix :Account do
+  #     on(:deposit, 100) do
+  #       it MUST change(account, :balance).by(100)
+  #       it SHOULD change(account, :updated_at)
+  #     end
+  #
+  #     on(:withdraw, 50) do
+  #       it MUST change(account, :balance).by(-50)
+  #       it MUST_NOT change(account, :status)
+  #     end
+  #   end
+  #
+  # @example Using predicates and custom matchers
+  #   Fix :Collection do
+  #     with items: [] do
+  #       it MUST be_empty
+  #       it MUST_NOT have_errors
+  #       it SHOULD satisfy { |c| c.valid? && c.initialized? }
+  #     end
+  #   end
+  #
+  # @param name [Symbol, nil] Optional name to register the specification under
+  # @yield Block containing the specification definition using Fix DSL
+  # @return [Fix::Set] A specification set ready for testing
+  # @raise [Fix::Error::MissingSpecificationBlock] If no block is provided
+  # @raise [Fix::Error::InvalidSpecificationName] If name is not a valid constant name
+  #
+  # @see Fix::Set For managing collections of specifications
+  # @see Fix::Dsl For the domain-specific language used in specifications
+  # @see Fix::Matcher For the complete list of available matchers
+  # @see https://tools.ietf.org/html/rfc2119 For details about requirement levels
   #
-  # @see Fix::Builder
-  # @see Fix::Set
-  # @see Fix::Dsl
-  def Fix(name = nil, &)
-    ::Fix::Builder.build(name, &)
+  # @api public
+  def Fix(name = nil, &block)
+    ::Fix.spec(name, &block)
   end
 
   # rubocop:enable Naming/MethodName

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fix
 version: !ruby/object:Gem::Version
-  version: '0.19'
+  version: '0.21'
 platform: ruby
 authors:
 - Cyril Kato
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-01-01 00:00:00.000000000 Z
+date: 2025-01-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: defi
@@ -65,11 +65,11 @@ files:
 - LICENSE.md
 - README.md
 - lib/fix.rb
-- lib/fix/builder.rb
 - lib/fix/doc.rb
 - lib/fix/dsl.rb
 - lib/fix/error/invalid_specification_name.rb
 - lib/fix/error/missing_specification_block.rb
+- lib/fix/error/missing_subject_block.rb
 - lib/fix/error/specification_not_found.rb
 - lib/fix/matcher.rb
 - lib/fix/requirement.rb

data/lib/fix/builder.rb

@@ -1,101 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "doc"
-require_relative "dsl"
-require_relative "set"
-require_relative "error/missing_specification_block"
-
-module Fix
-  # Handles the creation and setup of Fix specifications.
-  #
-  # The Builder constructs new Fix specification sets following these steps:
-  # 1. Creates a new specification class inheriting from DSL
-  # 2. Defines the specification content using the provided block
-  # 3. Optionally registers the named specification
-  # 4. Returns the built specification set
-  #
-  # @example Create a named specification
-  #   Fix::Builder.build(:Calculator) do
-  #     on(:add, 2, 3) { it MUST equal 5 }
-  #   end
-  #
-  # @example Create an anonymous specification
-  #   Fix::Builder.build do
-  #     it MUST be_positive
-  #   end
-  #
-  # @see Fix::Set
-  # @see Fix::Dsl
-  # @api private
-  class Builder
-    # Creates a new specification set.
-    #
-    # @param name [String, Symbol, nil] Optional name for the specification
-    # @yieldparam [void] Block containing specification definitions
-    # @yieldreturn [void]
-    # @return [Fix::Set] The constructed specification set
-    # @raise [Fix::Error::InvalidSpecificationName] If name is invalid
-    # @raise [Fix::Error::MissingSpecificationBlock] If no block given
-    def self.build(name = nil, &block)
-      new(name, &block).construct_set
-    end
-
-    # @return [String, Symbol, nil] The name of the specification
-    attr_reader :name
-
-    def initialize(name = nil, &block)
-      raise Error::MissingSpecificationBlock unless block
-
-      @name = name
-      @block = block
-    end
-
-    # Constructs and returns a new specification set.
-    #
-    # @return [Fix::Set] The constructed specification set
-    def construct_set
-      klass = create_specification
-      populate_specification(klass)
-      register_if_named(klass)
-      build_set(klass)
-    end
-
-    private
-
-    # @return [Proc] The block containing specification definitions
-    attr_reader :block
-
-    # Creates a new specification class with context tracking.
-    #
-    # @return [Class] A new class inheriting from Fix::Dsl with CONTEXTS initialized
-    def create_specification
-      ::Class.new(Dsl).tap do |klass|
-        klass.const_set(:CONTEXTS, [klass])
-      end
-    end
-
-    # Evaluates the specification block in the context of the class.
-    #
-    # @param klass [Class] The class to populate with specifications
-    # @return [void]
-    def populate_specification(klass)
-      klass.instance_eval(&block)
-    end
-
-    # Registers the specification in Fix::Doc if a name was provided.
-    #
-    # @param klass [Class] The specification class to register
-    # @return [void]
-    def register_if_named(klass)
-      Doc.spec_set(name, klass) if name
-    end
-
-    # Creates a new specification set from the populated class.
-    #
-    # @param klass [Class] The populated specification class
-    # @return [Fix::Set] A new specification set
-    def build_set(klass)
-      Set.new(*klass.const_get(:CONTEXTS))
-    end
-  end
-end