structured_params-openapi 0.1.0

data/sig/structured_params/openapi/configuration.rbs

@@ -0,0 +1,74 @@
+# Generated from lib/structured_params/openapi/configuration.rb with RBS::Inline
+
+module StructuredParams
+  # OpenAPI contract configuration and drift-check utilities.
+  module OpenAPI
+    # Global OpenAPI document and component-name convention for drift checks.
+    class Configuration
+      @ignored_issues: Array[Hash[Symbol, untyped]]
+
+      @documents: Hash[String, Array[untyped]]
+
+      attr_accessor document: Hash[untyped, untyped] | String?
+
+      attr_writer schema_name_resolver: untyped
+
+      attr_writer document_resolver: untyped
+
+      attr_writer parameter_class_filter: untyped
+
+      # : () -> void
+      def initialize: () -> void
+
+      # The OpenAPI document for +parameter_class+: the +document_resolver+ result when it
+      # returns one, otherwise the global +document+. Lets one app check classes from several
+      # API namespaces (e.g. admin and front) against separate files.
+      # : (singleton(StructuredParams::Params)) -> (Hash[untyped, untyped] | String)?
+      def document_for: (singleton(StructuredParams::Params)) -> (Hash[untyped, untyped] | String)?
+
+      # Parses an OpenAPI file once per modification time, so a bulk check across many
+      # parameter classes does not re-read the same document for each of them. JSON files
+      # work too, since JSON is valid YAML. Only the mtime invalidates the cache, so two writes
+      # within the filesystem's timestamp granularity can serve a stale parse. YAML dates such as
+      # `example: 2020-01-01` load as Date, hence +permitted_classes+.
+      # : (String) -> Hash[untyped, untyped]
+      def load_document: (String) -> Hash[untyped, untyped]
+
+      # Suppresses matching findings instead of raising them as errors. Each of +path+, +kind+
+      # and +parameter_class+ narrows the rule; an omitted one matches everything, but at least
+      # one must be given. Without +parameter_class+ the rule applies to every drift check,
+      # including once per parent class for a nested object reused by several top-level
+      # parameter classes. Skips (unsupported schema features) are never ignored; they only
+      # appear in Result#skipped.
+      #
+      # Paths use attribute names joined with +.+ and +[]+ for array items, e.g.
+      # +items[].sku+. A schema that cannot be found at all (+:missing_schema+) concerns the
+      # whole class rather than a property, so omit +path+ for it.
+      #
+      # Ignored findings are moved to DriftCheck::Result#ignored rather than dropped, so
+      # they stay auditable; #valid? and #to_message treat them as resolved.
+      # : (?path: String?, ?kind: Symbol?, ?parameter_class: (Class | String)?) -> void
+      def ignore_drift: (?path: String?, ?kind: Symbol?, ?parameter_class: (Class | String)?) -> void
+
+      # : (Symbol, String, ?untyped) -> bool
+      def ignored?: (Symbol, String, ?untyped) -> bool
+
+      # : () -> Array[singleton(StructuredParams::Params)]
+      def parameter_classes: () -> Array[singleton(StructuredParams::Params)]
+
+      # : (singleton(StructuredParams::Params), ?String?) -> String
+      def pointer_for: (singleton(StructuredParams::Params), ?String?) -> String
+    end
+
+    self.@configuration: Configuration?
+
+    # : () -> Configuration
+    def self.configuration: () -> Configuration
+
+    # : () { (Configuration) -> void } -> void
+    def self.configure: () { (Configuration) -> void } -> void
+
+    # : () -> void
+    def self.reset_configuration!: () -> void
+  end
+end

data/sig/structured_params/openapi/drift_check/issue.rbs

@@ -0,0 +1,19 @@
+# Generated from lib/structured_params/openapi/drift_check/issue.rb with RBS::Inline
+
+module StructuredParams
+  module OpenAPI
+    class DriftCheck
+      # A single finding (error, skipped check, or ignored finding) from a drift check.
+      class Issue < Struct[Symbol | String]
+        attr_accessor kind(): Symbol
+
+        attr_accessor path(): String
+
+        attr_accessor message(): String
+
+        def self.new: (?kind: Symbol, ?path: String, ?message: String) -> instance
+                    | ({ ?kind: Symbol, ?path: String, ?message: String }) -> instance
+      end
+    end
+  end
+end

