spec_forge 0.5.0 → 0.6.0

data/lib/spec_forge/cli/new.rb

@@ -2,6 +2,15 @@
 
 module SpecForge
   class CLI
+    #
+    # Command for generating new specs or factories
+    #
+    # @example Creating a new spec
+    #   spec_forge new spec users
+    #
+    # @example Creating a new factory
+    #   spec_forge new factory user
+    #
     class New < Command
       command_name "new"
       summary "Create a new spec or factory"
@@ -19,6 +28,9 @@ module SpecForge
 
       aliases :generate, :g
 
+      #
+      # Creates a new spec or factory file in the corresponding directory using templates
+      #
       def call
         type = arguments.first.downcase
         name = arguments.second
@@ -40,7 +52,7 @@ module SpecForge
       def create_new_spec(name)
         actions.template(
           "new_spec.tt",
-          SpecForge.forge.join("specs", "#{name}.yml"),
+          SpecForge.forge_path.join("specs", "#{name}.yml"),
           context: Proxy.new(name).call
         )
       end
@@ -48,20 +60,59 @@ module SpecForge
       def create_new_factory(name)
         actions.template(
           "new_factory.tt",
-          SpecForge.forge.join("factories", "#{name}.yml"),
+          SpecForge.forge_path.join("factories", "#{name}.yml"),
           context: Proxy.new(name).call
         )
       end
 
+      #
+      # Helper class for passing template variables to Thor templates
+      #
+      # @example Creating a proxy with a name
+      #   proxy = Proxy.new("user")
+      #   proxy.singular_name # => "user"
+      #   proxy.plural_name # => "users"
+      #
       class Proxy
-        attr_reader :original_name, :singular_name, :plural_name
+        #
+        # The original name passed to the command
+        #
+        # @return [String]
+        #
+        attr_reader :original_name
 
+        #
+        # The singular form of the name
+        #
+        # @return [String]
+        #
+        attr_reader :singular_name
+
+        #
+        # The plural form of the name
+        #
+        # @return [String]
+        #
+        attr_reader :plural_name
+
+        #
+        # Creates a new Proxy with the specified name
+        #
+        # @param name [String] The resource name to pluralize/singularize
+        #
+        # @return [Proxy] A new proxy instance
+        #
         def initialize(name)
           @original_name = name
           @plural_name = name.pluralize
           @singular_name = name.singularize
         end
 
+        #
+        # Returns a binding for use in templates
+        #
+        # @return [Binding] A binding containing template variables
+        #
         def call
           binding
         end

data/lib/spec_forge/cli/run.rb

@@ -2,6 +2,21 @@
 
 module SpecForge
   class CLI
+    #
+    # Command for running SpecForge tests with filtering options
+    #
+    # @example Running all specs
+    #   spec_forge run
+    #
+    # @example Running specific file
+    #   spec_forge run users
+    #
+    # @example Running specific spec
+    #   spec_forge run users:create_user
+    #
+    # @example Running specific expectation
+    #   spec_forge run users:create_user:"POST /users"
+    #
     class Run < Command
       command_name "run"
       syntax "run [target]"
@@ -26,6 +41,9 @@ module SpecForge
 
       # option "-n", "--no-docs", "Do not generate OpenAPI documentation on completion"
 
+      #
+      # Loads and runs all specs, or a subset of specs based on the provided arguments
+      #
       def call
         return SpecForge.run if arguments.blank?
 
@@ -53,6 +71,8 @@ module SpecForge
       #     Example with name:
       #       "users:show_user:'GET /users/:id - Returns 404 due to missing user'"
       #
+      # @private
+      #
       def extract_filter(input)
         # Note: Only split 3 because the expectation name can have colons in them.
         file_name, spec_name, expectation_name = input.split(":", 3).map(&:strip)

data/lib/spec_forge/cli.rb

@@ -7,15 +7,26 @@ require_relative "cli/new"
 require_relative "cli/run"
 
 module SpecForge
+  #
+  # Command-line interface for SpecForge that provides the overall command structure
+  # and entry point for the CLI functionality.
+  #
+  # @example Running the default command
+  #   SpecForge::CLI.new.run
+  #
+  # @example Running a specific command
+  #   # From command line: spec_forge init
+  #
   class CLI
     include Commander::Methods
 
