spec_forge 0.5.0 → 0.6.0

data/lib/spec_forge/attribute.rb

@@ -5,18 +5,21 @@ require_relative "attribute/parameterized"
 require_relative "attribute/chainable"
 require_relative "attribute/resolvable"
 
-# Doesn't matter
-require_relative "attribute/factory"
-require_relative "attribute/faker"
-require_relative "attribute/literal"
-require_relative "attribute/matcher"
-require_relative "attribute/regex"
-require_relative "attribute/resolvable_array"
-require_relative "attribute/resolvable_hash"
-require_relative "attribute/transform"
-require_relative "attribute/variable"
-
 module SpecForge
+  #
+  # Base class for all attribute types in SpecForge.
+  # Attributes represent values that can be transformed, resolved, or have special meaning
+  # in the context of specs and expectations.
+  #
+  # The Attribute system handles dynamic data generation, variable references,
+  # matchers, transformations and other special values in YAML specs.
+  #
+  # @example Basic usage in YAML
+  #   username: faker.internet.username    # A dynamic faker attribute
+  #   email: /\w+@\w+\.\w+/                # A regex attribute
+  #   status: kind_of.integer              # A matcher attribute
+  #   user_id: variables.user.id           # A variable reference
+  #
   class Attribute
     include Resolvable
 
@@ -66,7 +69,7 @@ module SpecForge
     end
 
     #
-    # Creates an Attribute instance from a string, handling any macros
+    # Creates an Attribute instance from a string
     #
     # @param string [String] The input string
     #
@@ -75,24 +78,31 @@ module SpecForge
     # @private
     #
     def self.from_string(string)
-      case string
-      when Faker::KEYWORD_REGEX
-        Faker.new(string)
-      when Variable::KEYWORD_REGEX
-        Variable.new(string)
-      when Matcher::KEYWORD_REGEX
-        Matcher.new(string)
-      when Factory::KEYWORD_REGEX
-        Factory.new(string)
-      when Regex::KEYWORD_REGEX
-        Regex.new(string)
-      else
-        Literal.new(string)
-      end
+      klass =
+        case string
+        when Factory::KEYWORD_REGEX
+          Factory
+        when Faker::KEYWORD_REGEX
+          Faker
+        when Global::KEYWORD_REGEX
+          Global
+        when Matcher::KEYWORD_REGEX
+          Matcher
+        when Regex::KEYWORD_REGEX
+          Regex
+        when Store::KEYWORD_REGEX
+          Store
+        when Variable::KEYWORD_REGEX
+          Variable
+        else
+          Literal
+        end
+
+      klass.new(string)
     end
 
     #
-    # Creates an Attribute instance from a hash, handling any macros
+    # Creates an Attribute instance from a hash
     #
     # @param hash [Hash] The input hash
     #
@@ -118,66 +128,156 @@ module SpecForge
       end
     end
 
+    #
+    # The original input value
+    #
+    # @return [Object]
+    #
     attr_reader :input
 
     #
-    # @param input [Object] Anything
+    # Creates a new attribute
+    #
+    # @param input [Object] The original input value
     #
     def initialize(input)
       @input = input
     end
 
     #
-    # Returns the processed value of the input
+    # Compares this attributes input to other
+    #
+    # @param other [Object, Attribute] If another Attribute, the input will be compared
+    #
+    # @return [Boolean]
+    #
+    def ==(other)
+      other =
+        if other.is_a?(Attribute)
+          other.input
+        else
+          other
+        end
+
+      input == other
+    end
+
+    #
+    # Returns the processed value of this attribute.
+    # Recursively calls #value on underlying attributes, but does NOT resolve
+    # all nested structures completely.
     #
-    # For literals, this is the input itself.
-    # For generated values (Faker, Transform), this is the result of their operations.
+    # This returns an intermediate representation - for fully resolved values, use #resolve instead.
     #
     # @return [Object] The processed value of this attribute
     #
     # @raise [RuntimeError] if not implemented by subclass
     #
+    # @example
+    #   variable_attr = Attribute::Variable.new("variables.user")
+    #   variable_attr.value # => User instance, but any attributes of User remain
+    #   as Attribute objects
+    #
     def value
       raise "not implemented"
     end
 
     #
-    # Returns the fully evaluated result, recursively resolving any nested attributes
+    # Returns the fully evaluated result with complete recursive resolution.
+    # Calls #value internally and then resolves all nested attributes, caching the result.
     #
-    # @return [Object] The resolved value
+    # Use this when you need the final, fully-resolved value with all nested attributes
+    # fully evaluated to their primitive values.
     #
-    # @example Simple literal
-    #   attr = Attribute::Literal.new("hello")
-    #   attr.resolve # => "hello"
+    # @return [Object] The completely resolved value with cached results
     #
