smithy 2.0.0.pre0 → 2.0.0.pre1

data/lib/smithy/views/client/client.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Views
+    module Client
+      # @api private
+      class Client < View
+        def initialize(plan, code_generated_plugins)
+          @plan = plan
+          @model = plan.model
+          _, @service = plan.service.first
+          @plugins = PluginList.new(plan, code_generated_plugins)
+          super()
+        end
+
+        def require_plugins
+          requires = []
+          @plugins.each do |plugin|
+            next if !@plan.destination_root && plugin.require_relative?
+
+            requires << "require#{'_relative' if plugin.require_relative?} '#{plugin.require_path}'"
+          end
+          requires
+        end
+
+        def module_name
+          @plan.module_name
+        end
+
+        def service_name
+          id, = @plan.service.first
+          Model::Shape.name(id).camelize
+        end
+
+        def add_plugins
+          @plugins.map(&:class_name)
+        end
+
+        def docstrings
+          options = @plugins.map(&:options).flatten.sort_by(&:name)
+          documentation = {}
+          options.each do |option|
+            documentation[option.name] = option_docstrings(option) if option.docstring
+          end
+          lines = []
+          documentation.each_value { |value| lines.concat(value) }
+          lines
+        end
+
+        def operations
+          Model::ServiceIndex
+            .new(@model)
+            .operations_for(@plan.service)
+            .map { |id, operation| Operation.new(@service, @model, id, operation) }
+        end
+
+        def gem_name
+          @plan.gem_name
+        end
+
+        def gem_version
+          @plan.gem_version
+        end
+
+        # TODO: re-evaluate this approach - perhaps plugins should register protocol classes with options
+        def protocols
+          @protocols ||= @plan.welds.map(&:protocols).reduce({}, :merge)
+        end
+
+        def waiters
+          waiters = Views::Client::Waiters.new(@plan).waiters
+          return ['{}'] if waiters.empty?
+
+          lines = ['{']
+          waiters.each do |waiter|
+            lines << "  #{waiter.name.underscore}: Waiters::#{waiter.name},"
+          end
+          lines.last.chomp!(',') if lines.last.end_with?(',')
+          lines << '}'
+          lines
+        end
+
+        private
+
+        def option_docstrings(option)
+          lines = []
+          lines << option_tag(option)
+          documentation = option.docstring.split("\n").map { |line| " #{line}" }
+          lines.concat(documentation)
+          lines
+        end
+
+        def option_tag(option)
+          tag = StringIO.new
+          tag << '@option options'
+          tag << " [#{option.doc_type}]" if option.doc_type
+          tag << " :#{option.name}"
+          default = option_default(option)
+          tag << " (#{default})" if default
+          tag.string
+        end
+
+        def option_default(option)
+          default = option.doc_default || option.default
+          return default unless option.name == :protocol
+
+          default.gsub('<DEFAULT_PROTOCOL>', protocols.keys.first || 'nil')
+        end
+
+        # @api private
+        class Operation
+          def initialize(service, model, id, operation)
+            @service = service
+            @model = model
+            @id = id
+            @operation = operation
+            @traits = operation.fetch('traits', {})
+          end
+
+          def docstrings # rubocop:disable Metrics/AbcSize
+            lines = []
+            lines.concat(documentation_docstrings)
+            lines.concat(params_docstrings)
+            lines.concat(OperationExamples.new(@model, method_name, @operation).docstrings)
+            lines.concat(RequestResponseExample.new(@model, method_name, @operation).docstrings)
+            lines.concat(deprecated_docstrings)
+            lines.concat(external_documentation_docstrings)
+            lines.concat(since_docstrings)
+            lines.concat(unstable_docstrings)
+            lines.concat(return_docstrings)
+            lines
+          end
+
+          def method_name
+            Model::Shape.name(@id).underscore
+          end
+
+          private
+
+          def documentation_docstrings
+            @traits.fetch('smithy.api#documentation', '').split("\n")
+          end
+
+          def params_docstrings
+            input_target = @operation['input']['target']
+            input = Model.shape(@model, input_target)
+
+            lines = []
+            lines << Model::YARD.param_docstring(@service, @model, input_target, input)
+            input['members'].each do |member_name, member_shape|
+              target = Model.shape(@model, member_shape['target'])
+              docstrings = Model::YARD.option_docstrings(
+                @service,
+                @model,
+                member_shape['target'],
+                target,
+                member_name.underscore,
+                param_docstrings(member_shape, target)
+              )
+              lines.concat(docstrings)
+            end
+            lines
+          end
+
+          def param_docstrings(member_shape, target)
+            documentation = member_shape.fetch('traits', {}).fetch('smithy.api#documentation', '').split("\n")
+            return documentation unless documentation.empty?
+
+            target.fetch('traits', {}).fetch('smithy.api#documentation', '').split("\n")
+          end
+
+          def deprecated_docstrings
+            return [] unless @traits.key?('smithy.api#deprecated')
+
+            message = @traits['smithy.api#deprecated'].fetch('message', '')
+            since = @traits['smithy.api#deprecated'].fetch('since', '')
+            Model::YARD.deprecated_docstrings(message, since)
+          end
+
+          def external_documentation_docstrings
+            return [] unless @traits.key?('smithy.api#externalDocumentation')
+
+            hash = @traits.fetch('smithy.api#externalDocumentation', {})
+            Model::YARD.external_documentation_docstrings(hash)
+          end
+
+          def since_docstrings
+            return [] unless @traits.key?('smithy.api#since')
+
+            [Model::YARD.since_docstring(@traits['smithy.api#since'])]
+          end
+
+          def unstable_docstrings
+            return [] unless @traits.key?('smithy.api#unstable')
+
+            [Model::YARD.unstable_docstring]
+          end
+
+          def return_docstrings
+            output_target = @operation['output']['target']
+            output = Model.shape(@model, output_target)
+            [Model::YARD.return_docstring(@service, @model, output_target, output)]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/smithy/views/client/client_rbs.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Views
+    module Client
+      # @api private
+      class ClientRbs < View
+        def initialize(plan, code_generated_plugins)
+          @plan = plan
+          @model = plan.model
+          @plugins = PluginList.new(plan, code_generated_plugins)
+          super()
+        end
+
+        def module_name
+          @plan.module_name
+        end
+
+        def option_types
+          @plugins
+            .map(&:options)
+            .flatten
+            .sort_by(&:name)
+            .select(&:docstring)
+            .to_h { |o| [o.name, rbs_type(o)] }
+        end
+
+        def operations
+          Model::ServiceIndex
+            .new(@model)
+            .operations_for(@plan.service)
+            .map { |id, operation| Operation.new(@model, id, operation) }
+        end
+
+        private
+
+        def rbs_type(option)
+          return option.rbs_type if option.rbs_type
+
+          return doc_to_rbs_types(option.doc_type) if option.doc_type
+
+          'untyped'
+        end
+
+        # doc types may specify multiple types combined with ","
+        def doc_to_rbs_types(doc_type)
+          doc_type
+            .to_s
+            .split(',')
+            .map(&:strip)
+            .map { |t| doc_to_rbs_type(t) }
+            .join(' | ')
+        end
+
+        def doc_to_rbs_type(doc_type)
+          case doc_type
+          when 'Boolean' then 'bool'
+          else
+            doc_type
+          end
+        end
+
+        # @api private
+        class Operation
+          def initialize(model, id, operation)
+            @model = model
+            @id = id
+            @operation = operation
+            @input = Input.new(model, operation['input']['target'])
+            @output = Output.new(model, operation['output']['target'])
+          end
+
+          attr_reader :input, :output
+
+          def response_interface
+            "_#{Model::Shape.name(@id)}Response"
+          end
+
+          def name
+            Model::Shape.name(@id).underscore
+          end
+        end
+
+        # @api private
+        class Output
+          def initialize(model, id)
+            @model = model
+            @id = id
+            @shape = Model.shape(model, id)
+          end
+
+          def type
+            Model::RBS.type(@model, @id, @shape)
+          end
+
+          def member_types
+            @shape.fetch('members', {}).to_h do |member_name, member|
+              target = Model.shape(@model, member['target'])
+              [member_name.underscore, Model::RBS.type(@model, member['target'], target)]
+            end
+          end
+        end
+
+        # @api private
+        class Input
+          def initialize(model, id)
+            @model = model
+            @id = id
+            @shape = Model.shape(model, id)
+          end
+
+          def members?
+            @shape.fetch('members', {}).any?
+          end
+
+          # @return [Array<String>]
+          def keyword_args
+            lines = []
+            @shape.fetch('members', {}).each do |name, member|
+              member_lines = kwargs_structure_member(name, member['target'])
+              # top level members all need to be considered optional
+              member_lines[0] = "?#{member_lines[0].strip}"
+              lines += member_lines
+            end
+            lines.last&.chomp!(',')
+            lines
+          end
+
+          private
+
+          def kwargs_structure_member(name, id, level = 0, visited = Set.new)
+            return indent(["#{name.underscore}: untyped,"], level) if visited.include?(id)
+
+            visited << id
+            shape = Model.shape(@model, id)
+            if complex?(shape)
+              kwargs_complex_structure_member(level, name, shape, visited)
+            else
+              indent(["#{name.underscore}: #{Model::RBS.type(@model, nil, shape)},"], level)
+            end
+          end
+
+          def kwargs_complex_structure_member(level, name, shape, visited)
+            lines = kwargs_complex_shape(shape, level, visited)
+            lines[0] = indent("#{name.underscore}: #{lines[0].strip}", level)
+            lines[lines.size - 1] = "#{lines.last},"
+            lines
+          end
+
+          def kwargs_complex_shape(shape, level, visited)
+            case shape['type']
+            when 'list'
+              kwargs_list(shape, level, visited)
+            when 'map'
+              kwargs_map(shape, level, visited)
+            when 'structure', 'union'
+              kwargs_structure(shape, level, visited)
+            else
+              ['untyped']
+            end
+          end
+
+          def kwargs_structure(shape, level, visited)
+            lines = [indent('{', level)]
+            shape.fetch('members', {}).each do |name, member|
+              lines += kwargs_structure_member(name, member['target'], level + 1, visited)
+            end
+            lines[lines.size - 1] = lines.last.chomp(',')
+            lines << indent('}', level)
+            lines
+          end
+
+          def kwargs_list(shape, level, visited)
+            member_target = Model.shape(@model, shape['member']['target'])
+            if complex?(member_target)
+              lines = [indent('Array[', level)]
+              lines += kwargs_complex_shape(member_target, level + 1, visited)
+              lines << indent(']', level)
+              lines
+            else
+              sparse = shape.fetch('traits', {}).key?('smithy.api#sparse')
+              indent(
+                ["Array[#{Model::RBS.type(@model, shape['member']['target'], member_target)}#{'?' if sparse}]"],
+                level
+              )
+            end
+          end
+
+          def kwargs_map(shape, level, visited)
+            key_target = Model.shape(@model, shape['key']['target'])
+            key_type = Model::RBS.type(@model, shape['key']['target'], key_target)
+            value_target = Model.shape(@model, shape['value']['target'])
+            if complex?(value_target)
+              kwargs_complex__map(key_type, level, value_target, visited)
+            else
+              kwargs_simple_map(key_type, level, shape, value_target)
+            end
+          end
+
+          def kwargs_simple_map(key_type, level, shape, value_target)
+            sparse = shape.fetch('traits', {}).key?('smithy.api#sparse')
+            value_type = Model::RBS.type(@model, shape['value']['target'], value_target)
+            indent(
+              ["Hash[#{key_type}, #{value_type}#{'?' if sparse}]"],
+              level
+            )
+          end
+
+          def kwargs_complex__map(key_type, level, value_target, visited)
+            lines = [indent("Hash[#{key_type},", level)]
+            lines += kwargs_complex_shape(value_target, level + 1, visited)
+            lines << indent(']', level)
+            lines
+          end
+
+          def complex?(shape)
+            %w[list map structure union].include?(shape['type'])
+          end
+
+          def indent(str, level)
+            case str
+            when Array then str.map { |s| indent(s, level) }
+            else
+              ('  ' * level) + str
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/smithy/views/client/customizations.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Views
+    module Client
+      # @api private
+      class Customizations < View; end
+    end
+  end
+end