-    COMMANDS = [Init, New, Run]
-
     #
-    # Runs the CLI
+    # @return [Array<SpecForge::CLI::Command>] All available commands
     #
-    # @private
+    COMMANDS = [Init, New, Run].freeze
+
+    #
+    # Runs the CLI application, setting up program information and registering commands
     #
     def run
       program :name, "SpecForge"
@@ -30,7 +41,7 @@ module SpecForge
     end
 
     #
-    # Registers the commands with Commander
+    # Registers the command classes with Commander
     #
     # @private
     #

data/lib/spec_forge/configuration.rb

@@ -1,43 +1,62 @@
 # frozen_string_literal: true
 
 module SpecForge
-  class Configuration < Struct.new(:base_url, :headers, :query, :factories, :specs, :on_debug)
-    ############################################################################
-
+  #
+  # Configuration container for SpecForge settings
+  # Defines default values and validation for all configuration options
+  #
+  class Configuration < Struct.new(:base_url, :headers, :query, :factories, :on_debug)
+    #
+    # Manages factory configuration settings
+    # Controls auto-discovery behavior and custom factory paths
+    #
+    # @example
+    #   config.factories.auto_discover = false
+    #   config.factories.paths += ["lib/factories"]
+    #
     class Factories < Struct.new(:auto_discover, :paths)
+      #
+      # Creates reader methods that return boolean values
+      # Allows for checking configuration with predicate methods
+      #
       attr_predicate :auto_discover, :paths
 
+      #
+      # Initializes a new Factories configuration
+      # Sets default values for auto-discovery and paths
+      #
+      # @param auto_discover [Boolean] Whether to auto-discover factories (default: true)
+      # @param paths [Array<String>] Additional paths to look for factories (default: [])
+      #
+      # @return [Factories] A new factories configuration instance
+      #
       def initialize(auto_discover: true, paths: []) = super
     end
 
-    ############################################################################
-
-    def self.overlay_options(source, overlay)
-      source.deep_merge(overlay) do |key, source_value, overlay_value|
-        # If overlay has a populated value, use it
-        if overlay_value.present? || overlay_value == false
-          overlay_value
-        # If source is nil and overlay exists (but wasn't "present"), use overlay
-        elsif source_value.nil? && !overlay_value.nil?
-          overlay_value
-        # Otherwise keep source value
-        else
-          source_value
-        end
-      end
-    end
-
+    #
+    # Initializes a new Configuration with default values
+    # Sets up the configuration structure including factory settings and debug proxy
+    #
+    # @return [Configuration] A new configuration instance with defaults
+    #
     def initialize
       config = Normalizer.default_configuration
 
       config[:base_url] = "http://localhost:3000"
       config[:factories] = Factories.new
-      config[:specs] = RSpec.configuration
       config[:on_debug] = Runner::DebugProxy.default
 
       super(**config)
     end
 
+    #
+    # Validates the configuration and applies normalization
+    # Ensures all required fields have values and applies defaults when needed
+    #
+    # @return [self] Returns self for method chaining
+    #
+    # @api private
+    #
     def validate
       output = Normalizer.normalize_configuration!(to_h)
 
@@ -49,10 +68,63 @@ module SpecForge
       self
     end
 
+    #
+    # Recursively converts the configuration to a hash representation
+    #
+    # @return [Hash] Hash representation of the configuration
+    #
     def to_h
-      hash = super.except(:specs)
+      hash = super
       hash[:factories] = hash[:factories].to_h
       hash
     end
+
+    #
+    # Returns the RSpec configuration object
+    # Provides access to RSpec's internal configuration for test customization
+    #
+    # @return [RSpec::Core::Configuration] RSpec's configuration object
+    #
+    # @example Setting formatter options
+    #   SpecForge.configure do |config|
+    #     config.specs.formatter = :documentation
+    #   end
+    #
+    def specs
+      RSpec.configuration
+    end
+
+    alias_method :rspec, :specs
+
+    #
+    # Registers a callback for a specific test lifecycle event
+    # Allows custom code execution at specific points during test execution
+    #
+    # @param name [Symbol, String] The callback point to register for
+    #   (:before_file, :after_expectation, etc.)
+    # @yield A block to execute when the callback is triggered
+    # @yieldparam context [Object] An object containing context-specific state data, depending
+    #   on which hook the callback is triggered from.
+    #
+    # @return [Proc] The registered callback
+    #
+    # @example Registering a custom debug handler
+    #   SpecForge.configure do |config|
+    #     config.register_callback(:on_debug) { binding.pry }
+    #   end
+    #
+    # @example Cleaning database after each test
+    #   SpecForge.configure do |config|
+    #     config.register_callback(:after_expectation) do
+    #       DatabaseCleaner.clean
+    #     end
+    #   end
+    #
+    def register_callback(name, &)
+      Callbacks.register(name, &)
+    end
+
+    alias_method :define_callback, :register_callback
+    alias_method :callback, :register_callback
   end
 end

