spec_forge 0.5.0 → 0.7.0

data/lib/spec_forge/callbacks.rb

@@ -0,0 +1,88 @@
+# 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
+
+      #
+      # Deregisters a callback
+      #
+      # @param name [String, Symbol] The name of the callback
+      #
+      def deregister(name)
+        instance.delete(name.to_s)
+      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/docs/generate.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class CLI
+    class Docs < Command
+      #
+      # Shared functionality for generating OpenAPI documentation
+      #
+      # This module contains the core logic for running tests, extracting endpoint
+      # data, and generating OpenAPI specifications. It's used by both the Docs
+      # and Serve commands to avoid duplication.
+      #
+      module Generate
+        #
+        # Generates OpenAPI documentation and writes it to disk
+        #
+        # Runs the documentation generation pipeline: executes tests, extracts
+        # endpoint data, generates OpenAPI spec, validates it, and writes the
+        # output file in the specified format.
+        #
+        # @return [Pathname] The path to the generated documentation file
+        #
+        def generate_documentation
+          generator = Documentation::Generators::OpenAPI["3.0"]
+          output = generator.generate(use_cache: !options.fresh)
+
+          generator.validate!(output) unless options.skip_validation
+
+          # Determine output format and path
+          file_format = determine_file_format
+          file_path = determine_output_path(file_format)
+
+          content =
+            if file_format == "json"
+              JSON.pretty_generate(output)
+            else
+              output.to_yaml(stringify_names: true)
+            end
+
+          ::File.write(file_path, content)
+
+          file_path
+        end
+
+        private
+
+        def determine_file_format
+          file_format = options.format&.downcase || "yml"
+          validate_format!(file_format)
+
+          file_format
+        end
+
+        def validate_format!(format)
+          return if VALID_FORMATS.include?(format)
+
+          raise ArgumentError,
+            "Invalid format #{format.in_quotes}. Valid formats: #{VALID_FORMATS.join_map(", ", &:in_quotes)}"
+        end
+
+        def determine_output_path(format)
+          if options.output
+            Pathname.new(options.output)
+          else
+            extension = (format == "json") ? "json" : "yml"
+            SpecForge.openapi_path.join("generated", "openapi.#{extension}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/cli/docs.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative "docs/generate"
+
+module SpecForge
+  class CLI
+    #
+    # Command for generating OpenAPI documentation from SpecForge tests
+    #
+    # Runs tests and extracts endpoint data to create OpenAPI specifications.
+    # Uses intelligent caching to avoid unnecessary test re-execution when
+    # specs haven't changed.
+    #
+    # @example Generate documentation
+    #   spec_forge docs
+    #
+    # @example Generate with fresh test run
+    #   spec_forge docs --fresh
+    #
+    class Docs < Command
+      include Docs::Generate
+
+      #
+      # Valid file formats for documentation output
+      #
+      # Supported formats include YAML variants (yml, yaml) and JSON.
+      # Used for validation when users specify the --format option.
+      #
+      # @api private
+      #
+      VALID_FORMATS = %w[yml yaml json].freeze
+
+      command_name "docs"
+      syntax "docs"
+      summary "Generate OpenAPI documentation from test results"
+
+      description <<~DESC
+        Generate OpenAPI documentation from test results.
+
+        Uses caching to avoid re-running tests unless specs
+        have changed. Output format can be YAML or JSON.
+      DESC
+
+      example "docs",
+        "Generates OpenAPI specifications from your tests using smart caching"
+
+      example "docs --fresh",
+        "Forces test re-execution and regenerates OpenAPI specs ignoring cache"
+
+      example "docs --format json",
+        "Generates OpenAPI specifications in JSON format instead of YAML"
+
+      example "docs --output ./build/api.yml",
+        "Generates OpenAPI specs to a custom file path"
+
+      example "docs --skip-validation",
+        "Generates documentation without validating the OpenAPI specification"
+
+      option "--fresh", "Re-run all tests ignoring cache"
+      option "--format=FORMAT", "Output format: yml/yaml or json (default: yml)"
+      option "--output=PATH", "Full file path for generated documentation"
+      option "--skip-validation", "Skip OpenAPI specification validation during generation"
+
+      #
+      # Generates OpenAPI documentation from tests
+      #
+      # Runs all SpecForge tests and creates OpenAPI specifications from the
+      # successful test results. This is the main entry point for the docs workflow.
+      #
+      # @return [void]
+      #
+      def call
+        # spec_forge/openapi/generated
+        generated_path = SpecForge.openapi_path.join("generated")
+        actions.empty_directory(generated_path, verbose: false)
+        actions.empty_directory(generated_path.join(".cache"), verbose: false)
+
+        file_path = generate_documentation
+
+        puts <<~STRING
+
+          ========================================
+          🎉 Success!
+          ========================================
+
+          Your OpenAPI specification is valid and ready to use.
+          Output written to: #{file_path.relative_path_from(SpecForge.forge_path)}
+        STRING
+      end
+    end
+  end
+end

data/lib/spec_forge/cli/init.rb

@@ -2,20 +2,62 @@
 
 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"
+      summary "Set up your SpecForge project (creates folders and config files)"
 
+      description <<~DESC
+        Creates the SpecForge project structure.
+
+        Sets up:
+          • spec_forge/specs/ for test files
+          • spec_forge/factories/ for test data (optional)
+          • spec_forge/openapi/ for documentation config (optional)
+          • forge_helper.rb for configuration
+      DESC
+
+      option "--skip-openapi", "Skip generating the \"openapi\" directory"
+      option "--skip-factories", "Skip generating the \"factories\" directory"
+
+      #
+      # 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
-        actions.empty_directory "#{base_path}/factories"
-        actions.empty_directory "#{base_path}/specs"
-
-        actions.template(
-          "forge_helper.tt",
-          SpecForge.root.join(base_path, "forge_helper.rb")
-        )
+        initialize_forge
+        initialize_openapi unless options.skip_openapi
+      end
+
+      private
+
+      def initialize_forge
+        base_path = SpecForge.forge_path
+        actions.empty_directory(base_path.join("specs"))
+        actions.empty_directory(base_path.join("factories")) unless options.skip_factories
+        actions.template("forge_helper.rb.tt", base_path.join("forge_helper.rb"))
+      end
+
+      def initialize_openapi
+        # spec_forge/openapi
+        openapi_path = SpecForge.openapi_path
+        actions.empty_directory(openapi_path)
+
+        # spec_forge/openapi/config
+        config_path = openapi_path.join("config")
+
+        actions.empty_directory(config_path)
+        actions.empty_directory(config_path.join("paths")) # openapi/config/paths
+        actions.empty_directory(config_path.join("components")) # openapi/config/components
+
+        # openapi/config/openapi.yml
+        actions.template("openapi.yml.tt", config_path.join("openapi.yml"))
       end
     end
   end

data/lib/spec_forge/cli/new.rb

@@ -2,9 +2,28 @@
 
 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"
+      summary "Create new test specs or data factories"
+
+      description <<~DESC
+        Generate new files from templates.
+
+        Types:
+          • spec - Creates YAML test files with common patterns
+          • factory - Creates FactoryBot factories for test data
+
+        Files are created in the appropriate spec_forge/ subdirectory.
+      DESC
 
       syntax "new <type> <name>"
 
@@ -19,6 +38,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
@@ -39,29 +61,68 @@ module SpecForge
 
       def create_new_spec(name)
         actions.template(
-          "new_spec.tt",
-          SpecForge.forge.join("specs", "#{name}.yml"),
+          "new_spec.yml.tt",
+          SpecForge.forge_path.join("specs", "#{name}.yml"),
           context: Proxy.new(name).call
         )
       end
 
       def create_new_factory(name)
         actions.template(
-          "new_factory.tt",
-          SpecForge.forge.join("factories", "#{name}.yml"),
+          "new_factory.yml.tt",
+          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