data/sig/structured_params/openapi/drift_check/result.rbs

@@ -0,0 +1,40 @@
+# Generated from lib/structured_params/openapi/drift_check/result.rb with RBS::Inline
+
+module StructuredParams
+  module OpenAPI
+    class DriftCheck
+      # Result of a single schema/class comparison.
+      class Result
+        attr_reader errors: Array[Issue]
+
+        attr_reader skipped: Array[Issue]
+
+        attr_reader ignored: Array[Issue]
+
+        attr_reader parameter_class: singleton(::StructuredParams::Params)
+
+        # : (singleton(::StructuredParams::Params), Array[Issue], Array[Issue], Array[Issue]) -> void
+        def initialize: (singleton(::StructuredParams::Params), Array[Issue], Array[Issue], Array[Issue]) -> void
+
+        # : () -> bool
+        def valid?: () -> bool
+
+        # : () -> String
+        def to_message: () -> String
+
+        # Lists what a passing check still left unverified (skipped) or suppressed (ignored),
+        # so those stay visible in CI output instead of only on the result object.
+        # : () -> String
+        def to_report: () -> String
+
+        private
+
+        # : () -> String
+        def class_label: () -> String
+
+        # : (Array[Issue]) -> String
+        def format_issues: (Array[Issue]) -> String
+      end
+    end
+  end
+end

data/sig/structured_params/openapi/drift_check.rbs

