spec_forge 0.6.0 → 0.7.0

data/lib/spec_forge/spec/expectation/constraint.rb

@@ -12,21 +12,24 @@ module SpecForge
       # @example In code
       #   constraint = Constraint.new(
       #     status: 200,
-      #     json: {name: "matcher.eq" => "John"}
+      #     headers: {response_header: "kind_of.string"},
+      #     json: {name: {"matcher.eq" => "John"}}
       #   )
       #
-      class Constraint < Data.define(:status, :json) # :xml, :html
+      class Constraint < Data.define(:status, :headers, :json) # :xml, :html
         #
         # Creates a new constraint
         #
         # @param status [Integer, String] The expected HTTP status code, or reference to one
+        # @param headers [Hash] The expected headers with matchers
         # @param json [Hash, Array] The expected JSON with matchers
         #
         # @return [Constraint] A new constraint instance
         #
-        def initialize(status:, json: {})
+        def initialize(status:, headers: {}, json: {})
           super(
             status: Attribute.from(status),
+            headers: Attribute.from(headers),
             json: Attribute.from(json)
           )
         end
@@ -58,7 +61,8 @@ module SpecForge
         def as_matchers
           {
             status: status.resolve_as_matcher,
-            json: resolve_json_matcher
+            json: resolve_json_matcher,
+            headers: resolve_hash_matcher(headers)
           }
         end
 
@@ -108,11 +112,15 @@ module SpecForge
         def resolve_json_matcher
           case json
           when HashLike
-            json.transform_values(&:resolve_as_matcher).stringify_keys
+            resolve_hash_matcher(json)
           else
             json.resolve_as_matcher
           end
         end
+
+        def resolve_hash_matcher(hash)
+          hash.transform_values(&:resolve_as_matcher).stringify_keys
+        end
       end
     end
   end

data/lib/spec_forge/spec/expectation.rb

@@ -15,7 +15,10 @@ module SpecForge
     #       json:
     #         name: kind_of.string
     #
-    class Expectation < Data.define(:id, :name, :line_number, :debug, :store_as, :constraints)
+    class Expectation < Data.define(
+      :id, :name, :line_number,
+      :debug, :store_as, :documentation, :constraints
+    )
       #
       # @return [Boolean] True if debugging is enabled
       #
@@ -34,14 +37,15 @@ module SpecForge
       # @param line_number [Integer] Line number in source
       # @param debug [Boolean] Whether to enable debugging
       # @param store_as [String] Unique Context::Store identifier
+      # @param documentation [Boolean] Whether to include in documentation generation
       # @param expect [Hash] Expected constraints
       #
       # @return [Expectation] A new expectation instance
       #
-      def initialize(id:, name:, line_number:, debug:, store_as:, expect:)
+      def initialize(id:, name:, line_number:, debug:, store_as:, expect:, documentation:)
         constraints = Constraint.new(**expect)
 
-        super(id:, name:, line_number:, debug:, store_as:, constraints:)
+        super(id:, name:, line_number:, debug:, store_as:, documentation:, constraints:)
       end
 
       #

data/lib/spec_forge/spec.rb

@@ -14,61 +14,15 @@ module SpecForge
   #     - expect:
   #         status: 200
   #
-  class Spec
+  class Spec < Data.define(
+    :id, :name, :file_path, :file_name, :line_number,
+    :debug, :documentation, :expectations
+  )
     #
     # @return [Boolean] True if debugging is enabled
     #
     attr_predicate :debug
 
