spec_forge 0.6.0 → 0.7.1

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

@@ -11,21 +11,53 @@ module SpecForge
     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
+        initialize_forge
+        initialize_openapi unless options.skip_openapi
+      end
+
+      private
+
+      def initialize_forge
         base_path = SpecForge.forge_path
-        actions.empty_directory "#{base_path}/factories"
-        actions.empty_directory "#{base_path}/specs"
+        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
 
-        actions.template(
-          "forge_helper.tt",
-          SpecForge.root.join(base_path, "forge_helper.rb")
-        )
+        # openapi/config/openapi.yml
+        actions.template("openapi.yml.tt", config_path.join("openapi.yml"))
       end
     end
   end

data/lib/spec_forge/cli/new.rb

@@ -13,7 +13,17 @@ module SpecForge
     #
     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>"
 
@@ -51,7 +61,7 @@ module SpecForge
 
       def create_new_spec(name)
         actions.template(
-          "new_spec.tt",
+          "new_spec.yml.tt",
           SpecForge.forge_path.join("specs", "#{name}.yml"),
           context: Proxy.new(name).call
         )
@@ -59,7 +69,7 @@ module SpecForge
 
       def create_new_factory(name)
         actions.template(
-          "new_factory.tt",
+          "new_factory.yml.tt",
           SpecForge.forge_path.join("factories", "#{name}.yml"),
           context: Proxy.new(name).call
         )

data/lib/spec_forge/cli/run.rb

@@ -21,8 +21,18 @@ module SpecForge
       command_name "run"
       syntax "run [target]"
 
-      summary "Runs specs loaded from spec_forge/specs/"
-      description "Runs specs loaded from spec_forge/specs/. The optional target argument allows running specific files, specs, or expectations."
+      summary "Execute your API tests with smart filtering options"
+
+      description <<~DESC
+        Execute API tests with filtering options.
+
+        Target formats:
+          • file_name - Run all specs in a file
+          • file:spec - Run specific spec
+          • file:spec:"expectation" - Run individual expectation
+
+        Uses RSpec for execution with detailed error reporting.
+      DESC
 
       example "spec_forge run",
         "Run all specs in spec_forge/specs/"
@@ -39,8 +49,6 @@ module SpecForge
       example "spec_forge run users:create_user:\"POST /users - Create Admin\"",
         "Run the specific expectation named \"Create Admin\""
 
-      # 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
       #