@@ -0,0 +1,201 @@
+# Generated from lib/structured_params/openapi/drift_check.rb with RBS::Inline
+
+module StructuredParams
+  # Schema comparison types for OpenAPI drift checks.
+  module OpenAPI
+    # Compares OpenAPI object schemas with StructuredParams declarations.
+    # rubocop:disable-next Metrics/ClassLength
+    class DriftCheck
+      @active_pairs: Array[Array[untyped]]
+
+      @ignored: Array[Issue]
+
+      @skipped: Array[Issue]
+
+      @errors: Array[Issue]
+
+      @document: Hash[untyped, untyped]?
+
+      @required_validation: :presence | :none
+
+      @property_names: Hash[Symbol, String]
+
+      @pointer: String?
+
+      @parameter_class: singleton(::StructuredParams::Params)
+
+      @schema_source: Hash[untyped, untyped] | String?
+
+      @openapi_source: Hash[untyped, untyped] | String?
+
+      # Finding kinds that can be raised as errors (and therefore matched by +ignore_drift+).
+      ERROR_KINDS: Array[Symbol]
+
+      # Options that stop a presence validator from enforcing presence on every validation.
+      CONDITIONAL_PRESENCE_OPTIONS: Array[Symbol]
+
+      # Schema types that a +oneOf+/+anyOf+ of plain scalars may offer.
+      SCALAR_SCHEMA_TYPES: Array[Symbol]
+
+      # rubocop:disable Metrics/ParameterLists
+      # : (**untyped) -> Result
+      def self.call: (**untyped) -> Result
+
+      # rubocop:disable Metrics/ParameterLists
+      # : (**untyped) -> void
+      def initialize: (**untyped) -> void
+
+      # : () -> Result
+      def call: () -> Result
+
+      private
+
+      # A missing or mistyped schema means the class silently lost its contract coverage,
+      # so it is an error (suppressible with +ignore_drift+) rather than a skip.
+      # : () -> Hash[untyped, untyped]?
+      def load_root_schema: () -> Hash[untyped, untyped]?
+
+      # : (String) -> nil
+      def report_missing_schema: (String) -> nil
+
+      # : () -> [Hash[untyped, untyped], Hash[untyped, untyped]]
+      def load_schema: () -> [ Hash[untyped, untyped], Hash[untyped, untyped] ]
+
+      # : () -> Hash[untyped, untyped]
+      def load_document: () -> Hash[untyped, untyped]
+
+      # : () -> String?
+      def selected_pointer: () -> String?
+
+      # : (Hash[untyped, untyped], singleton(StructuredParams::Params), String) -> void
+      def check_object: (Hash[untyped, untyped], singleton(StructuredParams::Params), String) -> void
+
+      # : (Hash[untyped, untyped], singleton(StructuredParams::Params), String) -> void
+      #  rubocop:disable-next Metrics/AbcSize
+      def check_object_properties: (Hash[untyped, untyped], singleton(StructuredParams::Params), String) -> void
+
+      # : (untyped, ActiveModel::Type::Value, String) -> void
+      def compare_property: (untyped, ActiveModel::Type::Value, String) -> void
+
+      # : (Hash[Symbol, String], Hash[String, ActiveModel::Type::Value], String) -> void
+      def compare_attribute_names: (Hash[Symbol, String], Hash[String, ActiveModel::Type::Value], String) -> void
+
+      # : (Hash[untyped, untyped], Hash[Symbol, String], singleton(StructuredParams::Params), String) -> void
+      def compare_required_attributes: (Hash[untyped, untyped], Hash[Symbol, String], singleton(StructuredParams::Params), String) -> void
+
+      # A required property that the schema allows to be null must not demand +presence+,
+      # which would reject the null the contract permits.
+      # : (Hash[untyped, untyped], String, String) -> bool
+      def nullable_property?: (Hash[untyped, untyped], String, String) -> bool
+
+      # : (Hash[untyped, untyped]) -> bool
+      def nullable_schema?: (Hash[untyped, untyped]) -> bool
+
+      # : (untyped) -> bool
+      def null_type?: (untyped) -> bool
+
+      # Runs a lookup whose findings are reported elsewhere, so they are not recorded twice.
+      # : [T] () { () -> T } -> T
+      def without_reporting: [T] () { () -> T } -> T
+
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      # : (Hash[untyped, untyped], ActiveModel::Type::Value, String) -> void
+      def compare_type: (Hash[untyped, untyped], ActiveModel::Type::Value, String) -> void
+
+      # : (Hash[untyped, untyped], Type::Array, String) -> void
+      def compare_array_item_type: (Hash[untyped, untyped], Type::Array, String) -> void
+
+      # : (Hash[untyped, untyped]) -> Symbol?
+      def schema_type: (Hash[untyped, untyped]) -> Symbol?
+
+      # : (Symbol?, Symbol) -> bool
+      def compatible_types?: (Symbol?, Symbol) -> bool
+
+      # : (singleton(StructuredParams::Params), Symbol) -> bool
+      def presence_validator?: (singleton(StructuredParams::Params), Symbol) -> bool
+
+      # A +oneOf+/+anyOf+ of plain scalars matches when the attribute fits any of them.
+      # : (Array[Symbol], ActiveModel::Type::Value, String) -> void
+      def compare_scalar_union: (Array[Symbol], ActiveModel::Type::Value, String) -> void
+
+      # The scalar types offered by a +oneOf+/+anyOf+, or nil when it is not a plain scalar union.
+      # : (Hash[untyped, untyped], String) -> Array[Symbol]?
+      def scalar_union_types: (Hash[untyped, untyped], String) -> Array[Symbol]?
+
+      # : (untyped, String) -> Symbol?
+      def scalar_option_type: (untyped, String) -> Symbol?
+
+      # : (Hash[untyped, untyped]) -> String?
+      def union_key: (Hash[untyped, untyped]) -> String?
+
+      # +oneOf: [X, {type: null}]+ and +type: [T, 'null']+ are how OpenAPI 3.1 says "X or null".
+      # Collapse them to X and mark the result +nullable+, so they are compared like a 3.0
+      # +nullable: true+ schema instead of being treated as unsupported unions.
+      # : (Hash[untyped, untyped]) -> Hash[untyped, untyped]
+      def collapse_nullable: (Hash[untyped, untyped]) -> Hash[untyped, untyped]
+
+      # : (Hash[untyped, untyped]) -> Hash[untyped, untyped]?
+      def collapse_null_type: (Hash[untyped, untyped]) -> Hash[untyped, untyped]?
+
+      # : (Hash[untyped, untyped]) -> Hash[untyped, untyped]?
+      def collapse_null_union: (Hash[untyped, untyped]) -> Hash[untyped, untyped]?
+
+      # : (untyped, Hash[untyped, untyped]) -> Hash[untyped, untyped]?
+      def nullable_option: (untyped, Hash[untyped, untyped]) -> Hash[untyped, untyped]?
+
+      # : (untyped) -> bool
+      def null_option?: (untyped) -> bool
+
+      # : (Hash[untyped, untyped], String) -> bool
+      def skip_union?: (Hash[untyped, untyped], String) -> bool
+
+      # : (Hash[untyped, untyped], String, ?Array[String]) -> Hash[untyped, untyped]
+      def resolve_references: (Hash[untyped, untyped], String, ?Array[String]) -> Hash[untyped, untyped]
+
+      # A dangling or circular local reference is a broken contract, not an unsupported feature.
+      # : (String, String, Array[String]) -> Hash[untyped, untyped]?
+      def fetch_reference: (String, String, Array[String]) -> Hash[untyped, untyped]?
+
+      # : (String, String, String) -> nil
+      def unresolved_reference: (String, String, String) -> nil
+
+      # A `$ref` left after resolve_references was already reported (skipped if external, an
+      # error if unresolvable), so comparing it further would only add misleading findings.
+      # : (Hash[untyped, untyped]) -> bool
+      def unresolved_reference?: (Hash[untyped, untyped]) -> bool
+
+      # OpenAPI/JSON Schema forbid sibling keys next to `$ref`, so generators such as TypeSpec
+      # commonly wrap a single `$ref` in `allOf` to attach a `description`, `default`, etc.
+      # That's equivalent to the ref carrying those siblings directly, so unwrap and merge a
+      # single-entry `allOf` (typically a `$ref`, though an inline schema is unwrapped the same
+      # way) instead of treating it as unsupported schema composition. `allOf` with more than
+      # one entry is genuine composition and stays out of scope (reported via skip_union?).
+      # : (Hash[untyped, untyped]) -> Hash[untyped, untyped]
+      def unwrap_single_all_of: (Hash[untyped, untyped]) -> Hash[untyped, untyped]
+
+      # : (untyped, String) -> untyped
+      def resolve_pointer: (untyped, String) -> untyped
+
+      # : (untyped, String) -> untyped
+      def dig_pointer_segment: (untyped, String) -> untyped
+
+      # : (Hash[untyped, untyped], String) -> untyped
+      def value_for: (Hash[untyped, untyped], String) -> untyped
+
+      # : (untyped) -> Symbol
+      def attribute_name: (untyped) -> Symbol
+
+      # : (String, String) -> String
+      def join_path: (String, String) -> String
+
+      # : (String, Symbol, String) -> void
+      def error: (String, Symbol, String) -> void
+
+      # : (String) -> String
+      def display_path: (String) -> String
+
+      # : (String, String) -> void
+      def skip: (String, String) -> void
+    end
+  end
+end