-    #
-    # Unique identifier for this spec
-    #
-    # @return [String] The spec ID
-    #
-    attr_reader :id
-
-    #
-    # Human-readable name for this spec
-    #
-    # @return [String] The spec name
-    #
-    attr_reader :name
-
-    #
-    # Absolute path to the file containing this spec
-    #
-    # @return [String] The file path
-    #
-    attr_reader :file_path
-
-    #
-    # Base name of the file without path or extension
-    #
-    # @return [String] The file name
-    #
-    attr_reader :file_name
-
-    #
-    # Whether to enable debugging for this spec
-    #
-    # @return [Boolean] Debug flag
-    #
-    attr_reader :debug
-
-    #
-    # Line number in the source file where this spec is defined
-    #
-    # @return [Integer] The line number
-    #
-    attr_reader :line_number
-
-    #
-    # The expectations to test for this spec
-    #
-    # @return [Array<Expectation>] The expectations
-    #
-    attr_accessor :expectations
-
     #
     # Creates a new spec instance
     #
@@ -78,18 +32,18 @@ module SpecForge
     # @param file_name [String] Base name of file
     # @param debug [Boolean] Whether to enable debugging
     # @param line_number [Integer] Line number in source
+    # @param documentation [Boolean] Whether to include in documentation generation
     # @param expectations [Array<Hash>] Expectation configurations
     #
     # @return [Spec] A new spec instance
     #
-    def initialize(id:, name:, file_path:, file_name:, debug:, line_number:, expectations:)
-      @id = id
-      @name = name
-      @file_path = file_path
-      @file_name = file_name
-      @debug = debug
-      @line_number = line_number
-      @expectations = expectations.map { |e| Expectation.new(**e) }
+    def initialize(
+      id:, name:, file_path:, file_name:, line_number:,
+      debug:, documentation:, expectations:
+    )
+      expectations = expectations.map { |e| Expectation.new(**e) }
+
+      super
     end
 
     #
@@ -104,6 +58,7 @@ module SpecForge
         file_name:,
         debug:,
         line_number:,
+        documentation:,
         expectations: expectations.map(&:to_h)
       }
     end

data/lib/spec_forge/version.rb

@@ -4,5 +4,5 @@ module SpecForge
   #
   # Current version of SpecForge
   #
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
 end

data/lib/spec_forge.rb

@@ -5,15 +5,19 @@ require "logger"
 require "active_support"
 require "active_support/core_ext"
 require "commander"
-require "everythingrb"
+require "everythingrb/prelude"
+require "everythingrb/all"
 require "factory_bot"
 require "faker"
 require "faraday"
 require "mime/types"
+require "openapi3_parser"
 require "pathname"
 require "rspec"
+require "sem_version"
 require "singleton"
 require "thor"
+require "webrick"
 require "yaml"
 
 #
@@ -57,28 +61,8 @@ module SpecForge
     # @param expectation_name [String, nil] Optional name of expectation to run
     #
     def run(file_name: nil, spec_name: nil, expectation_name: nil)
-      # Load spec_helper.rb
-      forge_helper = SpecForge.forge_path.join("forge_helper.rb")
-      require_relative forge_helper if File.exist?(forge_helper)
-
-      # Validate in case anything was changed
-      configuration.validate
-
-      # Load factories
-      Factory.load_and_register
-
-      # Load the specs from their files and create forges from them
-      forges = Loader.load_from_files.map { |f| Forge.new(*f) }
-
-      # Filter out the specs and expectations
-      forges = Filter.apply(forges, file_name:, spec_name:, expectation_name:)
-
-      # Tell the user that we filtered if we did
-      Filter.announce(forges, file_name:, spec_name:, expectation_name:)
-
-      # Define and run everything
-      Runner.define(forges)
-      Runner.run
+      forges = Runner.prepare(file_name:, spec_name:, expectation_name:)
+      Runner.run(forges, exit_on_finish: true)
     end
 
     #
@@ -99,6 +83,15 @@ module SpecForge
       @forge_path ||= root.join("spec_forge")
     end
 
+    #
+    # Returns SpecForge's openapi directory
+    #
+    # @return [Pathname] The spec_forge openapi directory path
+    #
+    def openapi_path
+      @openapi_path ||= forge_path.join("openapi")
+    end
+
     #
     # Returns SpecForge's configuration
     #
