contractful 0.1.0

data/lib/contractful/contract/postman_import/operation.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Contractful
+  module Contract
+    module PostmanImport
+      # One Postman request as a contract {Definition}, or a note saying why it
+      # cannot become one.
+      module Operation
+        VERBS = %w[get put post patch delete head options].freeze
+        # A built operation: its definition, the origin it calls and its auth.
+        Result = Struct.new(:definition, :origin, :auth, keyword_init: true)
+
+        module_function
+
+        def build(item, scope)
+          request = item['request']
+          verb = request['method'].to_s.downcase
+          return unsupported(item, verb, scope) unless VERBS.include?(verb)
+
+          build_request(item, request, verb, scope)
+        rescue Url::Unresolved, Contract::InvalidDefinition => e
+          scope.note("#{item['name'] || 'request'}: #{e.message} — skipped")
+          nil
+        end
+
+        def build_request(item, request, verb, scope)
+          parsed = Url.parse(request['url'], scope.variables)
+          definition = new_definition(item, verb, parsed, request, scope)
+          add_parts(definition, request, parsed, "#{verb.upcase} #{parsed.path}", scope)
+          Result.new(definition: definition, origin: parsed.origin, auth: request['auth'])
+        end
+
+        def unsupported(item, verb, scope)
+          scope.note("#{item['name'] || 'request'}: #{verb.upcase} is not a supported method — skipped")
+          nil
+        end
+
+        def new_definition(item, verb, parsed, request, scope)
+          Definition.new(scope.name_for(item, verb, parsed.path), verb.to_sym, parsed.path,
+                         description: description(request))
+        end
+
+        def add_parts(definition, request, parsed, label, scope)
+          add_query(definition, parsed.query, scope, label)
+          add_headers(definition, request['header'], scope, label)
+          Body.apply(definition, request['body'], scope, label)
+        end
+
+        def description(request)
+          text = request['description']
+          text = text['content'] if text.is_a?(Hash)
+          text.is_a?(String) && !text.empty? ? text : nil
+        end
+
+        # Query keys become untyped, optional params; the example values are not kept.
+        def add_query(definition, pairs, scope, label)
+          pairs.map(&:first).each { |name| add_query_key(definition, name, scope, label) }
+        end
+
+        def add_query_key(definition, name, scope, label)
+          unless name.match?(PostmanImport::IDENTIFIER)
+            return scope.note("#{label}: query parameter #{name.inspect} is not a valid identifier — skipped")
+          end
+          if definition.params.key?(name.to_sym)
+            return scope.note("#{label}: query parameter #{name.inspect} collides with another param — skipped")
+          end
+
+          definition.param(name.to_sym)
+        end
+
+        def add_headers(definition, headers, scope, label)
+          PostmanImport.enabled(headers).each do |header|
+            name = header['key'].to_s
+            next if not_mapped_header?(name, scope, label)
+
+            add_header(definition, name, header['value'].to_s, scope, label)
+          end
+        end
+
+        def not_mapped_header?(name, scope, label)
+          case name.downcase
+          when 'content-type' then true # the body decides the content type
+          when 'authorization'
+            scope.note("#{label}: Authorization is not mapped; declare auth (see the auth hints)")
+            true
+          else false
+          end
+        end
+
+        # A static value becomes the default, so the header is sent unless the caller
+        # overrides it; a value with a variable is left for the caller to supply.
+        def add_header(definition, name, value, scope, label)
+          key = OpenAPIImport.header_param_key(name)
+          unless name.match?(Param::HTTP_TOKEN) && key && !definition.params.key?(key)
+            return scope.note("#{label}: header #{name.inspect} cannot be declared (name or duplicate) — skipped")
+          end
+          return definition.param(key, String, header: name) if value.empty? || value.include?('{{')
+          unless Param::HEADER_VALUE.match?(value)
+            return scope.note("#{label}: header #{name.inspect} has control characters in its value — skipped")
+          end
+
+          definition.param(key, String, header: name, default: value)
+        end
+      end
+    end
+  end
+end

data/lib/contractful/contract/postman_import/scope.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Contractful
+  module Contract
+    module PostmanImport
+      # The notes and contract names of one import.
+      class Scope
+        attr_reader :variables, :notes
+        attr_writer :inferred_body
+
+        def initialize(variables)
+          @variables = variables
+          @notes = []
+          @names = OpenAPIImport::Context.new({})
+          @inferred_body = false
+        end
+
+        def note(message)
+          @notes << message unless @notes.include?(message)
+        end
+
+        def inferred_body?
+          @inferred_body
+        end
+
+        # A contract name from the request name, or from the method and path when
+        # the request has no usable name.
+        def name_for(item, verb, path)
+          base = OpenAPIImport.snake_case(item['name'].to_s).gsub(/[^a-zA-Z0-9_]+/, '_').gsub(/\A_+|_+\z/, '')
+          base = "#{verb} #{path}".gsub(/[^a-zA-Z0-9]+/, '_').gsub(/\A_+|_+\z/, '') if base.empty?
+          base = "_#{base}" if base.match?(/\A\d/)
+          @names.unique_name(base)
+        end
+      end
+    end
+  end
+end

