skooma 0.3.3 → 0.3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76912cb6b09166983cae2e1e03a104d16351116d2076e3c0b27e24491002a89b
-  data.tar.gz: 65f728f3eda604da0eb7750f7f6cad612cd98870626c8fc766c1554336a6efe1
+  metadata.gz: ecc89f4b7b9744168f5847936e80a6e43d1d9ab32e31df584adaf5c85eaa27af
+  data.tar.gz: bc186b5d374ea4fd8703b8bb58c1dc921760e6731de266e7914035868c921b47
 SHA512:
-  metadata.gz: 2253d20d61746403cd726d47092ba45c7614a283a1af9becfea8fcf387bcd1c9f6f4d52b48efd6ebd7284df52ac5ac944958f6997011f9b8da0b6602d5c21f0d
-  data.tar.gz: 9b220779384f848d308708a1ccd704314ca98d8a3ffc9683fe03962f10a997bc6465835e495638a83a2f955d19191a330e524050deef0345c858255421d2fd1c
+  metadata.gz: 45660ab6ee53e2be9822ee9fccda2850719f10d230a120e4cf1b72855fb88e0cf263f72612e8648b0dccced1cfc08e5e08a4cc462c7f7f8b50fe5122a42a49a3
+  data.tar.gz: 798b59438bdd1ccf3cea2633372f581118dc979fc6c0347b5c0c98b070c4b8a3e765343606cdd756b4b3133d212cf3e2bc06a06bee23273f9a4f4687f1146f5e

data/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning].
 
 ## [Unreleased]
 
+## [0.3.5] - 2025-07-31
+
+### Fixed
+
+- Fix the Enforce Access mode with additional properties. ([@aburgel])
+- Introduce coverage storage to fix Minitest parallel workers reports. ([@skarlcf])
+- Introduce `use_patterns_for_path_matching` option to allow using `path` patterns for path matching. ([@jandouwebeekman])
+
+    ```ruby
+    # spec/rails_helper.rb
+
+    RSpec.configure do |config|
+      # To enable path patterns, pass `use_patterns_for_path_matching: true` option:
+      config.include Skooma::RSpec[Rails.root.join("docs", "openapi.yml"), use_patterns_for_path_matching: true], type: :request
+    end
+    ```
+
+## [0.3.4] - 2025-01-14
+
+### Added
+
+- Experimental support for `readOnly` and `writeOnly` keywords. ([@skryukov])
+
+    ```ruby
+    # spec/rails_helper.rb
+    
+    RSpec.configure do |config|
+      # To enable support for readOnly and writeOnly keywords, pass `enforce_access_modes: true` option:
+      config.include Skooma::RSpec[Rails.root.join("docs", "openapi.yml"), enforce_access_modes: true], type: :request
+    end
+    ```
+- Support fallback parsers for vendor-specific media types. ([@pvcarrera], [@skryukov])
+
 ## [0.3.3] - 2024-10-14
 
 ### Fixed
@@ -124,11 +157,17 @@ and this project adheres to [Semantic Versioning].
 
 - Initial implementation. ([@skryukov])
 
+[@aburgel]: https://github.com/aburgel
 [@barnaclebarnes]: https://github.com/barnaclebarnes
+[@jandouwebeekman]: https://github.com/jandouwebeekman
+[@pvcarrera]: https://github.com/pvcarrera
+[@skarlcf]: https://github.com/skarlcf
 [@skryukov]: https://github.com/skryukov
 [@ursm]: https://github.com/ursm
 
-[Unreleased]: https://github.com/skryukov/skooma/compare/v0.3.3...HEAD
+[Unreleased]: https://github.com/skryukov/skooma/compare/v0.3.5...HEAD
+[0.3.5]: https://github.com/skryukov/skooma/compare/v0.3.4...v0.3.5
+[0.3.4]: https://github.com/skryukov/skooma/compare/v0.3.3...v0.3.4
 [0.3.3]: https://github.com/skryukov/skooma/compare/v0.3.2...v0.3.3
 [0.3.2]: https://github.com/skryukov/skooma/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/skryukov/skooma/compare/v0.3.0...v0.3.1

data/README.md

