spec_forge 0.4.0 → 0.6.0

data/lib/spec_forge/backtrace_formatter.rb

@@ -2,18 +2,41 @@
 
 module SpecForge
   #
-  # Used internally by RSpec
-  # This class handles formatting backtraces, hence the name ;)
+  # Used internally by RSpec to format backtraces for test failures
+  # Customizes error output to make it more readable and useful for SpecForge
   #
   module BacktraceFormatter
+    #
+    # Returns the RSpec backtrace formatter instance
+    # Lazily initializes the formatter on first access
+    #
+    # @return [RSpec::Core::BacktraceFormatter] The backtrace formatter
+    #
     def self.formatter
       @formatter ||= RSpec::Core::BacktraceFormatter.new
     end
 
+    #
+    # Formats a single backtrace line
+    # Delegates to the RSpec formatter
+    #
+    # @param line [String] The backtrace line to format
+    #
+    # @return [String] The formatted backtrace line
+    #
     def self.backtrace_line(line)
       formatter.backtrace_line(line)
     end
 
+    #
+    # Formats a complete backtrace for an example
+    # Adds the YAML location to the front of the backtrace for better context
+    #
+    # @param backtrace [Array<String>] The raw backtrace lines
+    # @param example_metadata [Hash] Metadata about the failing example
+    #
+    # @return [Array<String>] The formatted backtrace with YAML location first
+    #
     def self.format_backtrace(backtrace, example_metadata)
       backtrace = SpecForge.backtrace_cleaner.clean(backtrace)
 
@@ -21,7 +44,7 @@ module SpecForge
       line_number = example_metadata[:example_group][:line_number]
 
       # Add the yaml location to the front so it's the first thing people see
-      ["#{location}:#{line_number}"] + backtrace
+      ["#{location}:#{line_number}"] + backtrace[0..50]
     end
   end
 end

data/lib/spec_forge/callbacks.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module SpecForge
+  #
+  # Manages user-defined callbacks for test lifecycle events
+  #
+  # This singleton class stores and executes callback functions that
+  # users can register to run at specific points in the test lifecycle.
+  # Each callback receives a context object containing relevant state
+  # information for that point in execution.
+  #
+  # @example Registering and using a callback
+  #   SpecForge::Callbacks.register(:my_callback) do |context|
+  #     puts "Running test: #{context.expectation_name}"
+  #   end
+  #
+  class Callbacks < Hash
+    include Singleton
+
+    class << self
+      #
+      # Registers a new callback for a specific event
+      #
+      # @param name [String, Symbol] The name of the callback event
+      # @param block [Proc] The callback function to execute
+      #
+      # @raise [ArgumentError] If no block is provided
+      #
+      def register(name, &block)
+        raise ArgumentError, "A block must be provided" unless block.is_a?(Proc)
+
+        if registered?(name)
+          warn("Callback #{name.in_quotes} is already registered. It will be overwritten")
+        end
+
+        instance[name.to_s] = block
+      end
+
+      #
+      # Checks if a callback is registered for the given event
+      #
+      # @param name [String, Symbol] The name of the callback event
+      #
+      # @return [Boolean] True if the callback exists
+      #
+      def registered?(name)
+        instance.key?(name.to_s)
+      end
+
+      #
+      # Returns all registered callback names
+      #
+      # @return [Array<String>] List of registered callback names
+      #
+      def registered_names
+        instance.keys
+      end
+
+      #
+      # Executes a named callback with the provided context
+      #
+      # @param name [String, Symbol] The name of the callback to run
+      # @param context [Object] Context object containing state data
+      #
+      # @raise [ArgumentError] If the callback is not registered
+      #
+      def run(name, context)
+        callback = instance[name.to_s]
+        raise ArgumentError, "Callback #{name.in_quotes} is not defined" if callback.nil?
+
+        if callback.arity == 0
+          callback.call
+        else
+          callback.call(context)
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/cli/actions.rb

@@ -2,17 +2,44 @@
 
 module SpecForge
   class CLI
+    #
+    # Provides helper methods for CLI actions such as file generation
+    # and template rendering through Thor::Actions integration.
+    #
+    # @example Using actions in a command
+    #   actions.template("my_template.tt", "destination/path.rb")
+    #
     module Actions
+      #
+      # Internal Ruby hook, called when the module is included in another file
+      #
+      # @param base [Class] The class that included this module
+      #
       def self.included(base)
+        #
+        # Returns an ActionContext instance for performing file operations
+        #
+        # @return [ActionContext] The action context for this command
+        #
         base.define_method(:actions) do
           @actions ||= ActionContext.new
         end
       end
     end
 
+    #
+    # Provides a context for Thor actions that configures paths and options
+    #
+    # @private
+    #
     class ActionContext < Thor
       include Thor::Actions
 
