shaf 1.6.1 → 2.0.0

data/lib/shaf/upgrade/version.rb

@@ -8,7 +8,7 @@ module Shaf
       alias eql? ==
 
       class UpgradeVersionError < StandardError
-        def initialize(message = "")
+        def initialize(message = '')
           super("Bad upgrade version: #{message}")
         end
       end
@@ -16,25 +16,26 @@ module Shaf
       def initialize(version)
         case version
         when Version
-          @major, @minor, @patch = [:major, :minor, :patch].map { |m| version.send m }
+          @major, @minor, @patch = version.to_a
         when /\d+\.\d+(\.\d+)?/
           @major, @minor, @patch = split_version(version)
         else
-          raise UpgradeVersionError.new(version)
+          raise UpgradeVersionError, version
         end
       end
 
       def <=>(other)
-        case other
-        when String
-          compare_version(*split_version(other))
-        when Version
-          compare_version(other.major, other.minor, other.patch)
-        end
+        return unless other
+        other = self.class.new(other)
+        compare_version(other.major, other.minor, other.patch)
       end
 
       def to_s
-        [major, minor, patch].join('.')
+        to_a.join('.')
+      end
+
+      def to_a
+        [major, minor, patch]
       end
 
       private

data/lib/shaf/utils.rb

@@ -3,6 +3,8 @@
 require 'erb'
 require 'forwardable'
 require 'yaml'
+require 'csv'
+require 'zlib'
 require 'shaf/version'
 
 module Shaf
@@ -35,12 +37,19 @@ module Shaf
         noun[0..-2]
       end
 
-      def symbolize(str)
-        :"#{str}"
+      def symbol_string(str)
+        str.to_sym.inspect
       end
 
-      def symbol_string(str)
-        symbolize(str).inspect
+      def symbol_or_quoted_string(obj)
+        case obj
+        when Symbol
+          obj.inspect
+        when Numeric
+          obj
+        else
+          "'#{obj.to_s}'"
+        end
       end
 
       def environment
@@ -98,6 +107,11 @@ module Shaf
         end
       end
 
+      def iana_link_relations_csv
+        zip_file = File.join(gem_root, 'iana_link_relations.csv.gz')
+        Zlib::GzipReader.open(zip_file) { |content| CSV.new(content.read) }
+      end
+
       private
 
       def erb(content, binding: nil)
@@ -107,7 +121,7 @@ module Shaf
       end
     end
 
-    def_delegators Utils, :pluralize, :singularize, :symbolize, :symbol_string, :gem_root, :rackify_header
+    def_delegators Utils, :pluralize, :singularize, :symbol_string, :gem_root, :rackify_header
 
     def project_root
       return @project_root if defined? @project_root

data/lib/shaf/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Shaf
-  VERSION = "1.6.1"
+  VERSION = '2.0.0'
 end

data/lib/shaf/yard.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'yard'
+require 'shaf/yard/serializer_handler'
+require 'shaf/yard/attribute_method_handler'
+require 'shaf/yard/link_method_handler'
+require 'shaf/yard/profile_method_handler'
+require 'shaf/yard/resource_object'
+require 'shaf/yard/profile_object'
+require 'shaf/yard/attribute_object'
+require 'shaf/yard/link_object'
+require 'shaf/yard/nested_attributes'
+require 'shaf/yard/parser'
+
+module Shaf
+  module Yard
+    CUSTOM_TAGS = [
+      ['Request Header', :request_header, :with_name],
+      ['Reponse Header', :response_header, :with_name],
+      ['Example Request', :example_request],
+      ['Example Response', :example_response],
+      ['Description', :description],
+      ['HTTP method', :http_method],
+      ['Attribute type', :type, :with_types]
+    ].freeze
+
+    CUSTOM_TAGS.each do |tag|
+      YARD::Tags::Library.define_tag(*tag)
+    end
+
+    TEMPLATE_PATH = File.join(Utils.gem_root, 'yard_templates').freeze
+    YARD::Templates::Engine.register_template_path TEMPLATE_PATH
+  end
+end

