spec_forge 0.5.0 → 0.6.0

data/lib/spec_forge/context/variables.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Context
+    #
+    # Manages variable resolution across different expectations in SpecForge tests.
+    #
+    # The Variables class handles two layers of variable definitions:
+    #   - Base variables: The core set of variables defined at the spec level
+    #   - Overlay variables: Additional variables defined at the expectation level
+    #       that can override base variables with the same name.
+    #
+    # @example Basic usage
+    #   variables = Variables.new(
+    #     base: {user_id: 123, name: "Test User"},
+    #     overlay: {
+    #       "expectation_1": {name: "Override User"}
+    #     }
+    #   )
+    #
+    #   variables[:user_id] #=> 123
+    #   variables[:name]    #=> "Test User"
+    #
+    #   variables.use_overlay("expectation_1")
+    #   variables[:name]    #=> "Override User"
+    #   variables[:user_id] #=> 123 (unchanged)
+    #
+    class Variables < Hash
+      attr_reader :base, :overlay
+
+      #
+      # Creates a new Variables container with base and overlay definitions
+      #
+      # @param base [Hash] The base set of variables (typically defined at spec level)
+      # @param overlay [Hash<String, Hash>] A hash of overlay variable sets keyed by ID
+      #
+      # @return [Variables]
+      #
+      def initialize(base: {}, overlay: {})
+        set(base:, overlay:)
+      end
+
+      #
+      # Sets the base and overlay variable hashes
+      #
+      # @param base [Hash] The new base variable hash
+      # @param overlay [Hash<String, Hash>] The new overlay variable hashes
+      #
+      # @return [self]
+      #
+      def set(base:, overlay: {})
+        @base = Attribute.from(base)
+        @overlay = overlay
+
+        resolve_into_self(@base)
+        self
+      end
+
+      #
+      # Applies a specific overlay to the base variables
+      # If the overlay doesn't exist or is empty, no changes are made.
+      #
+      # @param id [String] The ID of the overlay to apply
+      #
+      # @return [nil]
+      #
+      def use_overlay(id)
+        active = @base
+
+        if (overlay = @overlay[id]) && overlay.present?
+          active = active.deep_merge(overlay)
+        end
+
+        resolve_into_self(active)
+        self
+      end
+
+      private
+
+      def resolve_into_self(hash)
+        # Start fresh
+        clear
+
+        # Load the resolved values into self
+        hash.each do |key, value|
+          self[key] = Attribute.from(value).resolved
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/context.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module SpecForge
+  #
+  # Core data structure that maintains context during test execution
+  #
+  # Context stores and provides access to global variables, test variables, and
+  # shared state across specs.
+  # It acts as a central repository for test data during execution.
+  #
+  # @example Accessing the current context
+  #   SpecForge.context.variables[:user_id] #=> 123
+  #
+  class Context < Data.define(:global, :store, :variables)
+    #
+    # Creates a new context with default values
+    #
+    # @param global [Hash] Global variables shared across all specs
+    # @param variables [Hash] Test variables specific to the current context
+    #
+    # @return [Context] A new context instance
+    #
+    def initialize(global: {}, variables: {})
+      super(
+        global: Global.new(**global),
+        store: Store.new,
+        variables: Variables.new(**variables)
+      )
+    end
+  end
+end
+
+require_relative "context/callbacks"
+require_relative "context/global"
+require_relative "context/store"
+require_relative "context/variables"

data/lib/spec_forge/core_ext/rspec.rb

@@ -2,19 +2,37 @@
 
 return if defined?(SPEC_FORGE_INTERNAL_TESTING)
 
+#
+# RSpec's core testing framework module
+# Provides the fundamental structure and functionality for RSpec tests
+#
 module RSpec
+  #
+  # Core implementation details and extensions for RSpec
+  # Contains the fundamental building blocks of the RSpec testing framework
+  #
   module Core
+    #
+    # Handles notifications and reporting for RSpec test runs
+    # Manages how test results and metadata are processed and communicated
+    #
     module Notifications
       #
-      # I did attempt to do this without monkey patching
-      # Getting around the `rspec` word was making it difficult
+      # A monkey patch of an internal RSpec class to allow SpecForge to replace parts of
+      # RSpec's reporting output in order to provide useful feedback to the user.
+      # This replaces "rspec" in commands with "spec_forge", removes any line numbers, and
+      # ensures that failures properly report the YAML file that it occurred in.
       #
       class SummaryNotification