@@ -168,6 +161,19 @@ module SpecForge
     def register_callback(name, &)
       Callbacks.register(name, &)
     end
+
+    #
+    # Generates a unique ID for an object based on hash and object_id
+    #
+    # @param object [Object] The object to generate an ID for
+    #
+    # @return [String] A unique ID string
+    #
+    # @private
+    #
+    def generate_id(object)
+      "#{object.hash.abs.to_s(36)}_#{object.object_id.to_s(36)}"
+    end
   end
 end
 
@@ -178,6 +184,7 @@ require_relative "spec_forge/cli"
 require_relative "spec_forge/configuration"
 require_relative "spec_forge/context"
 require_relative "spec_forge/core_ext"
+require_relative "spec_forge/documentation"
 require_relative "spec_forge/error"
 require_relative "spec_forge/factory"
 require_relative "spec_forge/filter"

data/lib/templates/openapi.yml.tt

@@ -0,0 +1,22 @@
+info:
+  title: My API
+  version: 1.0.0
+  description: A description of My API
+  contact:
+    name: My API Team
+    email: api@example.com
+  license:
+    name: MIT
+    url: https://opensource.org/licenses/MIT
+
+# servers:
+# - url: https://api.example.com/v1
+#   description: Production
+# - url: https://staging-api.example.com/v1
+#   description: Staging
+#
+# tags:
+# - name: users
+#   description: User account management
+# - name: posts
+#   description: Blog post management

data/lib/templates/redoc.html.tt

@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+  <title>Redoc</title>
+  <!-- needed for adaptive design -->
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
+
+  <!--
+    Redoc doesn't change outer page styles
+    -->
+  <style>
+    body {
+      margin: 0;
+      padding: 0;
+    }
+  </style>
+</head>
+
+<body>
+  <redoc spec-url="<%= spec_url %>"></redoc>
+  <script src=" https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js">
+  </script>
+</body>
+
+</html>

data/lib/templates/swagger.html.tt

@@ -0,0 +1,59 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8">
+  <title>Swagger UI</title>
+  <style>
+    html {
+      box-sizing: border-box;
+      overflow: -moz-scrollbars-vertical;
+      overflow-y: scroll;
+    }
+
+    *,
+    *:before,
+    *:after {
+      box-sizing: inherit;
+    }
+
+    body {
+      margin: 0;
+      background: #fafafa;
+    }
+  </style>
+
+  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.24.0/swagger-ui.min.css"
+    integrity="sha512-wWpxfn2bFvPwxuqDyiJbVB0WR3ffSqJNMMryNP07frPJ1h5Xg9HIDMV1wRr1rpxT5E+KTxDrKTuWfGb1RcV8SA=="
+    crossorigin="anonymous" referrerpolicy="no-referrer" />
+</head>
+
+<body>
+  <div id="swagger-ui"></div>
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.24.0/swagger-ui-bundle.min.js"
+    integrity="sha512-nEy/zRjIvuFMSr5ljsQUaUW4l7DoSHz8+SRybclmCjCh3MeF9UaooWYdr/SqjGCiyi4RIvBvn9DxCCV0ZDhiNA=="
+    crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.24.0/swagger-ui-standalone-preset.min.js"
+    integrity="sha512-yJlD9FXQ7YaxAKXhviHSt/0KqWDCkLFdCnk0Ti23HXDMEQtHLAAWMHZ+POglC1mx/MOUB//h8kci3U1JYrywpQ=="
+    crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+
+  <script>
+    window.onload = function () {
+      const ui = SwaggerUIBundle({
+        url: "<%= spec_url %>",
+        dom_id: "#swagger-ui",
+        deepLinking: true,
+        presets: [
+          SwaggerUIBundle.presets.apis,
+          SwaggerUIStandalonePreset
+        ],
+        plugins: [
+          SwaggerUIBundle.plugins.DownloadUrl
+        ],
+        layout: "StandaloneLayout"
+      });
+    };
+  </script>
+</body>
+
+</html>

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: spec_forge
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Bryan
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-03-24 00:00:00.000000000 Z
+date: 2025-06-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.8'
 - !ruby/object:Gem::Dependency
   name: factory_bot
   requirement: !ruby/object:Gem::Requirement