data/lib/shaf/yard/attribute_method_handler.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'shaf/yard/base_method_handler'
+
+module Shaf
+  module Yard
+    # Handles call to Shaf::Serializer::attribute
+    class AttributeMethodHandler < BaseMethodHandler
+      handles method_call(:attribute)
+
+      def object
+        AttributeObject.new(serializer_namespace, name).tap do |attr|
+          attr.dynamic = true
+          attr.name = name
+        end
+      end
+    end
+  end
+end

data/lib/shaf/yard/attribute_object.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Shaf
+  module Yard
+    class AttributeObject < ::YARD::CodeObjects::Base
+      attr_accessor :name
+
+      def documentation
+        profile_doc || 'Not documented'
+      end
+
+      def profile
+        return unless namespace.respond_to? :profile
+        @profile ||= namespace.profile
+      end
+
+      def value_types
+        Array(descriptor&.type).compact.map(&:to_s)
+      end
+
+      def profile_doc
+        descriptor&.doc
+      end
+
+      def descriptor
+        profile&.find_attribute(name)
+      end
+    end
+  end
+end

data/lib/shaf/yard/base_method_handler.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Shaf
+  module Yard
+    class BaseMethodHandler < ::YARD::Handlers::Ruby::Base
+      namespace_only
+
+      def process
+        return unless serializer_namespace
+
+        register object
+      end
+
+      def name
+        call_params.first.yield_self do |name|
+          # remove single colon. Sometimes symbols get the :, (e.g. :self)
+          name.sub(/\A:(?!:)/, '')
+        end
+      end
+
+      def object
+        raise NotImplementedError, "#{self} must implement #object"
+      end
+
+      def serializer_namespace
+        @serializer_namespace ||= YARD::Registry.at ResourceObject.path(namespace)
+      end
+    end
+  end
+end

data/lib/shaf/yard/link_method_handler.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'shaf/yard/base_method_handler'
+
+module Shaf
+  module Yard
+    # Handles call to Shaf::Serializer::link
+    class LinkMethodHandler < BaseMethodHandler
+      handles method_call(:link)
+
+      def object
+        LinkObject.new(serializer_namespace, name).tap do |link|
+          link.dynamic = true
+          link.rel = name
+          link.curie = curie
+        end
+      end
+
+      def name
+        super.sub(/[^:]+:/, '')
+      end
+
+      def curie
+        m = name.match(/([^:]+):/)
+        return m[1] if m
+
+        statement.parameters(false).each do |param|
+          next unless param&.respond_to? :source
+
+          str = String(param.source)
+          m = str.match(/curie:\s:?(\w+)/)
+          return m[1] if m
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/shaf/yard/link_object.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'shaf/api_doc/link_relations'
+
+module Shaf
+  module Yard
+    class LinkObject < ::YARD::CodeObjects::Base
+      attr_accessor :rel, :curie
+
+      def curie?
+        !!curie
+      end
+
+      def documentation
+        profile_doc || iana_doc || 'Undocumented'
+      end
+
+      def profile_object
+        return unless profile
+        return unless namespace.respond_to? :profile_objects
+
+        namespace.profile_objects.find do |po|
+          po.profile == profile
+        end
+      end
+
+      def profile
+        return @profile if defined? @profile
+        return unless namespace.respond_to? :profile
+        profile = namespace.profile
+        @profile = profile&.find_relation(name) && profile
+      end
+
+      def descriptor
+        profile&.find_relation(rel)
+      end
+
+      def profile_doc
+        descriptor&.doc
+      end
+
+      def http_methods
+        Array(descriptor&.http_methods)
+      end
+
+      def href
+        descriptor&.href
+      end
+
+      def content_type
+        descriptor&.content_type
+      end
+
+      def iana_doc
+        ApiDoc::LinkRelations.load_iana
+        ApiDoc::LinkRelations[name.to_sym]&.description
+      end
+    end
+  end
+end