-    # @example Nested array with faker
-    #   attr = Attribute::Literal.new(["faker.number.positive", ["faker.name.first_name"]])
-    #   attr.resolve # => [42, ["Jane"]]
+    # @example
+    #   faker_attr = Attribute::Faker.new("faker.name.first_name")
+    #   faker_attr.resolved # => "Jane" (result is cached in @resolved)
+    #   faker_attr.resolved # => "Jane" (returns same cached value)
     #
-    def resolve
-      @resolved ||= resolve_value
+    def resolved
+      @resolved ||= resolve
     end
 
-    def resolve_value
-      __resolve(value)
+    #
+    # Performs recursive resolution of the attribute's value.
+    # Handles nested arrays and hashes by recursively resolving their elements.
+    #
+    # Unlike #resolved, this method doesn't cache results and can be used
+    # when fresh resolution is needed each time.
+    #
+    # @return [Object] The recursively resolved value without caching
+    #
+    # @example
+    #   hash_attr = Attribute::ResolvableHash.new({name: Attribute::Faker.new("faker.name.name")})
+    #   hash_attr.resolve # => {name: "John Smith"}
+    #   hash_attr.resolve # => {name: "Jane Doe"} (different value on each call)
+    #
+    def resolve
+      case value
+      when ArrayLike
+        value.map(&resolved_proc)
+      when HashLike
+        value.transform_values(&resolved_proc)
+      else
+        value
+      end
     end
 
     #
-    # Compares this attributes input to other
+    # Converts this attribute to an appropriate RSpec matcher.
+    # Handles different types of values by creating the right matcher type:
+    # - Arrays become contain_exactly matchers
+    # - Hashes become include matchers
+    # - Regexp become match matchers
+    # - Existing matchers are passed through
+    # - Other values become eq matchers
     #
-    # @param other [Object, Attribute] If another Attribute, the input will be compared
+    # This method is crucial for nested matcher structures and compound matchers
+    # like matcher.and that require all values to be proper matchers.
     #
-    # @return [Boolean]
+    # @return [RSpec::Matchers::BuiltIn::BaseMatcher] A matcher representing this attribute
     #
-    def ==(other)
-      other =
-        if other.is_a?(Attribute)
-          other.input
+    # @example Converting different values to matchers
+    #   literal_attr = Attribute::Literal.new("hello")
+    #   literal_attr.resolve_as_matcher # => eq("hello")
+    #
+    #   array_attr = Attribute::ResolvableArray.new([1, 2, 3])
+    #   array_attr.resolve_as_matcher # => contain_exactly(eq(1), eq(2), eq(3))
+    #
+    #   hash_attr = Attribute::ResolvableHash.new({name: "Test"})
+    #   hash_attr.resolve_as_matcher # => include("name" => eq("Test"))
+    #
+    def resolve_as_matcher
+      methods = Attribute::Matcher::MATCHER_METHODS
+
+      case resolved
+      when Array, ArrayLike
+        resolved_array = resolved.map(&resolve_as_matcher_proc)
+
+        if resolved_array.size > 0
+          methods.contain_exactly(*resolved_array)
         else
-          other
+          methods.eq([])
         end
+      when Hash, HashLike
+        resolved_hash = resolved.transform_values(&resolve_as_matcher_proc).stringify_keys
 
-      input == other
+        if resolved_hash.size > 0
+          methods.include(**resolved_hash)
+        else
+          methods.eq({})
+        end
+      when Attribute::Matcher, Regexp
+        methods.match(resolved)
+      when RSpec::Matchers::BuiltIn::BaseMatcher,
+          RSpec::Matchers::DSL::Matcher,
+          Class
+        resolved # Pass through
+      else
+        methods.eq(resolved)
+      end
     end
 
     #
@@ -185,20 +285,20 @@ module SpecForge
     #
     # @param variables [Hash] A hash of variable attributes
     #
-    def bind_variables(_variables)
-    end
-
-    protected
-
-    def __resolve(value)
-      case value
-      when ArrayLike
-        value.map(&resolvable_proc)
-      when HashLike
-        value.transform_values(&resolvable_proc)
-      else
-        value
-      end
+    def bind_variables(variables)
     end
   end
 end
+
+# Order doesn't matter
+require_relative "attribute/factory"
+require_relative "attribute/faker"
+require_relative "attribute/global"
+require_relative "attribute/literal"
+require_relative "attribute/matcher"
+require_relative "attribute/regex"
+require_relative "attribute/resolvable_array"
+require_relative "attribute/resolvable_hash"
+require_relative "attribute/store"
+require_relative "attribute/transform"
+require_relative "attribute/variable"

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"