spec_forge 0.6.0 → 0.7.0

data/lib/spec_forge/cli/serve.rb

@@ -0,0 +1,155 @@
+# 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

@@ -40,7 +40,7 @@ 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
@@ -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?

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