data/lib/spec_forge/context/callbacks.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Context
+    #
+    # Manages user-defined callbacks grouped by lifecycle hook
+    #
+    # This class collects and organizes callbacks by their hook type
+    # (before_file, after_each, etc.) to support the test lifecycle.
+    # It ensures callbacks are properly categorized for execution.
+    #
+    # @example Creating callback groups
+    #   callbacks = Context::Callbacks.new([
+    #     {before_file: "setup_environment"},
+    #     {after_each: "log_test_result"}
+    #   ])
+    #
+    class Callbacks
+      #
+      # Creates a new callbacks collection
+      #
+      # @param callback_array [Array] Optional initial callbacks to register
+      #
+      # @return [Callbacks] A new callbacks collection
+      #
+      def initialize(callback_array = [])
+        set(callback_array)
+      end
+
+      #
+      # Updates the callbacks collection
+      #
+      # @param callback_array [Array] New callbacks to register
+      #
+      # @return [self]
+      #
+      def set(callback_array)
+        @inner = organize_callbacks_by_hook(callback_array)
+        self
+      end
+
+      #
+      # Returns the hash representation of callbacks
+      #
+      # @return [Hash] Callbacks organized by hook type
+      #
+      def to_h
+        @inner
+      end
+
+      #
+      # Executes all registered callbacks for a specific lifecycle hook
+      #
+      # @param hook_name [String, Symbol] The lifecycle hook (before_file, after_each, etc.)
+      # @param context [Hash] State data that will be converted to a structured object
+      #   and passed to callbacks
+      #
+      def run(hook_name, context = {})
+        context = context.to_struct
+
+        @inner[hook_name].each do |callback_name|
+          SpecForge::Callbacks.run(callback_name, context)
+        end
+      end
+
+      private
+
+      #
+      # Organizes callbacks from an array to hash structure by hook type
+      # Groups callbacks like before_file, after_each, etc. for easier lookup
+      #
+      # @param callback_array [Array] The array of callbacks
+      #
+      # @return [Hash] Callbacks indexed by hook type
+      #
+      # @private
+      #
+      def organize_callbacks_by_hook(callback_array)
+        groups = Hash.new { |h, k| h[k] = Set.new }
+
+        callback_array.each_with_object(groups) do |callbacks, groups|
+          callbacks.each do |hook, name|
+            next if name.blank?
+
+            groups[hook].add(name)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/context/global.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Context
+    #
+    # Manages global state and variables at the spec file level.
+    #
+    # The Global class provides access to variables that are defined at the global level
+    # in a spec file and are accessible across all specs and expectations in a file.
+    # Unlike regular variables, global variables do not support overlaying - they maintain
+    # consistent values throughout test execution.
+    #
+    # @example Basic usage
+    #   global = Global.new(variables: {api_version: "v2", environment: "test"})
+    #
+    #   global.variables[:api_version] #=> "v2"
+    #   global.variables[:environment] #=> "test"
+    #
+    #   # Update global variables
+    #   global.set(variables: {environment: "staging"})
+    #   global.variables[:environment] #=> "staging"
+    #   global.variables[:api_version] #=> nil
+    #
+    class Global
+      # @return [Context::Variables] The container for global variables
+      attr_reader :variables
+
+      # @return [Context::Callbacks] The container for callbacks
+      attr_reader :callbacks
+
+      #
+      # Creates a new Global context instance
+      #
+      # @param variables [Hash<Symbol, Object>] A hash of variable names and values
+      # @param callbacks [Array<Hash<Symbol, String>>] An array of callback hooks
+      #
+      # @return [Global] The new Global instance
+      #
+      def initialize(variables: {}, callbacks: [])
+        @variables = Variables.new(base: variables)
+        @callbacks = Callbacks.new(callbacks)
+      end
+
+      #
+      # Sets the global variables
+      #
+      # @param variables [Hash<Symbol, Object>] A hash of variable names and values
+      # @param callbacks [Array<Hash<Symbol, String>>] An array of callback hooks
+      #
+      # @return [self]
+      #
+      def set(variables: {}, callbacks: [])
+        @variables.set(base: variables)
+        @callbacks.set(callbacks)
+
+        self
+      end
+
+      #
+      # Returns a hash representation of the global context
+      #
+      # @return [Hash]
+      #
+      def to_h
+        {
+          variables: variables.to_h,
+          callbacks: callbacks.to_h
+        }
+      end
+    end
+  end
+end