+        #
+        # Create an alias to RSpec original colorized_rerun_commands so it can be called at a
+        # later point.
+        #
+        alias_method :og_colorized_rerun_commands, :colorized_rerun_commands
+
         # Customizes RSpec's failure output to:
         # 1. Use 'spec_forge' instead of 'rspec' for rerun commands
         # 2. Remove line numbers since SpecForge uses dynamic spec generation
-        alias_method :og_colorized_rerun_commands, :colorized_rerun_commands
-
         def colorized_rerun_commands(colorizer)
           # Updating these at this point fixes the re-run for some failures - it depends
           failed_examples.each do |example|

data/lib/spec_forge/error.rb

@@ -1,150 +1,304 @@
 # frozen_string_literal: true
 
 module SpecForge
-  # Pass into to_sentence
-  OR_CONNECTOR = {
-    last_word_connector: ", or ",
-    two_words_connector: " or ",
-    # This is a minor performance improvement to avoid locales being loaded
-    # This will need to be removed if locales are added
-    locale: false
-  }.freeze
-
-  private_constant :OR_CONNECTOR
-
-  class Error < StandardError; end
-
   #
-  # Raised by Attribute::Faker when a provided classname does not exist in Faker
+  # Base error class for all SpecForge-specific exceptions
   #
-  class InvalidFakerClassError < Error
-    CLASS_CHECKER = DidYouMean::SpellChecker.new(
-      dictionary: Faker::Base.descendants.map { |c| c.to_s.downcase.gsub!("::", ".") }
-    )
+  class Error < StandardError
+    # Pass into to_sentence
+    OR_CONNECTOR = {
+      last_word_connector: ", or ",
+      two_words_connector: " or ",
+      # This is a minor performance improvement to avoid locales being loaded
+      # This will need to be removed if locales are added
+      locale: false
+    }.freeze
 
-    def initialize(input)
-      corrections = CLASS_CHECKER.correct(input)
+    private_constant :OR_CONNECTOR
 