data/lib/contractful/contract/postman_import/url.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module Contractful
+  module Contract
+    module PostmanImport
+      # Turns a Postman request URL into an origin, a path template and query
+      # pairs. {{variables}} resolve from the collection and the caller. The
+      # origin and the path must resolve, since a contract needs both.
+      module Url
+        VARIABLE = /\{\{\s*([^{}\s]+)\s*\}\}/
+        ABSOLUTE = %r{\A([a-zA-Z][a-zA-Z0-9+.-]*://[^/]+)(/.*)?\z}
+
+        # The origin and path of a request, and its enabled query pairs.
+        Parsed = Struct.new(:origin, :path, :query, keyword_init: true)
+
+        # Raised when the origin or the path cannot be resolved.
+        class Unresolved < StandardError; end
+
+        module_function
+
+        def parse(request_url, variables)
+          text = substitute(raw(request_url), variables)
+          main, query_text = text.split('?', 2)
+          main ||= ''
+          variable = main.scan(VARIABLE).first
+          raise Unresolved, "unresolved variable {{#{variable.first}}}" if variable
+
+          match = ABSOLUTE.match(main)
+          raise Unresolved, "no absolute URL for #{main.inspect}" unless match
+
+          Parsed.new(origin: match[1], path: match[2] || '/', query: query(request_url, query_text))
+        end
+
+        # The URL as one string: Postman stores it as a string or as an object.
+        def raw(request_url)
+          return request_url if request_url.is_a?(String)
+          return '' unless request_url.is_a?(Hash)
+          return request_url['raw'].to_s if request_url['raw']
+
+          "#{scheme_of(request_url)}#{authority(request_url)}#{path_of(request_url)}"
+        end
+
+        def scheme_of(request_url)
+          request_url['protocol'] ? "#{request_url['protocol']}://" : ''
+        end
+
+        def authority(request_url)
+          host = Array(request_url['host']).join('.')
+          request_url['port'] ? "#{host}:#{request_url['port']}" : host
+        end
+
+        def path_of(request_url)
+          path = Array(request_url['path']).join('/')
+          path.empty? ? '' : "/#{path}"
+        end
+
+        def substitute(text, variables)
+          text.gsub(VARIABLE) do
+            name = Regexp.last_match(1)
+            variables.fetch(name) { "{{#{name}}}" }
+          end
+        end
+
+        # The object form's query list wins over the query text of the raw URL.
+        def query(request_url, query_text)
+          if request_url.is_a?(Hash) && request_url['query']
+            return PostmanImport.enabled(request_url['query']).map { |entry| [entry['key'].to_s, entry['value'].to_s] }
+          end
+          return [] unless query_text
+
+          URI.decode_www_form(query_text)
+        rescue ArgumentError
+          []
+        end
+      end
+    end
+  end
+end

data/lib/contractful/contract/postman_import.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'openapi_import'
+require_relative 'postman_import/scope'
+require_relative 'postman_import/url'
+require_relative 'postman_import/body'
+require_relative 'postman_import/auth'
+require_relative 'postman_import/operation'
+
+module Contractful
+  module Contract
+    # Imports a Postman Collection (a v2.0 or v2.1 JSON export) as contract
+    # declarations, the way {OpenAPIImport} imports OpenAPI documents. It is
+    # opt-in and development-time:
+    #
+    #   require 'contractful/contract/postman_import'
+    #
+    # A collection carries example values rather than schemas, so its params are
+    # untyped and none is required, except a GraphQL query. Everything that is not
+    # mapped is reported on {Import#notes}.
+    module PostmanImport
+      FORMAT = 'Postman Collection v2.1'
+      IDENTIFIER = /\A[a-zA-Z_][a-zA-Z0-9_]*\z/
+
+      # The import result, shared with {OpenAPIImport}.
+      Import = OpenAPIImport::Import
+
+      module_function
+
+      # @param source a collection Hash, a path, or JSON text
+      # @param variables [Hash] values for {{variables}} the collection does not
+      #   define, such as an environment's baseUrl; they override the collection's
+      # @param only [Array<Symbol>] keep only these operation names
+      # @param except [Array<Symbol>] drop these operation names
+      # @return [OpenAPIImport::Import]
+      def import(source, variables: {}, only: nil, except: nil)
+        collection = load(source)
+        scope = Scope.new(collection_variables(collection).merge(string_hash(variables)))
+        results = requests(collection['item']).filter_map { |item| Operation.build(item, scope) }
+        base = base_origin(results, scope)
+        definitions = definitions_for(results, base, only, except)
+        summarize(scope, definitions)
+        assemble(collection, results, base, definitions, scope)
+      end
+
+      def assemble(collection, results, base, definitions, scope)
+        Import.new(document: document(collection), base_url: base, auth_hints: auth_hints(collection, results),
+                   definitions: definitions, notes: scope.notes)
+      end
+
+      def definitions(source, variables: {}, only: nil, except: nil)
+        import(source, variables: variables, only: only, except: except).definitions
+      end
+
+      def to_ruby(source, class_name: 'GeneratedClient', variables: {}, only: nil, except: nil)
+        import(source, variables: variables, only: only, except: except).to_ruby(class_name: class_name)
+      end
+
+      def load(source)
+        collection = source.is_a?(Hash) ? source : parse(source)
+        unless collection.is_a?(Hash) && collection['item'].is_a?(Array)
+          raise OpenAPIImport::Error, 'not a Postman collection: expected an "item" array'
+        end
+
+        collection
+      end
+
+      def parse(source)
+        JSON.parse(text_of(source))
+      rescue JSON::ParserError => e
+        raise OpenAPIImport::Error, "invalid JSON for a Postman collection: #{e.message}"
+      end
+
+      def text_of(source)
+        return source if source.is_a?(String) && source.lstrip.start_with?('{', '[')
+        raise OpenAPIImport::Error, "no such file: #{source}" unless File.file?(source.to_s)
+
+        File.read(source.to_s)
+      end
+
+      # Request items in document order, with folders flattened away.
+      def requests(items)
+        list(items).flat_map do |item|
+          next [] unless item.is_a?(Hash)
+          next [item] if item['request'].is_a?(Hash)
+
+          requests(item['item'])
+        end
+      end
+
+      # The origin most requests call. Requests on another origin cannot share
+      # one client's base URL, so they are skipped and noted.
+      def base_origin(results, scope)
+        base = results.map(&:origin).tally.max_by(&:last)&.first
+        results.each do |result|
+          next if result.origin == base
+
+          scope.note("#{result.definition.name}: calls #{result.origin}, not #{base} — one client has " \
+                     'one base URL, so it is skipped')
+        end
+        base
+      end
+
+      def definitions_for(results, base, only, except)
+        results.each_with_object({}) do |result, out|
+          name = result.definition.name
+          out[name] = result.definition if result.origin == base && !OpenAPIImport.skip_name?(name, only, except)
+        end
+      end
+
+      def summarize(scope, definitions)
+        return if definitions.empty?
+
+        scope.note('a Postman collection carries example values, not schemas: params are untyped and ' \
+                   'none is required, except a GraphQL query')
+        return unless scope.inferred_body?
+
+        scope.note('body fields come from example bodies: their types are unknown, and strict_params is ' \
+                   'off on those operations, because an example may omit fields')
+      end
+
+      def document(collection)
+        { 'info' => { 'title' => info_name(collection) }, 'x-contractful-source' => FORMAT }
+      end
+
+      def auth_hints(collection, results)
+        prefix = env_prefix(collection)
+        auths = ([collection['auth']] + results.map(&:auth)).compact.uniq
+        auths.flat_map { |auth| Auth.hints(auth, prefix) }.uniq
+      end
+
+      def info_name(collection)
+        info = collection['info']
+        info.is_a?(Hash) ? info['name'].to_s : ''
+      end
+
+      def env_prefix(collection)
+        name = info_name(collection).upcase.gsub(/[^A-Z0-9]+/, '_').gsub(/\A_+|_+\z/, '')
+        name.empty? ? 'POSTMAN' : name
+      end
+
+      def collection_variables(collection)
+        list(collection['variable']).each_with_object({}) do |entry, out|
+          out[entry['key'].to_s] = entry['value'].to_s if entry.is_a?(Hash) && entry['key']
+        end
+      end
+
+      def string_hash(hash)
+        hash.to_h { |key, value| [key.to_s, value.to_s] }
+      end
+
+      # The items of an array field, or none when the field is missing or malformed.
+      def list(value)
+        value.is_a?(Array) ? value : []
+      end
+
+      # The entries of a key/value list that are not disabled.
+      def enabled(entries)
+        list(entries).select { |entry| entry.is_a?(Hash) && !entry['disabled'] }
+      end
+    end
+  end
+end

data/lib/contractful/contract/response_field.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module Contractful
+  module Contract
+    # A single declared field of a response payload — the "open" side of a
+    # contract.
+    #
+    # Response schemas are deliberately OPEN, unlike request params:
+    #
+    #   * +required+ and +type+ BIND: a declared required field that is
+    #     missing (or null), or a field whose value does not match the
+    #     declared type, raises {UnexpectedResponse} when the response is
+    #     received.
+    #   * Everything else is ADDITIVE DATA: fields that were never declared
+    #     are passed through untouched, and declared +inclusion+ sets are
+    #     NOT enforced unless <tt>strict: true</tt> is given — a new enum
+    #     member the client does not know about yet is data, not an error.
+    #   * Values are never coerced: what the server sent is what you get.
+    #
+    # Example:
+    #
+    #   contract :create_order, 'POST /orders' do
+    #     response_field :order_id, :string, required: true
+    #     response_field :status, :string   # open: new states are additive
+    #   end
+    class ResponseField
+      # Symbol aliases accepted for +type+. +:boolean+ matches true/false,
+      # +:number+ matches any Numeric (Integer or Float).
+      SYMBOL_TYPES = {
+        string: String,
+        integer: Integer,
+        float: Float,
+        array: Array,
+        hash: Hash,
+        number: :number,
+        boolean: :boolean
+      }.freeze
+
+      attr_reader :name, :type, :inclusion, :description
+
+      def initialize(name, type = nil, required: false, inclusion: nil,
+                     strict: false, description: nil)
+        @name = name.to_sym
+        @type = normalize_type(type)
+        @required = required ? true : false
+        @inclusion = inclusion
+        @strict = strict ? true : false
+        @description = description
+        validate_definition!
+      end
+
+      def required?
+        @required
+      end
+
+      def strict?
+        @strict
+      end
+
+      # Check a parsed JSON object against this field.
+      #
+      # JSON.parse yields String-keyed hashes, so both Symbol and String key
+      # spellings are looked up (Symbol first — internal hashes tend to be
+      # symbol-keyed).
+      #
+      # @return [Array<String>] every violation message (empty when the
+      #   payload conforms)
+      def violations_for(payload)
+        if payload.key?(@name)
+          value = payload[@name]
+        elsif payload.key?(string_name = @name.to_s)
+          value = payload[string_name]
+        else
+          return @required ? ["field :#{@name} is required but missing"] : []
+        end
+
+        msgs = []
+        if value.nil?
+          msgs << "field :#{@name} is required but was null" if @required
+        else
+          msgs.concat(type_violations(value))
+          msgs.concat(inclusion_violations(value))
+        end
+        msgs
+      end
+
+      # Human-readable summary used in error messages and introspection.
+      def to_s
+        parts = [type_name]
+        parts << 'required' if @required
+        parts << "in #{inclusion.inspect}" if @inclusion
+        parts << 'strict' if @strict
+        parts.join(', ')
+      end
+
+      private
+
+      def normalize_type(type)
+        return nil if type.nil?
+
+        if type.is_a?(Symbol)
+          unless SYMBOL_TYPES.key?(type)
+            raise InvalidDefinition,
+                  "unsupported response_field type #{type.inspect} for :#{@name} " \
+                  "(supported symbols: #{SYMBOL_TYPES.keys.join(', ')})"
+          end
+          return SYMBOL_TYPES[type]
+        end
+
+        unless type.is_a?(Class)
+          raise InvalidDefinition,
+                "unsupported response_field type #{type.inspect} for :#{@name} " \
+                '(expected a Class or a supported symbol)'
+        end
+
+        type
+      end
+
+      def validate_definition!
+        return unless @inclusion && !@inclusion.respond_to?(:include?)
+
+        raise InvalidDefinition,
+              "response_field :#{@name}: inclusion must respond to #include? " \
+              "(got #{@inclusion.inspect})"
+        
+      end
+
+      def type_violations(value)
+        return [] unless @type
+
+        case @type
+        when :boolean
+          unless value.equal?(true) || value.equal?(false)
+            return ["field :#{@name} expected boolean, got #{value.class}"]
+          end
+        when :number
+          return ["field :#{@name} expected number, got #{value.class}"] unless value.is_a?(Numeric)
+        else
+          return ["field :#{@name} expected #{type_name}, got #{value.class}"] unless value.is_a?(@type)
+        end
+        []
+      end
+
+      def inclusion_violations(value)
+        # Open-schema default: new enum members are additive data. Only an
+        # explicitly strict field treats an unknown value as a violation.
+        return [] unless @inclusion && @strict
+
+        unless @inclusion.include?(value)
+          return ["field :#{@name} value #{value.inspect} " \
+                  "is not in #{@inclusion.inspect}"]
+        end
+        []
+      end
+
+      def type_name
+        case @type
+        when nil then 'untyped'
+        when :boolean then 'boolean'
+        when :number then 'number'
+        when Class then @type.name || 'anonymous class'
+        else @type.to_s
+        end
+      end
+    end
+  end
+end