data/lib/spec_forge/context/store.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Context
+    #
+    # Manages storage of API responses for use in subsequent tests
+    #
+    # This class provides a mechanism to store HTTP requests and responses
+    # during test execution, allowing values to be referenced in later tests
+    # through the `store.id.body.attribute` syntax.
+    #
+    # @example Storing and retrieving a response in specs
+    #   # In one expectation:
+    #   store_as: user_creation
+    #
+    #   # In a later test:
+    #   query:
+    #     id: store.user_creation.body.id
+    #
+    class Store
+      #
+      # Represents a single stored entry with request, variables, and response data
+      #
+      # Entries are immutable once created and contain a deep-frozen
+      # snapshot of the test state at the time of storage.
+      #
+      # @example Accessing stored entry data
+      #   entry = store["user_creation"]
+      #   entry.status    # => 201
+      #   entry.body.id   # => 42
+      #
+      class Entry < Data.define(:scope, :request, :variables, :response)
+        #
+        # Creates a new immutable store entry
+        #
+        # @param request [Hash] The HTTP request that was executed
+        # @param variables [Hash] Variables from the test context
+        # @param response [Hash] The HTTP response received
+        # @param scope [Symbol] Scope of this entry, either :file or :spec
+        #
+        # @return [Entry] A new immutable entry instance
+        #
+        def initialize(request:, variables:, response:, scope: :file)
+          request = request.deep_freeze
+          variables = variables.deep_freeze
+          response = response.deep_freeze
+
+          super
+        end
+
+        #
+        # Shorthand accessor for the HTTP status code
+        #
+        # @return [Integer] The response status code
+        #
+        def status = response[:status]
+
+        #
+        # Shorthand accessor for the response body
+        #
+        # @return [Hash, Array, String] The parsed response body
+        #
+        def body = response[:body]
+
+        #
+        # Shorthand accessor for the response headers
+        #
+        # @return [Hash] The response headers
+        #
+        def headers = response[:headers]
+
+        #
+        # Returns all available methods that can be called
+        #
+        # @return [Array] The method names
+        #
+        def available_methods
+          members + [:status, :body, :headers]
+        end
+      end
+
+      #
+      # Creates a new empty store
+      #
+      # @return [Store] A new store instance
+      #
+      def initialize
+        @inner = {}
+      end
+
+      #
+      # Retrieves a stored entry by ID
+      #
+      # @param id [String, Symbol] The identifier for the stored entry
+      #
+      # @return [Entry, nil] The stored entry or nil if not found
+      #
+      def [](id)
+        @inner[id]
+      end
+
+      #
+      # Returns the number of entries in the store
+      #
+      # @return [Integer] The count of stored entries
+      #
+      def size
+        @inner.size
+      end
+
+      #
+      # Stores an entry with the specified ID
+      #
+      # @param id [String, Symbol] The identifier to store the entry under
+      #
+      # @return [self]
+      #
+      def set(id, **)
+        @inner[id] = Entry.new(**)
+
+        self
+      end
+
+      #
+      # Removes all entries from the store
+      #
+      def clear
+        @inner.clear
+      end
+
+      #
+      # Removes all spec entries from the store
+      #
+      def clear_specs
+        @inner.delete_if { |_k, v| v.scope == :spec }
+      end
+
+      #
+      # Returns a hash representation of store
+      #
+      # @return [Hash]
+      #
+      def to_h
+        @inner.transform_values(&:to_h).deep_stringify_keys
+      end
+    end
+  end
+end