data/lib/shaf/yard/nested_attributes.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Shaf
+  module Yard
+    module NestedAttributes
+      def nested_attributes_for(descriptor)
+        return {} unless descriptor
+
+        base_key = nested_key(descriptor)
+        nested_attributes(descriptor)
+          .yield_self { |nested| flatten(nested, base_key) }
+      end
+
+      def nested_attributes(descriptor)
+        attrs = Array(descriptor&.attributes)
+        attrs.each_with_object({}) do |attr, nested|
+          nested[attr] = nested_attributes(attr)
+        end.transform_values { |v| v.empty? ? nil : v }
+      end
+
+      def flatten(nested, base_key)
+        return {} if !nested || nested.empty?
+
+        nested.each_with_object({}) do |(desc, nested), all|
+          key = nested_key(base_key, desc)
+          all[key] = desc
+          next unless nested
+          all.merge!(flatten(nested, key))
+        end
+      end
+
+      def nested_key(base_key = nil, desc)
+        [base_key, desc.name].compact.join('.')
+      end
+    end
+  end
+end

data/lib/shaf/yard/parser.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Shaf
+  module Yard
+    class Parser
+      def self.call(name: '')
+        new(name).parse!
+      end
+
+      def initialize(name)
+        @name = name.downcase
+      end
+
+      def parse!
+        verify_exists! unless name.empty?
+        ::YARD.parse pattern
+      end
+
+      private
+
+      attr_reader :name
+
+      def pattern
+        return file_path if file_path
+
+        base = ['*', suffix].join
+        File.join(base_dir, '**', base)
+      end
+
+      def suffix
+        '_serializer.rb'
+      end
+
+      def verify_exists!
+        file_path or raise <<~ERR
+          Could not find a matching serializer for #{name}.
+          Looked in: #{base_dir}
+          Using suffix: #{suffix}
+        ERR
+      end
+
+      def file_path
+        @file_path ||= lookup_path
+      end
+
+      def base_dir
+        File.join(Shaf::Settings.app_dir || 'api', 'serializers')
+      end
+
+      def lookup_path
+        return if name.empty?
+
+        path = File.join(base_dir, name)
+        return path if File.exist? path
+
+        with_suffix = [path, suffix].join
+        return with_suffix if File.exist? with_suffix
+
+        with_extension = [path, '.rb'].join
+        with_extension if File.exist? with_extension
+      end
+    end
+  end
+end

data/lib/shaf/yard/profile_method_handler.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'shaf/yard/base_method_handler'
+require 'shaf/profiles'
+require 'shaf/utils'
+
+module Shaf
+  module Yard
+    # Handles call to Shaf::Serializer::profile
+    class ProfileMethodHandler < BaseMethodHandler
+      include Shaf::Utils
+
+      handles method_call(:profile)
+
+      def process
+        serializer = serializer_namespace
+        profile = shaf_profile
+        return unless serializer
+
+        serializer.profile = profile
+
+        register object
+        serializer_namespace.profile_objects << object
+      end
+
+      def shaf_profile
+        return @shaf_profile if defined? @shaf_profile
+
+        bootstrap(env: ENV['RACK_ENV'])
+
+        @shaf_profile = Shaf::Profiles.find name
+      end
+
+      def object
+        # Put the Profile object on the the same namespace level as
+        # the serializer. Typically this it the root namespace
+        ns = namespace.namespace
+
+        name = shaf_profile&.to_s || self.name
+        name.gsub!(/(Shaf|Profiles)?::/, "")
+
+        name << "Profile" unless name.end_with? "Profile"
+
+        ProfileObject.new(ns, name).tap do |obj|
+          obj.dynamic = true
+          obj.profile = shaf_profile
+        end
+      end
+    end
+  end
+end