@@ -128,6 +128,13 @@ ActionDispatch::IntegrationTest.include Skooma::Minitest[path_to_openapi, path_p
 # To enable coverage, pass `coverage: :report` option,
 # and to raise an error when an operation is not covered, pass `coverage: :strict` option:
 ActionDispatch::IntegrationTest.include Skooma::Minitest[path_to_openapi, coverage: :report], type: :request
+
+# EXPERIMENTAL
+# To enable support for readOnly and writeOnly keywords, pass `enforce_access_modes: true` option:
+ActionDispatch::IntegrationTest.include Skooma::Minitest[path_to_openapi, enforce_access_modes: true], type: :request
+
+# To enable custom regex patterns for path parameters, pass `use_patterns_for_path_matching: true` option.
+ActionDispatch::IntegrationTest.include Skooma::Minitest[path_to_openapi, use_patterns_for_path_matching: true], type: :request
 ```
 
 #### Validate OpenAPI document

data/lib/skooma/body_parsers.rb

@@ -6,16 +6,38 @@ module Skooma
       DEFAULT_PARSER = ->(body, **_options) { body }
 
       def [](media_type)
-        parsers[media_type.to_s.strip.downcase] || DEFAULT_PARSER
+        key = normalize_media_type(media_type)
+        parsers[key] ||
+          find_suffix_parser(key) ||
+          find_fallback_parser(key) ||
+          DEFAULT_PARSER
       end
 
       attr_accessor :parsers
 
       def register(*media_types, parser)
         media_types.each do |media_type|
-          parsers[media_type.to_s.strip.downcase] = parser
+          parsers[normalize_media_type(media_type)] = parser
         end
       end
+
+      private
+
+      def normalize_media_type(media_type)
+        media_type.to_s.strip.downcase
+      end
+
+      def find_suffix_parser(media_type)
+        return unless media_type.include?("+")
+
+        suffix = media_type.split("+").last
+        parsers["application/#{suffix}"]
+      end
+
+      def find_fallback_parser(media_type)
+        type = media_type.split("/").first
+        parsers["#{type}/*"] || parsers["*/*"]
+      end
     end
     self.parsers = {}
 

data/lib/skooma/coverage.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Skooma
   class NoopCoverage
     def track_request(*)
@@ -24,7 +26,7 @@ module Skooma
       end
     end
 
-    def self.new(schema, mode: nil, format: nil)
+    def self.new(schema, mode: nil, format: nil, storage: nil)
       case mode
       when nil, false
         NoopCoverage.new
@@ -35,14 +37,23 @@ module Skooma
       end
     end
 
-    attr_reader :mode, :format, :defined_paths, :covered_paths, :schema
+    attr_reader :mode, :format, :defined_paths, :storage, :schema
+    attr_accessor :covered_paths
 
-    def initialize(schema, mode:, format:)
+    def initialize(schema, mode:, format:, storage:)
       @schema = schema
       @mode = mode
       @format = format || SimpleReport
-      @defined_paths = find_defined_paths(schema)
-      @covered_paths = Set.new
+      @storage = storage || CoverageStore.new
+
+      stored_data = @storage.load_data
+      @defined_paths = stored_data[:defined_paths]
+      @covered_paths = stored_data[:covered_paths]
+
+      if @defined_paths.empty?
+        @defined_paths = find_defined_paths(schema)
+        @storage.save_data(@defined_paths, @covered_paths)
+      end
     end
 
     def track_request(result)
@@ -57,6 +68,7 @@ module Skooma
         end
       end
       covered_paths << operation
+      storage.save_data(Set.new, Set.new([operation]))
     end
 
     def uncovered_paths
@@ -68,7 +80,10 @@ module Skooma
     end
 
     def report
+      stored_data = storage.load_data
+      self.covered_paths = stored_data[:covered_paths]
       format.new(self).report
+      storage.clear
       exit 1 if mode == :strict && uncovered_paths.any?
     end
 

data/lib/skooma/coverage_store.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Skooma
+  class CoverageStore
+    DEFAULT_FILE_PATH = File.join(Dir.pwd, "tmp", "skooma_coverage.json")
+
+    attr_reader :file_path
+
+    def initialize(file_path: DEFAULT_FILE_PATH)
+      @file_path = file_path
+      ensure_file_exists
+    end
+
+    def load_data
+      with_lock("r") do |file|
+        parse_data(file.read)
+      end
+    end
+
+    def save_data(new_defined_paths, new_covered_paths)
+      with_lock("r+") do |file|
+        existing_data = parse_data(file.read)
+        merged_data = merge_data(existing_data, new_defined_paths, new_covered_paths)
+
+        file.rewind
+        file.write(JSON.generate(merged_data))
+        file.flush
+        file.truncate(file.pos)
+      end
+    end
+
+    def clear
+      File.delete(file_path) if File.exist?(file_path)
+    end
+
+    private
+
+    def ensure_file_exists
+      FileUtils.mkdir_p(File.dirname(@file_path))
+      FileUtils.touch(@file_path) unless File.exist?(@file_path)
+    end
+
+    def parse_data(content)
+      return {defined_paths: Set.new, covered_paths: Set.new} if content.strip.empty?
+
+      data = JSON.parse(content, symbolize_names: true)
+      {
+        defined_paths: Set.new(data[:defined_paths]),
+        covered_paths: Set.new(data[:covered_paths])
+      }
+    end
+
+    def merge_data(existing_data, new_defined_paths, new_covered_paths)
+      {
+        defined_paths: (existing_data[:defined_paths] | new_defined_paths).to_a,
+        covered_paths: (existing_data[:covered_paths] | new_covered_paths).to_a
+      }
+    end
+
+    def with_lock(mode)
+      File.open(@file_path, mode) do |file|
+        file.flock(File::LOCK_EX)
+        yield(file)
+      ensure
+        file.flock(File::LOCK_UN)
+      end
+    end
+  end
+end

data/lib/skooma/dialects/oas_3_1.rb

@@ -16,6 +16,9 @@ module Skooma
             Skooma::Keywords::OAS31::Dialect::OneOf,
             Skooma::Keywords::OAS31::Dialect::Discriminator,
             Skooma::Keywords::OAS31::Dialect::Xml,
+            Skooma::Keywords::OAS31::Dialect::Properties,
+            Skooma::Keywords::OAS31::Dialect::AdditionalProperties,
+            Skooma::Keywords::OAS31::Dialect::Required,
             Skooma::Keywords::OAS31::Dialect::ExternalDocs,
             Skooma::Keywords::OAS31::Dialect::Example
           )

data/lib/skooma/keywords/oas_3_1/dialect/additional_properties.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Skooma
+  module Keywords
+    module OAS31
+      module Dialect
+        class AdditionalProperties < JSONSkooma::Keywords::Applicator::AdditionalProperties
+          self.key = "additionalProperties"
+          self.instance_types = "object"
+          self.value_schema = :schema
+          self.depends_on = %w[properties patternProperties]
+
+          def evaluate(instance, result)
+            known_property_names = result.sibling(instance, "properties")&.schema_node&.keys || []
+            known_property_patterns = (result.sibling(instance, "patternProperties")&.schema_node&.keys || [])
+              .map { |pattern| Regexp.new(pattern) }
+
+            forbidden = []
+
+            if json.root.enforce_access_modes?
+              only_key = result.path.include?("responses") ? "writeOnly" : "readOnly"
+              properties_result = result.sibling(instance, "properties")
+              instance.each_key do |name|
+                res = properties_result&.children&.[](instance[name]&.path)&.[]name
+                forbidden << name.tap { puts "adding #{name}" } if res && annotation_exists?(res, key: only_key)
+              end
+            end
+
+            annotation = []
+            error = []
+
+            instance.each do |name, item|
+              if forbidden.include?(name) || !known_property_names.include?(name) && known_property_patterns.none? { |pattern| pattern.match?(name) }
+                if json.evaluate(item, result).passed?
+                  annotation << name
+                else
+                  error << name
+                  # reset to success for the next iteration
+                  result.success
+                end
+              end
+            end
+            return result.annotate(annotation) if error.empty?
+
+            result.failure(error)
+          end
+
+          private
+
+          def annotation_exists?(result, key:)
+            return result if result.key == key && result.annotation
+
+            result.each_children do |child|
+              return child if annotation_exists?(child, key: key)
+            end
+
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/skooma/keywords/oas_3_1/dialect/properties.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Skooma
+  module Keywords
+    module OAS31
+      module Dialect
+        class Properties < JSONSkooma::Keywords::Applicator::Properties
+          self.key = "properties"
+          self.instance_types = "object"
+          self.value_schema = :object_of_schemas
+
+          def evaluate(instance, result)
+            annotation = []
+            err_names = []
+            instance.each do |name, item|
+              next unless json.value.key?(name)
+
+              result.call(item, name) do |subresult|
+                json[name].evaluate(item, subresult)
+                if ignored_with_only_key?(subresult)
+                  subresult.discard
+                elsif subresult.passed?
+                  annotation << name
+                else
+                  err_names << name
+                end
+              end
+            end
+
+            return result.annotate(annotation) if err_names.empty?
+
+            result.failure("Properties #{err_names.join(", ")} are invalid")
+          end
+
+          private
+
+          def ignored_with_only_key?(subresult)
+            return false unless json.root.enforce_access_modes?
+
+            if subresult.parent.path.include?("responses")
+              subresult.children["readOnly"]&.value == true
+            else
+              subresult.children["writeOnly"]&.value == true
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/skooma/keywords/oas_3_1/dialect/required.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Skooma
+  module Keywords
+    module OAS31
+      module Dialect
+        class Required < JSONSkooma::Keywords::Validation::Required
+          self.key = "required"
+          self.instance_types = "object"
+          self.depends_on = %w[properties]
+
+          def evaluate(instance, result)
+            missing = required_keys.reject { |key| instance.key?(key) }
+            return if missing.none?
+
+            if json.root.enforce_access_modes?
+              properties_schema = result.sibling(instance, "properties")&.schema_node || {}
+              only_key = result.path.include?("responses") ? "writeOnly" : "readOnly"
+              ignore = []
+              missing.each do |name|
+                next unless properties_schema.key?(name)
+
+                result.call(nil, name) do |subresult|
+                  properties_schema[name].evaluate(nil, subresult)
+                  ignore << name if annotation_exists?(subresult, key: only_key)
+                  subresult.discard
+                end
+              end
+
+              return if (missing - ignore).none?
+            end
+
+            result.failure(missing_keys_message(missing))
+          end
+
+          private
+
+          def annotation_exists?(result, key:)
+            return result if result.key == key && result.annotation
+
+            result.each_children do |child|
+              return child if annotation_exists?(child, key: key)
+            end
+
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/skooma/matchers/wrapper.rb

@@ -44,7 +44,7 @@ module Skooma
         end
       end
 
-      def initialize(helper_methods_module, openapi_path, base_uri: "https://skoomarb.dev/", path_prefix: "", **params)
+      def initialize(helper_methods_module, openapi_path, base_uri: "https://skoomarb.dev/", path_prefix: "", enforce_access_modes: false, use_patterns_for_path_matching: false, **params)
         super()
 
         registry = create_test_registry
@@ -57,8 +57,14 @@ module Skooma
         )
         @schema = registry.schema(URI.parse("#{source_uri}#{pathname.basename}"), schema_class: Skooma::Objects::OpenAPI)
         @schema.path_prefix = path_prefix
+        @schema.enforce_access_modes = enforce_access_modes
 
-        @coverage = Coverage.new(@schema, mode: params[:coverage], format: params[:coverage_format])
+        storage = Skooma::CoverageStore.new(
+          file_path: File.join(Dir.pwd, "tmp", "skooma_coverage_#{Digest::SHA256.hexdigest(source_uri)[0..8]}.json")
+        )
+        @coverage = Coverage.new(@schema, mode: params[:coverage], format: params[:coverage_format], storage: storage)
+
+        @schema.use_patterns_for_path_matching = use_patterns_for_path_matching
 
         include DefaultHelperMethods
         include helper_methods_module

data/lib/skooma/minitest.rb

@@ -39,7 +39,9 @@ module Skooma
     def initialize(openapi_path, **params)
       super(HelperMethods, openapi_path, **params)
 
-      ::Minitest.after_run { coverage.report }
+      ::Minitest.after_run do
+        coverage.report
+      end
     end
   end
 end

data/lib/skooma/objects/openapi/keywords/paths.rb

@@ -13,14 +13,6 @@ module Skooma
 
           def initialize(parent_schema, value)
             super
-            @regexp_map = json.filter_map do |path, subschema|
-              next unless path.include?("{") && path.include?("}")
-
-              path_regex = path.gsub(ROUTE_REGEXP, "(?<\\1>[^/?#]+)")
-              path_regex = Regexp.new("\\A#{path_regex}\\z")
-
-              [path, path_regex, subschema]
-            end
           end
 
           def evaluate(instance, result)
@@ -44,11 +36,34 @@ module Skooma
 
           private
 
+          def regexp_map
+            @regexp_map ||= json.filter_map do |path, subschema|
+              next unless path.include?("{") && path.include?("}")
+
+              pattern_hash = if json.root.use_patterns_for_path_matching?
+                create_hash_of_patterns(subschema)
+              else
+                {}
+              end
+
+              path_regex = path.gsub(ROUTE_REGEXP) do |match|
+                param = match[1..-2]
+                if pattern_hash.key?(param)
+                  "(?<#{param}>#{pattern_hash[param]})"
+                else
+                  "(?<#{param}>[^/?#]+)"
+                end
+              end
+              path_regex = Regexp.new("\\A#{path_regex}\\z")
+
+              [path, path_regex, subschema]
+            end
+          end
+
           def find_route(instance_path)
             instance_path = instance_path.delete_prefix(json.root.path_prefix)
             return [instance_path, {}, json[instance_path]] if json.key?(instance_path)
-
-            @regexp_map.reduce(nil) do |result, (path, path_regex, subschema)|
+            regexp_map.reduce(nil) do |result, (path, path_regex, subschema)|
               next result unless path.include?("{") && path.include?("}")
 
               match = instance_path.match(path_regex)
@@ -58,6 +73,57 @@ module Skooma
               [path, match.named_captures, subschema]
             end
           end
+
+          def get_child(parent, child_name)
+            if parent
+              parent_to_use = if parent.key?("$ref")
+                parent.resolve_ref(parent["$ref"])
+              else
+                parent
+              end
+              if parent_to_use.key?(child_name)
+                parent_to_use[child_name]
+              end
+            end
+          end
+
+          def create_hash_of_patterns(subschema)
+            output = {}
+            parameters = []
+            parameters = parameters.concat(subschema["parameters"]) if subschema["parameters"]
+            %w[get post put patch delete].each do |method|
+              parameters = parameters.concat(subschema[method]["parameters"]) if subschema[method] && subschema[method]["parameters"]
+            end
+            parameters.each do |parameter|
+              if get_child(parameter, "in") == "path"
+                pattern = "[^/?#]+"
+                new_pattern = get_child(parameter, "pattern")
+                pattern = new_pattern if new_pattern
+                new_pattern = get_child(get_child(parameter, "schema"), "pattern")
+                pattern = new_pattern if new_pattern
+
+                output[get_child(parameter, "name").to_s] = filter_pattern(pattern)
+              end
+            end
+            output
+          end
+
+          def filter_pattern(pattern)
+            to_return = pattern.to_s
+            if to_return.start_with?("^")
+              to_return = to_return[1..]
+            end
+            if to_return.start_with?('\A')
+              to_return = to_return[2..]
+            end
+            if to_return.end_with?("$")
+              to_return = to_return[0..-2]
+            end
+            if to_return.end_with?('\Z', '\z')
+              to_return = to_return[0..-3]
+            end
+            to_return
+          end
         end
       end
     end

data/lib/skooma/objects/openapi.rb

@@ -39,6 +39,26 @@ module Skooma
         @path_prefix = @path_prefix.delete_suffix("/") if @path_prefix.end_with?("/")
       end
 
+      def enforce_access_modes=(value)
+        raise ArgumentError, "Enforce access modes must be a boolean" unless [true, false].include?(value)
+
+        @enforce_access_modes = value
+      end
+
+      def enforce_access_modes?
+        @enforce_access_modes
+      end
+
+      def use_patterns_for_path_matching=(value)
+        raise ArgumentError, "Use patterns for path matching must be a boolean" unless [true, false].include?(value)
+
+        @use_patterns_for_path_matching = value
+      end
+
+      def use_patterns_for_path_matching?
+        @use_patterns_for_path_matching
+      end
+
       def path_prefix
         @path_prefix || ""
       end

data/lib/skooma/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Skooma
-  VERSION = "0.3.3"
+  VERSION = "0.3.5"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: skooma
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.3.5
 platform: ruby
 authors:
 - Svyatoslav Kryukov
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-14 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -30,14 +29,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: 0.2.5
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: 0.2.5
 description: Apply a documentation-first approach to API development.
 email:
 - me@skryukov.dev
@@ -55,16 +54,20 @@ files:
 - lib/skooma.rb
 - lib/skooma/body_parsers.rb
 - lib/skooma/coverage.rb
+- lib/skooma/coverage_store.rb
 - lib/skooma/dialects/oas_3_1.rb
 - lib/skooma/env_mapper.rb
 - lib/skooma/inflector.rb
 - lib/skooma/instance.rb
 - lib/skooma/keywords/oas_3_1.rb
+- lib/skooma/keywords/oas_3_1/dialect/additional_properties.rb
 - lib/skooma/keywords/oas_3_1/dialect/any_of.rb
 - lib/skooma/keywords/oas_3_1/dialect/discriminator.rb
 - lib/skooma/keywords/oas_3_1/dialect/example.rb
 - lib/skooma/keywords/oas_3_1/dialect/external_docs.rb
 - lib/skooma/keywords/oas_3_1/dialect/one_of.rb
+- lib/skooma/keywords/oas_3_1/dialect/properties.rb
+- lib/skooma/keywords/oas_3_1/dialect/required.rb
 - lib/skooma/keywords/oas_3_1/dialect/xml.rb
 - lib/skooma/keywords/oas_3_1/schema.rb
 - lib/skooma/matchers/be_valid_document.rb
@@ -149,7 +152,6 @@ metadata:
   homepage_uri: https://github.com/skryukov/skooma
   source_code_uri: https://github.com/skryukov/skooma
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -164,8 +166,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.17
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Validate API implementations against OpenAPI documents.
 test_files: []