data/lib/smithy/views/client/endpoint_parameter.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Views
+    module Client
+      # @api private
+      class EndpointParameter
+        def initialize(id, data, plan, operation = nil)
+          @id = id
+          @data = data
+          @plan = plan
+          @model = @plan.model
+          @service = @plan.service.values.first
+
+          @operation = operation
+
+          @name = @id.underscore
+          @value, @source = endpoint_parameter_value(operation)
+        end
+
+        attr_reader :id, :data, :name, :source, :value
+
+        def docstrings
+          @data['documentation'].split("\n")
+        end
+
+        def documentation_type
+          case @data['type'].downcase
+          when 'stringarray' then 'Array<String>'
+          when 'string' then 'String'
+          when 'boolean' then 'Boolean'
+          else
+            @data['type']
+          end
+        end
+
+        def rbs_type
+          case @data['type'].downcase
+          when 'stringarray' then 'Array[String]'
+          when 'string' then 'String'
+          when 'boolean' then 'bool'
+          else
+            @data['type']
+          end
+        end
+
+        def default_value
+          default = @data['default']
+          case default
+          when String then "\"#{default}\""
+          when nil then 'nil'
+          else
+            default
+          end
+        end
+
+        def validate_required?
+          @data['required'] && !@data['default']
+        end
+
+        def create_from_config?
+          @source == 'config'
+        end
+
+        def built_in?
+          @data['builtIn']
+        end
+
+        def built_in_binding
+          @built_in_binding ||=
+            @plan.welds
+                 .map(&:endpoint_built_in_bindings)
+                 .map { |b| b[@data['builtIn']] }
+                 .find { |b| !b.nil? }
+        end
+
+        def client_context?
+          @service['traits']['smithy.rules#clientContextParams']&.key?(@id) && !@data['builtIn']
+        end
+
+        def client_context_doc
+          @service['traits']['smithy.rules#clientContextParams'][@id]['documentation']
+        end
+
+        private
+
+        # Highest to lowest priority:
+        # 1. staticContextParams
+        # 2. contextParam
+        # 3. operationContextParams
+        # 4. clientContextParams (always sourced from config)
+        # 5. Built-In Bindings (sourced from config in most cases)
+        # @return [value, source].  source may be one of [operation, config, default]
+        def endpoint_parameter_value(operation)
+          unless operation.nil?
+            value = static_context_param(operation)
+            value = context_param_value(operation) if value.nil?
+            value = operation_context_param_value(operation) if value.nil?
+            source = 'operation' unless value.nil?
+          end
+
+          value, source = client_context_param_value if value.nil?
+          value, source = built_in_param_value if value.nil?
+
+          [value, source]
+        end
+
+        def static_context_param(operation)
+          value = operation.dig('traits', 'smithy.rules#staticContextParams', @id, 'value')
+          if !value.nil? && value.is_a?(String)
+            "\"#{value}\""
+          else
+            value
+          end
+        end
+
+        def context_param_value(operation)
+          return nil unless operation['input']
+
+          input = Model.shape(@model, operation['input']['target'])
+          context_param_member(input['members'])
+        end
+
+        def context_param_member(members)
+          members.find do |(member_name, member_def)|
+            context_param = member_def.fetch('traits', {}).fetch('smithy.rules#contextParam', {})
+            break "params[:#{member_name.underscore}]" if context_param.fetch('name', nil) == @id
+          end
+        end
+
+        def operation_context_param_value(operation)
+          return nil unless operation['input']
+
+          binding = operation.fetch('traits', {}).fetch('smithy.rules#operationContextParams', {})[@id]
+
+          return nil unless binding
+
+          "JMESPath.search(\"#{Util::Underscore.underscore_jmespath(binding['path'])}\", params)"
+        end
+
+        def client_context_param_value
+          return unless client_context?
+
+          ["config.#{name}", 'config']
+        end
+
+        def built_in_param_value
+          return unless @data['builtIn']
+          raise ArgumentError, "Endpoint built-in not available for #{@data['builtIn']}" unless built_in_binding
+
+          [built_in_binding[:render_build].call(@plan, nil), 'config']
+        end
+      end
+    end
+  end
+end