data/sig/structured_params/openapi/registry.rbs

@@ -0,0 +1,46 @@
+# Generated from lib/structured_params/openapi/registry.rb with RBS::Inline
+
+module StructuredParams
+  # OpenAPI contract registration and bulk execution utilities.
+  module OpenAPI
+    # Raised by Registry.check_all! when one or more registered contracts drift.
+    class DriftError < StandardError
+    end
+
+    # Collects exceptional mappings and runs all configured drift checks.
+    class Registry
+      self.@entries: Array[Array[untyped]]?
+
+      # +parameter_class+ may be a class name String (e.g. from a Rails initializer,
+      # before Zeitwerk autoloading is set up); it is resolved lazily in +check_all+.
+      # +openapi+ (a file path or Hash) overrides the configured document for this class, so
+      # one app can check classes against several OpenAPI files.
+      # : (singleton(StructuredParams::Params) | String, **untyped) -> void
+      # rubocop:disable-next Metrics/ParameterLists
+      def self.register: (singleton(StructuredParams::Params) | String, **untyped) -> void
+
+      # : (?auto_discover: bool) -> Array[DriftCheck::Result]
+      def self.check_all: (?auto_discover: bool) -> Array[DriftCheck::Result]
+
+      # With +strict+, a check that skipped part of a schema also fails the run.
+      # : (?auto_discover: bool, ?strict: bool) -> Array[DriftCheck::Result]
+      def self.check_all!: (?auto_discover: bool, ?strict: bool) -> Array[DriftCheck::Result]
+
+      # Describes what passing checks skipped or ignored, plus a one-line summary.
+      # : (Array[DriftCheck::Result]) -> String
+      def self.report: (Array[DriftCheck::Result]) -> String
+
+      # : () -> void
+      def self.clear: () -> void
+
+      # : () -> Hash[singleton(StructuredParams::Params), Hash[untyped, untyped]]
+      private def self.auto_discovered_checks: () -> Hash[singleton(StructuredParams::Params), Hash[untyped, untyped]]
+
+      # : () -> Array[Array[untyped]]
+      private def self.entries: () -> Array[Array[untyped]]
+
+      # : (singleton(StructuredParams::Params) | String) -> singleton(StructuredParams::Params)
+      private def self.resolve: (singleton(StructuredParams::Params) | String) -> singleton(StructuredParams::Params)
+    end
+  end
+end