+      #
+      # Creates a new action context with SpecForge template paths configured
+      #
+      # @return [ActionContext] A new context for Thor actions
+      #
       def initialize(...)
         self.class.source_root(File.expand_path("../../templates", __dir__))
         self.destination_root = SpecForge.root

data/lib/spec_forge/cli/command.rb

@@ -2,20 +2,55 @@
 
 module SpecForge
   class CLI
+    #
+    # Base class for CLI commands that provides common functionality and
+    # defines the DSL for declaring command properties.
+    #
+    # @example Defining a simple command
+    #   class MyCommand < Command
+    #     command_name "my_command"
+    #     syntax "my_command [options]"
+    #     summary "Does something awesome"
+    #     description "A longer description of what this command does"
+    #
+    #     option "-f", "--force", "Force the operation"
+    #
+    #     def call
+    #       # Command implementation
+    #     end
+    #   end
+    #
     class Command
       include CLI::Actions
 
       class << self
-        attr_writer(*%i[
-          command_name
-          syntax
-          description
-          summary
-          options
-        ])
+        #
+        # Sets the command's name
+        #
+        attr_writer :command_name
+
+        #
+        # Sets the command's syntax string
+        #
+        attr_writer :syntax
+
+        #
+        # Sets the command's detailed description
+        #
+        attr_writer :description
+
+        #
+        # Sets a brief summary of the command
+        #
+        attr_writer :summary
+
+        #
+        # Sets the command's available options
+        #
+        attr_writer :options
 
         #
-        # The command's name
+        # Sets the command's name
         #
         # @param name [String] The name of the command
         #
@@ -24,37 +59,37 @@ module SpecForge
         end
 
         #
-        # The command's syntax
+        # Sets the command's syntax
         #
-        # @param syntax [String]
+        # @param syntax [String] The command syntax to display in help
         #
         def syntax(syntax)
           self.syntax = syntax
         end
 
         #
-        # The command's description, long form
+        # Sets the command's description, displayed in detailed help
         #
-        # @param description [String]
+        # @param description [String] The detailed command description
         #
         def description(description)
           self.description = description
         end
 
         #
-        # The command's summary, short form
+        # Sets the command's summary, displayed in command list
         #
-        # @param summary [String]
+        # @param summary [String] The short command summary
         #
         def summary(summary)
           self.summary = summary
         end
 
         #
-        # Defines an example on how to use the command
+        # Adds an example of how to use the command
         #
-        # @param command [String] The example
-        # @param description [String] Description of the example
+        # @param command [String] The example command
+        # @param description [String] Description of what the example does
         #
         def example(command, description)
           @examples ||= []
@@ -64,7 +99,10 @@ module SpecForge
         end
 
         #
-        # Defines a command flag (-f, --force)
+        # Adds a command line option
+        #
+        # @param args [Array<String>] The option flags (e.g., "-f", "--force")
+        # @yield [value] Block to handle the option value
         #
         def option(*args, &block)
           @options ||= []
@@ -73,9 +111,9 @@ module SpecForge
         end
 
         #
-        # Defines any aliases for this command
+        # Adds command aliases
         #
-        # @param *aliases [Array<String>]
+        # @param aliases [Array<String>] Alias names for this command
         #
         def aliases(*aliases)
           @aliases ||= []
@@ -86,7 +124,7 @@ module SpecForge
         #
         # Registers the command with Commander
         #
-        # @param context [Commander::Command]
+        # @param context [Commander::Command] The Commander context
         #
         # @private
         #
@@ -112,11 +150,27 @@ module SpecForge
         end
       end
 
-      attr_reader :arguments, :options
+      #
+      # Command arguments passed from the command line
+      #
+      # @return [Array] The positional arguments
+      #
+      attr_reader :arguments
+
+      #
+      # Command options passed from the command line
+      #
+      # @return [Hash] The flag arguments
+      #
+      attr_reader :options
 
       #
-      # @param arguments [Array] Any positional arguments
-      # @param options [Hash] Any flag arguments
+      # Creates a new command instance
+      #
+      # @param arguments [Array] Any positional arguments from the command line
+      # @param options [Hash] Any flag arguments from the command line
+      #
+      # @return [Command] A new command instance
       #
       def initialize(arguments, options)
         @arguments = arguments

data/lib/spec_forge/cli/init.rb

@@ -2,13 +2,23 @@
 
 module SpecForge
   class CLI
+    #
+    # Command for initializing a new SpecForge project structure
+    #
+    # @example Creating a new SpecForge project
+    #   spec_forge init
+    #
     class Init < Command
       command_name "init"
       syntax "init"
       summary "Initializes directory structure and configuration files"
 
+      #
+      # Creates the "spec_forge", "spec_forge/factories", and "spec_forge/specs" directories
+      # Also creates the "spec_forge.rb" initialization file
+      #
       def call
-        base_path = SpecForge.forge
+        base_path = SpecForge.forge_path
         actions.empty_directory "#{base_path}/factories"
         actions.empty_directory "#{base_path}/specs"
 

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
     #