data/lib/smithy/views/client/endpoint_parameters.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Views
+    module Client
+      # @api private
+      class EndpointParameters < View
+        def initialize(plan)
+          @plan = plan
+          @model = plan.model
+          service = @plan.service
+          @endpoint_rules = service.values.first['traits']['smithy.rules#endpointRuleSet']
+          @operations = Model::ServiceIndex.new(@model).operations_for(@plan.service)
+          @parameters = @endpoint_rules['parameters']
+                        .map { |id, data| EndpointParameter.new(id, data, @plan) }
+          @operation_params = build_operation_params
+
+          super()
+        end
+
+        attr_reader :parameters, :operation_params
+
+        def module_name
+          @plan.module_name
+        end
+
+        private
+
+        def build_operation_params
+          operation_params = {}
+          @operations.each do |operation_id, operation|
+            name = operation_id.split('#').last.underscore
+            params = @endpoint_rules['parameters']
+                     .map { |id, data| EndpointParameter.new(id, data, @plan, operation) }
+                     .select { |p| p.source == 'operation' }
+            operation_params[name] = params unless params.empty?
+          end
+          operation_params
+        end
+      end
+    end
+  end
+end

data/lib/smithy/views/client/endpoint_parameters_rbs.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Views
+    module Client
+      # @api private
+      class EndpointParametersRbs < View
+        def initialize(plan)
+          @plan = plan
+          @model = plan.model
+          service = @plan.service
+          @endpoint_rules = service.values.first['traits']['smithy.rules#endpointRuleSet']
+          @operations = Model::ServiceIndex.new(@model).operations_for(@plan.service)
+          @parameters = @endpoint_rules['parameters']
+                        .map { |id, data| EndpointParameter.new(id, data, @plan) }
+
+          super()
+        end
+
+        attr_reader :parameters
+
+        def module_name
+          @plan.module_name
+        end
+      end
+    end
+  end
+end

data/lib/smithy/views/client/endpoint_plugin.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Smithy
+  module Views
+    module Client
+      # @api private
+      class EndpointPlugin < View
+        def initialize(plan)
+          @plan = plan
+          @model = plan.model
+          service = @plan.service.values.first
+          @endpoint_rules = service['traits']['smithy.rules#endpointRuleSet']
+          @parameters = @endpoint_rules['parameters']
+                        .map { |id, data| EndpointParameter.new(id, data, @plan) }
+
+          super()
+        end
+
+        attr_reader :plan, :parameters
+
+        def module_name
+          @plan.module_name
+        end
+      end
+    end
+  end
+end