data/lib/spec_forge/cli/serve.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class CLI
+    #
+    # Command for generating and serving API documentation
+    #
+    # Combines documentation generation with a local web server to provide
+    # an easy way to view and interact with generated API documentation.
+    # Supports both Swagger UI and Redoc interfaces.
+    #
+    # @example Start documentation server
+    #   spec_forge serve
+    #
+    # @example Serve with Redoc UI
+    #   spec_forge serve --ui redoc
+    #
+    class Serve < 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 "serve"
+      syntax "serve"
+      summary "Start a local server to preview your API documentation"
+      description <<~DESC
+        Generate documentation and start a local preview server.
+
+        Combines docs generation with a web interface. Choose between
+        Swagger UI or Redoc for viewing the documentation.
+      DESC
+
+      example "serve",
+        "Generates docs (if needed) and starts documentation server at localhost:8080"
+
+      example "serve --fresh",
+        "Re-runs tests, regenerates docs, and starts the documentation server"
+
+      example "serve --ui redoc",
+        "Starts server with Redoc interface instead of Swagger UI"
+
+      example "serve --port 3001",
+        "Starts documentation server on port 3001"
+
+      example "serve --fresh --ui redoc --port 3001",
+        "Re-runs tests and serves fresh docs with Redoc on custom port"
+
+      # Generation options
+      option "--fresh", "Re-run all tests before starting server"
+      option "--format=FORMAT", "Output format: yml/yaml or json (default: yml)"
+      option "--skip-validation", "Skip OpenAPI specification validation during generation"
+
+      # Server options
+      option "--ui=UI", "Documentation interface: swagger or redoc (default: swagger)"
+      option "--port=PORT", "Port to serve documentation on (default: 8080)"
+
+      aliases :s
+
+      #
+      # Generates documentation and starts a local web server
+      #
+      # Creates OpenAPI documentation from tests and serves it through a local
+      # HTTP server with either Swagger UI or Redoc interface for easy viewing.
+      #
+      # @return [void]
+      #
+      def call
+        server_path = SpecForge.openapi_path.join("server")
+        actions.empty_directory(server_path, verbose: false) # spec_forge/openapi/server
+
+        # Generate and copy the OpenAPI spec file
+        file_name = generate_and_copy_openapi_spec
+
+        # Determine which template file to use
+        template_name =
+          if options.ui == "redoc"
+            "redoc.html.tt"
+          else
+            "swagger.html.tt"
+          end
+
+        # Remove the index if it exists
+        index_path = server_path.join("index.html")
+        index_path.delete if index_path.exist?
+
+        # Generate index.html
+        actions.template(
+          template_name,
+          index_path,
+          context: Proxy.new(spec_url: file_name).call,
+          verbose: false
+        )
+
+        # And serve it!
+        port = options.port || 8080
+        server = WEBrick::HTTPServer.new(
+          Port: port,
+          DocumentRoot: server_path
+        )
+
+        puts <<~STRING
+          ========================================
+          🚀 SpecForge Documentation Server
+          ========================================
+          Server running at: http://localhost:#{port}
+          Press Ctrl+C to stop
+          ========================================
+        STRING
+
+        trap("INT") { server.shutdown }
+        server.start
+      end
+
+      private
+
+      def generate_and_copy_openapi_spec
+        server_path = SpecForge.openapi_path.join("server")
+
+        file_path = generate_documentation
+
+        file_name = file_path.basename
+        path = server_path.join(file_name)
+
+        # If the file already exists, delete it
+        # This ensures we always have the latest spec
+        path.delete if path.exist?
+
+        actions.copy_file(file_path, path, verbose: false)
+
+        file_name
+      end
+
+      #
+      # Helper class for passing template variables to Thor templates
+      #
+      class Proxy < Struct.new(:spec_url)
+        #
+        # Returns a binding for use in templates
+        #
+        # @return [Binding] A binding containing template variables
+        #
+        def call
+          binding
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/cli.rb

@@ -2,18 +2,17 @@
 
 require_relative "cli/actions"
 require_relative "cli/command"
+require_relative "cli/docs"
 require_relative "cli/init"
 require_relative "cli/new"
 require_relative "cli/run"
+require_relative "cli/serve"
 
 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
   #
@@ -23,7 +22,7 @@ module SpecForge
     #
     # @return [Array<SpecForge::CLI::Command>] All available commands
     #
-    COMMANDS = [Init, New, Run].freeze
+    COMMANDS = [Docs, Init, New, Run, Serve].freeze
 
     #
     # Runs the CLI application, setting up program information and registering commands
@@ -31,11 +30,20 @@ module SpecForge
     def run
       program :name, "SpecForge"
       program :version, SpecForge::VERSION
-      program :description, "Write expressive API tests in YAML with the power of RSpec matchers"
+      program :description, <<~DESC.strip
+        Write expressive API tests in YAML with the power of RSpec matchers.
+
+        Quick Start:
+          spec_forge init              # Set up your project
+          spec_forge new spec users    # Create your first test
+          spec_forge run               # Execute tests
+          spec_forge docs              # Generate API docs
+          spec_forge serve             # Serve API docs locally
+      DESC
 
       register_commands
 
-      default_command :run
+      default_command :help
 
       run!
     end

data/lib/spec_forge/configuration.rb

@@ -5,7 +5,7 @@ module SpecForge
   # 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)