@@ -108,6 +108,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.6'
+- !ruby/object:Gem::Dependency
+  name: openapi3_parser
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.1
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -122,6 +136,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: sem_version
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: thor
   requirement: !ruby/object:Gem::Requirement
@@ -136,6 +164,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
 description: Write API tests in YAML without sacrificing power. SpecForge combines
   RSpec's matcher system, Faker's data generation, and factory patterns into a clean,
   declarative syntax that eliminates boilerplate while preserving control over your
@@ -179,9 +221,12 @@ files:
 - lib/spec_forge/cli.rb
 - lib/spec_forge/cli/actions.rb
 - lib/spec_forge/cli/command.rb
+- lib/spec_forge/cli/docs.rb
+- lib/spec_forge/cli/docs/generate.rb
 - lib/spec_forge/cli/init.rb
 - lib/spec_forge/cli/new.rb
 - lib/spec_forge/cli/run.rb
+- lib/spec_forge/cli/serve.rb
 - lib/spec_forge/configuration.rb
 - lib/spec_forge/context.rb
 - lib/spec_forge/context/callbacks.rb
@@ -189,7 +234,32 @@ files:
 - lib/spec_forge/context/store.rb
 - lib/spec_forge/context/variables.rb
 - lib/spec_forge/core_ext.rb
+- lib/spec_forge/core_ext/array.rb
 - lib/spec_forge/core_ext/rspec.rb
+- lib/spec_forge/documentation.rb
+- lib/spec_forge/documentation/builder.rb
+- lib/spec_forge/documentation/document.rb
+- lib/spec_forge/documentation/document/operation.rb
+- lib/spec_forge/documentation/document/parameter.rb
+- lib/spec_forge/documentation/document/request_body.rb
+- lib/spec_forge/documentation/document/response.rb
+- lib/spec_forge/documentation/document/response_body.rb
+- lib/spec_forge/documentation/generators.rb
+- lib/spec_forge/documentation/generators/base.rb
+- lib/spec_forge/documentation/generators/openapi.rb
+- lib/spec_forge/documentation/generators/openapi/base.rb
+- lib/spec_forge/documentation/generators/openapi/error_formatter.rb
+- lib/spec_forge/documentation/generators/openapi/v3_0.rb
+- lib/spec_forge/documentation/loader.rb
+- lib/spec_forge/documentation/loader/cache.rb
+- lib/spec_forge/documentation/openapi.rb
+- lib/spec_forge/documentation/openapi/base.rb
+- lib/spec_forge/documentation/openapi/v3_0/example.rb
+- lib/spec_forge/documentation/openapi/v3_0/media_type.rb
+- lib/spec_forge/documentation/openapi/v3_0/operation.rb
+- lib/spec_forge/documentation/openapi/v3_0/response.rb
+- lib/spec_forge/documentation/openapi/v3_0/schema.rb
+- lib/spec_forge/documentation/openapi/v3_0/tag.rb
 - lib/spec_forge/error.rb
 - lib/spec_forge/factory.rb
 - lib/spec_forge/filter.rb
@@ -202,14 +272,19 @@ files:
 - lib/spec_forge/loader.rb
 - lib/spec_forge/matchers.rb
 - lib/spec_forge/normalizer.rb