data/sig/structured_params/openapi/version.rbs

@@ -0,0 +1,7 @@
+# Generated from lib/structured_params/openapi/version.rb with RBS::Inline
+
+module StructuredParams
+  module OpenAPI
+    VERSION: String
+  end
+end

data/sig/structured_params/openapi.rbs

@@ -0,0 +1,14 @@
+# Generated from lib/structured_params/openapi.rb with RBS::Inline
+
+module StructuredParams
+  # OpenAPI drift check for StructuredParams classes.
+  module OpenAPI
+    RAKE_TASK_PATH: String
+
+    # Defers loading the drift-check rake task until Rails actually loads rake tasks,
+    # so requiring this gem never depends on the Rake DSL being mixed into +main+
+    # (e.g. `rails runner`, `rails console`, app boot).
+    class Railtie < Rails::Railtie
+    end
+  end
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: structured_params-openapi
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mizuki Yamamoto
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: structured_params
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.5
+description: Detects differences between OpenAPI request schemas and StructuredParams
+  classes, with a Rake task for CI, JSON Pointer and component naming conventions,
+  and support for several OpenAPI documents.
+email:
+- mizuki-y@syati.info
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- README_ja.md
+- docs/drift-check.md
+- docs/drift-check_ja.md
+- lib/structured_params/openapi.rb
+- lib/structured_params/openapi/configuration.rb
+- lib/structured_params/openapi/drift_check.rb
+- lib/structured_params/openapi/drift_check/issue.rb
+- lib/structured_params/openapi/drift_check/result.rb
+- lib/structured_params/openapi/registry.rb
+- lib/structured_params/openapi/version.rb
+- lib/tasks/structured_params_openapi.rake
+- sig/structured_params/openapi.rbs
+- sig/structured_params/openapi/configuration.rbs
+- sig/structured_params/openapi/drift_check.rbs
+- sig/structured_params/openapi/drift_check/issue.rbs
+- sig/structured_params/openapi/drift_check/result.rbs
+- sig/structured_params/openapi/registry.rbs
+- sig/structured_params/openapi/version.rbs
+homepage: https://github.com/Syati/structured_params
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Syati/structured_params/tree/main/structured_params-openapi#readme
+  changelog_uri: https://github.com/Syati/structured_params/blob/main/structured_params-openapi/CHANGELOG.md
+  bug_tracker_uri: https://github.com/Syati/structured_params/issues
+  source_code_uri: https://github.com/Syati/structured_params/tree/main/structured_params-openapi
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: OpenAPI drift check for StructuredParams.
+test_files: []