+  class Configuration < Struct.new(:base_url, :headers, :query, :factories, :on_debug_proc)
     #
     # Manages factory configuration settings
     # Controls auto-discovery behavior and custom factory paths
@@ -40,11 +40,11 @@ module SpecForge
     # @return [Configuration] A new configuration instance with defaults
     #
     def initialize
-      config = Normalizer.default_configuration
+      config = Normalizer.default(:configuration)
 
       config[:base_url] = "http://localhost:3000"
       config[:factories] = Factories.new
-      config[:on_debug] = Runner::DebugProxy.default
+      config[:on_debug_proc] = Runner::DebugProxy.default
 
       super(**config)
     end
@@ -58,7 +58,7 @@ module SpecForge
     # @api private
     #
     def validate
-      output = Normalizer.normalize_configuration!(to_h)
+      output = Normalizer.normalize!(to_h, using: :configuration)
 
       # In case any value was set to `nil`
       self.base_url = output[:base_url] if base_url.blank?
@@ -68,6 +68,15 @@ module SpecForge
       self
     end
 
+    def on_debug(&block)
+      self.on_debug_proc = block
+    end
+
+    def on_debug=(block)
+      warn("SpecForge::Configuration#on_debug= is deprecated. Use #on_debug instead")
+      self.on_debug_proc = block
+    end
+
     #
     # Recursively converts the configuration to a hash representation
     #
@@ -108,11 +117,6 @@ module SpecForge
     #
     # @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

data/lib/spec_forge/context/store.rb

@@ -19,63 +19,46 @@ module SpecForge
     #
     class Store
       #
-      # Represents a single stored entry with request, variables, and response data
+      # Represents a stored entry containing arbitrary data from test execution
       #
-      # Entries are immutable once created and contain a deep-frozen
-      # snapshot of the test state at the time of storage.
+      # Entries are created during test execution to store custom data that can be
+      # accessed in subsequent tests. Unlike the original rigid Data structure, this
+      # OpenStruct-based approach allows storing any key-value pairs, making it perfect
+      # for complex test scenarios that need custom configuration, metadata, or
+      # computed values.
       #
-      # @example Accessing stored entry data
-      #   entry = store["user_creation"]
-      #   entry.status    # => 201
-      #   entry.body.id   # => 42
+      # @example Storing custom configuration data
+      #   SpecForge.context.store.set(
+      #     "app_config",
+      #     api_version: "v2.1",
+      #     feature_flags: { advanced_search: true }
+      #   )
       #
-      class Entry < Data.define(:scope, :request, :variables, :response)
+      # @example Accessing stored data in tests
+      #   headers:
+      #     X-API-Version: store.app_config.api_version
+      #   query:
+      #     search_enabled: store.app_config.feature_flags.advanced_search
+      #
+      class Entry < OpenStruct
         #
-        # Creates a new immutable store entry
+        # Creates a new 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
+        # @return [Entry] A new entry instance
         #
-        def initialize(request:, variables:, response:, scope: :file)
-          request = request.deep_freeze
-          variables = variables.deep_freeze
-          response = response.deep_freeze
-
+        def initialize(scope: :file, **)
           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]
+          @table.keys
         end
       end
 

data/lib/spec_forge/core_ext/array.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+#
+# Extensions to Ruby's Array class for SpecForge functionality
+#
+# Adds utility methods used throughout SpecForge for array manipulation
+# and data processing.
+#
+class Array
+  #
+  # Merges an array of hashes into a single hash
+  #
+  # Performs a deep merge on each hash in the array, combining them
+  # into a single hash with all keys and values.
+  #
+  # @return [Hash] A hash containing the merged contents of all hashes in the array
+  #
+  # @example Merging an array of hashes
+  #   [{a: 1}, {b: 2}, {a: 3}].to_merged_h
+  #   # => {a: 3, b: 2}
+  #
+  def to_merged_h
+    each_with_object({}) do |hash, output|
+      output.deep_merge!(hash)
+    end
+  end
+end