-- lib/spec_forge/normalizer/configuration.rb
-- lib/spec_forge/normalizer/constraint.rb
-- lib/spec_forge/normalizer/expectation.rb
-- lib/spec_forge/normalizer/factory.rb
-- lib/spec_forge/normalizer/factory_reference.rb
-- lib/spec_forge/normalizer/global_context.rb
-- lib/spec_forge/normalizer/spec.rb
+- lib/spec_forge/normalizer/default.rb
+- lib/spec_forge/normalizer/definition.rb
+- lib/spec_forge/normalizer/validators.rb
+- lib/spec_forge/normalizers/_shared.yml
+- lib/spec_forge/normalizers/configuration.yml
+- lib/spec_forge/normalizers/constraint.yml
+- lib/spec_forge/normalizers/expectation.yml
+- lib/spec_forge/normalizers/factory.yml
+- lib/spec_forge/normalizers/factory_reference.yml
+- lib/spec_forge/normalizers/global_context.yml
+- lib/spec_forge/normalizers/spec.yml
 - lib/spec_forge/runner.rb
+- lib/spec_forge/runner/adapter.rb
 - lib/spec_forge/runner/callbacks.rb
 - lib/spec_forge/runner/debug_proxy.rb
 - lib/spec_forge/runner/listener.rb
@@ -220,9 +295,12 @@ files:
 - lib/spec_forge/spec/expectation/constraint.rb
 - lib/spec_forge/type.rb
 - lib/spec_forge/version.rb
-- lib/templates/forge_helper.tt
-- lib/templates/new_factory.tt
-- lib/templates/new_spec.tt
+- lib/templates/forge_helper.rb.tt
+- lib/templates/new_factory.yml.tt
+- lib/templates/new_spec.yml.tt
+- lib/templates/openapi.yml.tt
+- lib/templates/redoc.html.tt
+- lib/templates/swagger.html.tt
 homepage: https://github.com/itsthedevman/spec_forge
 licenses:
 - MIT

data/lib/spec_forge/normalizer/configuration.rb

@@ -1,90 +0,0 @@
-# frozen_string_literal: true
-
-module SpecForge
-  class Normalizer
-    #
-    # Normalizes configuration hash structure for SpecForge
-    #
-    # Ensures that the global configuration has the correct structure
-    # and default values for all required settings.
-    #
-    class Configuration < Normalizer
-      #
-      # Defines the normalized structure for configuration validation
-      #
-      # Specifies validation rules for configuration attributes:
-      # - Enforces specific data types
-      # - Provides default values
-      # - Supports alternative key names
-      #
-      # @return [Hash] Configuration attribute validation rules
-      #
-      STRUCTURE = {
-        base_url: SHARED_ATTRIBUTES[:base_url].except(:default), # Make it required
-        headers: SHARED_ATTRIBUTES[:headers],
-        query: SHARED_ATTRIBUTES[:query],
-        factories: {
-          type: Hash,
-          default: {},
-          structure: {
-            auto_discover: {
-              type: [TrueClass, FalseClass],
-              default: true
-            },
-            paths: {
-              type: Array,
-              default: []
-            }
-          }
-        },
-        on_debug: {
-          type: Proc
-        }
-      }.freeze
-    end
-
-    # On Normalizer
-    class << self
-      #
-      # Generates an empty configuration hash
-      #
-      # @return [Hash] Default configuration hash
-      #
-      def default_configuration
-        Configuration.default
-      end
-
-      #
-      # Normalizes a configuration hash with validation
-      #
-      # @param input [Hash] The hash to normalize
-      #
-      # @return [Hash] A normalized hash with defaults applied
-      #
-      # @raise [Error::InvalidStructureError] If validation fails
-      #
-      def normalize_configuration!(input)
-        raise_errors! do
-          normalize_configuration(input)
-        end
-      end
-
-      #
-      # Normalize a configuration hash
-      #
-      # @param configuration [Hash] Configuration hash
-      #
-      # @return [Array] [normalized_hash, errors]
-      #
-      # @private
-      #
-      def normalize_configuration(configuration)
-        if !Type.hash?(configuration)
-          raise Error::InvalidTypeError.new(configuration, Hash, for: "configuration")
-        end
-
-        Normalizer::Configuration.new("configuration", configuration).normalize
-      end
-    end
-  end
-end