-      super(<<~STRING.chomp
-        Undefined Faker class "#{input}". #{DidYouMean::Formatter.message_for(corrections)}
-
-        For available classes, please check https://github.com/faker-ruby/faker#generators.
-      STRING
+    #
+    # Raised when a provided Faker class name doesn't exist
+    # Provides helpful suggestions for similar class names
+    #
+    # @example
+    #   Attribute::Faker.new("faker.invalid.method")
+    #   # => InvalidFakerClassError: Undefined Faker class "invalid". Did you mean? name, games, ...
+    #
+    class InvalidFakerClassError < Error
+      #
+      # A spell checker for Faker classes
+      #
+      # @return [DidYouMean::SpellChecker]
+      #
+      CLASS_CHECKER = DidYouMean::SpellChecker.new(
+        dictionary: Faker::Base.descendants.map { |c| c.to_s.downcase.gsub!("::", ".") }
       )
+
+      def initialize(input)
+        corrections = CLASS_CHECKER.correct(input)
+
+        super(<<~STRING.chomp
+          Undefined Faker class "#{input}". #{DidYouMean::Formatter.message_for(corrections)}
+
+          For available classes, please check https://github.com/faker-ruby/faker#generators.
+        STRING
+        )
+      end
     end
-  end
 
-  #
-  # Raised by Attribute::Faker when a provided method for a Faker class does not exist.
-  #
-  class InvalidFakerMethodError < Error
-    def initialize(input, klass)
-      spell_checker = DidYouMean::SpellChecker.new(dictionary: klass.public_methods)
-      corrections = spell_checker.correct(input)
+    #
+    # Raised when a provided method for a Faker class doesn't exist
+    # Provides helpful suggestions for similar method names
+    #
+    # @example
+    #   Attribute::Faker.new("faker.name.invlaid")
+    #   # => InvalidFakerMethodError: Undefined Faker method "invlaid" for "Faker::Name".
+    #                                 Did you mean? first_name, last_name, ...
+    #
+    class InvalidFakerMethodError < Error
+      def initialize(input, klass)
+        spell_checker = DidYouMean::SpellChecker.new(dictionary: klass.public_methods)
+        corrections = spell_checker.correct(input)
 
-      super(<<~STRING.chomp
-        Undefined Faker method "#{input}" for "#{klass}". #{DidYouMean::Formatter.message_for(corrections)}
+        super(<<~STRING.chomp
+          Undefined Faker method "#{input}" for "#{klass}". #{DidYouMean::Formatter.message_for(corrections)}
 
-        For available methods for this class, please check https://github.com/faker-ruby/faker#generators.
-      STRING
-      )
+          For available methods for this class, please check https://github.com/faker-ruby/faker#generators.
+        STRING
+        )
+      end
     end
-  end
 
-  #
-  # Raised by Attribute::Transform when the provided transform function is not valid
-  #
-  class InvalidTransformFunctionError < Error
-    def initialize(input)
-      # TODO: Update link to docs
-      super(<<~STRING.chomp
-        Undefined transform function "#{input}".
-
-        For available functions, please check https://github.com/itsthedevman/spec_forge.
-      STRING
-      )
+    #
+    # Raised when an unknown transform function is referenced
+    # Indicates when a transform name isn't supported
+    #
+    class InvalidTransformFunctionError < Error
+      def initialize(input)
+        # TODO: Update link to docs
+        super(<<~STRING.chomp
+          Undefined transform function "#{input}".
+
+          For available functions, please check https://github.com/itsthedevman/spec_forge.
+        STRING
+        )
+      end
     end
-  end
 
-  #
-  # Raised by Attribute::Chainable when an step in the invocation chain is invalid
-  #
-  class InvalidInvocationError < Error
-    def initialize(step, object)
-      valid_operations =
-        case object
-        when ArrayLike
-          "Array index (0, 1, 2, etc.) or any Array methods (first, last, size, etc.)"
-        when HashLike
-          "Any Hash key: #{object.keys.join(", ")}"
-        else
-          "Any method available on #{object.class}"
+    #
+    # Raised when a step in an invocation chain is invalid
+    # Provides detailed information about where in the chain the error occurred
+    #
+    # @example
+    #   variable_attr = Attribute::Variable.new("variables.user.invalid_method")
+    #   variable_attr.resolved
+    #   # => InvalidInvocationError: Cannot invoke "invalid_method" on User
+    #
+    class InvalidInvocationError < Error
+      def initialize(step, object, resolution_path = {})
+        @step = step
+        @object = object
+        @resolution_path = resolution_path
+
+        object_class =
+          case object
+          when Data
+            object.class.name || "Data"
+          when Struct
+            object.class.name || "Struct"
+          else
+            object.class
+          end
+
+        super(<<~STRING.chomp
+          Cannot invoke "#{step}" on #{object_class}
+          #{resolution_path_message}
+        STRING
+        )
+      end
+
+      #
+      # Creates a new InvalidInvocationError with a new resolution path
+      #
+      # @param path [Hash] The steps taken up until this point
+      #
+      def with_resolution_path(path)
+        self.class.new(@step, @object, path)
+      end
+
+      private
+
+      def resolution_path_message
+        return "" if @resolution_path.empty?
+
+        message =
+          @resolution_path.map.with_index do |(path, description), index|
+            "#{index + 1}. #{path} --> #{description}"
+          end.join("\n")
+
+        "\nResolution path:\n#{message}"
+      end
+    end
+
+    #
+    # An extended version of TypeError with better error messages
+    # Makes it easier to understand type mismatches in the codebase
+    #
+    # @example
+    #   raise Error::InvalidTypeError.new(123, String, for: "name parameter")
+    #   # => Expected String, got Integer for name parameter
+    #
+    class InvalidTypeError < Error
+      def initialize(object, expected_type, **opts)
+        if expected_type.instance_of?(Array)
+          expected_type = expected_type.to_sentence(**OR_CONNECTOR)
         end
 
-      super(<<~STRING.chomp
-        Cannot invoke "#{step}" on #{object.class}.
+        message = "Expected #{expected_type}, got #{object.class}"
+        message += " for #{opts[:for]}" if opts[:for].present?
 
-        Valid operations include: #{valid_operations}
-      STRING
-      )
+        super(message)
+      end
     end
-  end
 
-  #
-  # An extended version of TypeError to make things easier when reporting invalid types
-  #
-  class InvalidTypeError < Error
-    def initialize(object, expected_type, **opts)
-      if expected_type.instance_of?(Array)
-        expected_type = expected_type.to_sentence(**OR_CONNECTOR)
+    #
+    # Raised when a variable reference cannot be resolved
+    # Indicates when a spec or expectation references an undefined variable
+    #
+    class MissingVariableError < Error
+      def initialize(variable_name)
+        super("Undefined variable \"#{variable_name}\" referenced in expectation")
       end
+    end
 
-      message = "Expected #{expected_type}, got #{object.class}"
-      message += " for #{opts[:for]}" if opts[:for].present?
+    #
+    # Raised when a YAML structure doesn't match expectations
+    # Acts as a container for multiple validation errors
+    #
+    class InvalidStructureError < Error
+      def initialize(errors)
+        message = errors.to_a.join_map("\n") do |error|
+          next error if error.is_a?(SpecForge::Error)
 
-      super(message)
+          # Normal errors, let's get verbose
+          backtrace = SpecForge.backtrace_cleaner.clean(error.backtrace)
+          "#{error.inspect}\n  # ./#{backtrace.join("\n  # ./")}\n"
+        end
+
+        super(message)
+      end
     end
-  end
 
-  #
-  # Raised by Attribute::Variable when the provided variable name is not defined
-  #
-  class MissingVariableError < Error
-    def initialize(variable_name)
-      super("Undefined variable \"#{variable_name}\" referenced in expectation")
+    #
+    # Raised when an unknown factory build strategy is provided
+    # Indicates when a strategy string doesn't match supported options
+    #
+    class InvalidBuildStrategy < Error
+      def initialize(build_strategy)
+        valid_strategies = Attribute::Factory::BUILD_STRATEGIES.to_sentence(**OR_CONNECTOR)
+
+        super(<<~STRING.chomp
+          Unknown build strategy "#{build_strategy}" referenced in spec.
+
+          Valid strategies include: #{valid_strategies}
+        STRING
+        )
+      end
     end
-  end
 
-  #
-  # Raised by Normalizer when any errors are returned. Acts like a grouping of errors
-  #
-  class InvalidStructureError < Error
-    def initialize(errors)
-      message = errors.to_a.join_map("\n") do |error|
-        next error if error.is_a?(SpecForge::Error)
-
-        # Normal errors, let's get verbose
-        backtrace = SpecForge.backtrace_cleaner.clean(error.backtrace)
-        "#{error.inspect}\n  # ./#{backtrace.join("\n  # ./")}\n"
+    #
+    # Raised when a spec file cannot be loaded
+    # Provides detailed information about the cause of the loading error
+    #
+    class SpecLoadError < Error
+      def initialize(error, file_path, spec: nil)
+        message =
+          if spec
+            "Error loading spec #{spec[:name].in_quotes} in file #{file_path.in_quotes} (line #{spec[:line_number]})"
+          else
+            "Error loading spec file #{file_path.in_quotes}"
+          end
+
+        causes = error.message.split("\n").map(&:strip).reject(&:empty?)
+
+        message +=
+          if causes.size > 1
+            "\nCauses:\n  - #{causes.join_map("\n  - ")}"
+          else
+            "\nCause: #{error}"
+          end
+
+        super(message)
       end
+    end
 
-      super(message)
+    #
+    # Raised when the provided namespace is not defined on the global context
+    #
+    class InvalidGlobalNamespaceError < Error
+      def initialize(provided_namespace)
+        super("Invalid global namespace #{provided_namespace.in_quotes}. Currently supported namespaces are: \"variables\"")
+      end
     end
-  end
 
-  #
-  # Raised by Attribute::Factory when an unknown build strategy is provided
-  #
-  class InvalidBuildStrategy < Error
-    def initialize(build_strategy)
-      valid_strategies = Attribute::Factory::BUILD_STRATEGIES.to_sentence(**OR_CONNECTOR)
+    #
+    # Raised when the provided matcher name does not defined with RSpec
+    #
+    class UndefinedMatcherError < Error
+      def initialize(matcher_name)
+        matcher_categories = {
+          Equality: ["matcher.eq", "matcher.eql", "matcher.equal"],
+          Types: ["kind_of.string", "kind_of.integer", "kind_of.array", "kind_of.hash"],
+          Truthiness: ["be.true", "be.false", "be.nil"],
+          Comparison: ["be.within", "be.between", "be.greater_than", "be.less_than"],
+          Collections: ["matcher.include", "matcher.contain_exactly", "matcher.all"],
+          Strings: ["/regex/", "matcher.start_with", "matcher.end_with"]
+        }
 
-      super(<<~STRING.chomp
-        Unknown build strategy "#{build_strategy}" referenced in spec.
+        formatted_categories =
+          matcher_categories.join_map("\n") do |category, matchers|
+            "  #{category}: #{matchers.join(", ")}"
+          end
 
-        Valid strategies include: #{valid_strategies}
-      STRING
-      )
+        super(<<~STRING.chomp
+          Undefined matcher method "#{matcher_name}" is not available in RSpec matchers.
+
+          Common matchers you can use:
+          #{formatted_categories}
+
+          For the complete list of available matchers, check the RSpec documentation:
+          https://rspec.info/documentation/3.12/rspec-expectations/RSpec/Matchers.html
+        STRING
+        )
+      end
+    end
+
+    #
+    # Raised when a callback is referenced in config but hasn't been defined
+    #
+    class UndefinedCallbackError < Error
+      def initialize(callback_name, available_callbacks = [])
+        message = "The callback #{callback_name.in_quotes} was referenced but hasn't been defined."
+
+        message +=
+          if available_callbacks.any?
+            <<~STR.chomp
+
+              Available callbacks are: #{available_callbacks.join_map(", ", &:in_quotes)}
+            STR
+          else
+            <<~STR.chomp
+
+              No callbacks have been defined yet. Register callbacks with:
+
+                SpecForge.register_callback(:#{callback_name}) do |context|
+                  # Your callback code
+                end
+            STR
+          end
+
+        super(message)
+      end
     end
   end
 end

data/lib/spec_forge/factory.rb

@@ -1,9 +1,14 @@
 # frozen_string_literal: true
 
 module SpecForge
+  #
+  # Manages factory definitions and registration with FactoryBot
+  # Provides methods for loading factories from YAML files
+  #
   class Factory
     #
-    # Loads the factories from their yml files and registers them with FactoryBot
+    # Loads factories from files and registers them with FactoryBot
+    # Sets up paths and loads definitions based on configuration
     #
     def self.load_and_register
       if SpecForge.configuration.factories.paths?
@@ -17,14 +22,13 @@ module SpecForge
     end
 
     #
-    # Loads any factories defined in the factories. A single file can contain one or more factories
+    # Loads factory definitions from YAML files
+    # Creates Factory instances but doesn't register them with FactoryBot
     #
-    # @return [Array<Factory>] An array of factories that were loaded.
-    #   Note: This factories have not been registered with FactoryBot.
-    #   See #register
+    # @return [Array<Factory>] Array of loaded factory instances
     #
     def self.load_from_files
-      path = SpecForge.forge.join("factories", "**/*.yml")
+      path = SpecForge.forge_path.join("factories", "**/*.yml")
 
       factories = []
 
@@ -43,13 +47,28 @@ module SpecForge
 
     ############################################################################
 
-    attr_reader :name, :input, :model_class, :variables, :attributes
+    # @return [Symbol, String] The name of the factory
+    attr_reader :name
 
+    # @return [Hash] The raw input that defined this factory
+    attr_reader :input
+
+    # @return [String, nil] The model class name this factory represents, if specified
+    attr_reader :model_class
+
+    # @return [Hash<Symbol, Attribute>] Variables defined for this factory
+    attr_reader :variables
+
+    # @return [Hash<Symbol, Attribute>] The attributes that define this factory
+    attr_reader :attributes
+
+    #
+    # Creates a new Factory instance
     #
-    # Creates a new Factory
+    # @param name [String, Symbol] The name of the factory
+    # @param input [Hash] The attributes defining the factory
     #
-    # @param name [String] The name of the factory
-    # @param **input [Hash] Attributes to define the factory. See Normalizer::Factory
+    # @return [Factory] A new factory instance
     #
     def initialize(name:, **input)
       @name = name
@@ -63,10 +82,10 @@ module SpecForge
     end
 
     #
-    # Registers this factory with FactoryBot.
-    # Once registered, you can call FactoryBot.build and other methods
+    # Registers this factory with FactoryBot
+    # Makes the factory available for use in specs
     #
-    # @return [Self]
+    # @return [self] Returns self for method chaining
     #
     def register
       dsl = FactoryBot::Syntax::Default::DSL.new
@@ -78,7 +97,7 @@ module SpecForge
       factory_forge = self
       dsl.factory(name, options) do
         factory_forge.attributes.each do |name, attribute|
-          add_attribute(name) { attribute.resolve_value }
+          add_attribute(name) { attribute.resolve }
         end
       end