docrb-html 0.2.0

data/lib/renderer/component/method_argument.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+class Renderer
+  class Component
+    class MethodArgument < Component
+      prop :type, :name, :value, :value_type, :computed
+
+      def prepare
+        @computed = {
+          rest: rest_arg,
+          name:,
+          continuation: continuation_for_type,
+          value: value_for_argument
+        }
+      end
+
+      def continuation_for_type
+        if type == "kwarg" || type == "kwoptarg"
+          :colon
+        elsif type&.index("opt")&.zero?
+          :equal
+        end
+      end
+
+      REST_ARG_BY_TYPE = {
+        "kwrestarg" => :double,
+        "restarg" => :single,
+        "blockarg" => :block
+      }.freeze
+
+      def rest_arg
+        REST_ARG_BY_TYPE[type]
+      end
+
+      def value_for_argument
+        return if value_type.nil?
+
+        case value_type
+        when "sym"
+          { kind: :symbol, value: }
+        when "bool"
+          { kind: :symbol, value: value.inspect }
+        when "nil"
+          { kind: :symbol, value: "nil" }
+        when "int"
+          { kind: :number, value: }
+        when "str"
+          { kind: :string, value: }
+        when "send"
+          method_call_argument(value)
+        when "const"
+          const_value(value)
+        else
+          { kind: :plain, value: }
+        end
+      end
+
+      def method_call_argument(value)
+        class_path = value[:target].map do |i|
+          next { kind: :symbol, value: "self" } if i == "self"
+
+          # TODO: Is this plain?
+          [{ kind: :class_or_module, value: i }, { kind: :plain, value: "::" }]
+        end.flatten
+
+        class_path.pop
+
+        {
+          kind: :method_call_argument,
+          value: [
+            class_path,
+            { kind: :plain, value: "." },
+            { kind: :plain, value: value[:name] }
+          ].flatten
+        }
+      end
+
+      def const_value(value)
+        class_path = value[:target].map do |i|
+          # TODO: Is this plain?
+          [{ kind: :class_or_module, value: i }, { kind: :continuation, double: true }]
+        end.flatten
+
+        class_path.pop
+
+        if class_path.empty?
+          return {
+            kind: :const,
+            value: [
+              { kind: :class_or_module, value: value[:name] }
+            ].flatten
+          }
+        end
+
+        {
+          kind: :const,
+          value: [
+            class_path,
+            { kind: :continuation, double: true },
+            { kind: :class_or_module, value: value[:name] }
+          ].flatten
+        }
+      end
+    end
+  end
+end

data/lib/renderer/component/method_display.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class Renderer
+  class Component
+    class MethodDisplay < Component
+      prop :visibility, :type, :name, :href, :args, :doc, :decoration, :short_type
+    end
+  end
+end

data/lib/renderer/component/method_list.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class Renderer
+  class Component
+    class MethodList < Component
+      prop :list
+    end
+  end
+end

data/lib/renderer/component/project_header.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class Renderer
+  class Component
+    class ProjectHeader < Component
+      prop :name, :description, :owner, :license, :links
+    end
+  end
+end

data/lib/renderer/component/reference.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class Renderer
+  class Component
+    class Reference < Component
+      prop :ref, :unresolved, :path
+
+      def prepare
+        @unresolved = !ref[:ref_path]
+        return if @unresolved
+
+        components = ref[:ref_path].dup
+        @path = if ref[:ref_type] == "method"
+                  method_name = components.pop
+                  parent_name = components.pop
+                  components + ["#{parent_name}.html#{method_name}"]
+                else
+                  last = components.pop
+                  (components + ["#{last}.html"]).compact
+                end
+      end
+    end
+  end
+end

data/lib/renderer/component/symbol.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class Renderer
+  class Component
+    class Symbol < Component
+      prop :name
+    end
+  end
+end

data/lib/renderer/component/tab_bar.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class Renderer
+  class Component
+    class TabBar < Component
+      prop :items, :selected_index
+    end
+  end
+end

data/lib/renderer/component/text_block.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class Renderer
+  class Component
+    class TextBlock < Component
+      prop :list
+
+      def prepare
+        return unless !@list.nil? && !@list.is_a?(Array)
+
+        @list = [{ type: "html", contents: @list }]
+      end
+    end
+  end
+end

data/lib/renderer/component/type_definition.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class Renderer
+  class Component
+    class TypeDefinition < Component
+      prop :type, :name, :href
+    end
+  end
+end

data/lib/renderer/component/typedef.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class Renderer
+  class Component
+    class Typedef < Component
+      prop :name
+    end
+  end
+end

data/lib/renderer/component.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+class Renderer
+  class Component
+    attr_accessor :id
+
+    def self.prop(*names)
+      attr_accessor(*names)
+
+      @props ||= []
+      @props.append(*names)
+    end
+
+    class << self
+      attr_writer :template
+    end
+
+    def self.template
+      return @template_instance if @template_instance
+
+      t_name = @template || name.split("::").last.snakify
+      @template_instance = Template.new("templates/#{t_name}.erb")
+    end
+
+    def props = @props ||= self.class.instance_variable_get(:@props) || []
+    def template = self.class.template
+
+    def initialize(**kwargs)
+      @id = kwargs.delete(:id)
+      kwargs.each do |k, v|
+        raise ArgumentError, "Unknown property #{k} for #{self.class.name}" unless props.include? k
+
+        send("#{k}=", v)
+      end
+    end
+
+    def prepare; end
+
+    def render(&)
+      prepare
+      opts = props.map { [_1, send(_1)] }.to_h
+      opts[:id] = @id
+      template.render(HELPERS, **opts, &)
+    end
+  end
+end
+
+Dir[Pathname.new(__dir__).join("component/*.rb")].each do |file|
+  require_relative "component/#{Pathname.new(file).basename}"
+end

data/lib/renderer/core_extensions.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class String
+  def snakify
+    gsub(/::/, "/")
+      .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+      .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+      .tr("-", "_")
+      .downcase
+  end
+end

data/lib/renderer/defs/specialized_object.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+class Renderer
+  class Defs
+    class SpecializedObject
+      def initialize(obj, parent, provider)
+        @obj = obj
+        @provider = provider
+        prepare(parent)
+      end
+
+      def self.specialize(obj, parent, provider)
+        return nil if obj.nil?
+
+        new(obj, parent, provider)
+      end
+
+      def [](key) = @obj[key]
+      def fetch(*, **, &) = @obj.fetch(*, **, &)
+
+      def resolve(name)
+        named = named_as(name)
+        modules.find(&named) \
+        || classes.find(&named) \
+        || attributes&.find(&named) \
+        || defs.find(&named) \
+        || sdefs.find(&named)
+      end
+
+      def resolve_inheritance(name)
+        named = named_as(name)
+        modules.find(&named) \
+        || classes.find(&named) \
+        || parent&.resolve_inheritance(name)
+      end
+
+      def resolve_parent(name)
+        parent = self[:parent]
+        return { type: "Unknown Ref", name: } unless parent
+
+        parent.resolve(name) || parent.resolve_parent(name)
+      end
+
+      def resolve_path(path)
+        p = path.dup
+        obj = self
+        until p.empty?
+          obj = obj.resolve(p[0])
+          return unless obj
+
+          p.shift
+        end
+        obj
+      end
+
+      def resolve_qualified(obj)
+        result = nil
+        query = nil
+
+        if obj[:class_path]&.length&.> 0
+          query = obj[:class_path] + [obj[:name]]
+          result = root.resolve_path(query)
+        else
+          query = obj[:name]
+          result = resolve(query)
+          result ||= resolve_inheritance(query)
+        end
+
+        puts "Qualified resolution of #{query.inspect} by #{name} failed." unless result
+
+        result
+      end
+
+      def method_missing(method_name, *args, **kwargs, &)
+        var = "@#{method_name}".to_sym
+        if instance_variables.include?(var)
+          instance_variable_get(var)
+        elsif @obj.key? method_name
+          @obj.fetch(method_name)
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        instance_variables.include?("@#{method_name}".to_sym) || @obj.key?(method_name) || super
+      end
+
+      def to_s
+        "<SpecializedObject for #{@provider.path_of(@obj).join("::")}>"
+      end
+
+      def inspect = to_s
+
+      def prepare_inheritance
+        @inheritance_prepared = true
+        @inherits = coerce_inheritance_data(@obj[:inherits])
+        @extends = @obj[:extends]&.map { resolve_qualified _1 }
+        @includes = @obj[:includes]&.map { resolve_qualified _1 }
+        @classes.each(&:prepare_inheritance)
+        @modules.each(&:prepare_inheritance)
+      end
+
+      private
+
+      def make_path
+        r = [name]
+        p = parent
+        while p
+          r << p.name
+          p = p.parent
+        end
+
+        r.reverse
+      end
+
+      def parent_of(parent)
+        return unless parent
+
+        p = parent
+        while p
+          return p unless p.parent
+
+          p = p.parent
+        end
+
+        p
+      end
+
+      def specialize_defs(defs, _parent)
+        defs.values.map do |i|
+          decoration = if i[:source] == "inheritance"
+                         "inherited"
+                       elsif i[:overriding]
+                         "override"
+                       else
+                         ""
+                       end
+
+          origin = i[:source]
+
+          @provider.find_source(i)
+                   .merge({ decoration:, origin: })
+        end
+      end
+
+      def coerce_inheritance_data(obj)
+        return obj if obj.nil?
+
+        resolve_inheritance(obj) || obj
+      end
+
+      def prepare(parent)
+        @inheritance_prepared = true
+        @parent = parent
+        @defs = specialize_defs(@obj[:defs], self)
+        @sdefs = specialize_defs(@obj[:sdefs], self)
+        @attributes = (@obj[:attributes] || {}).values.map do |v|
+          @provider.prepare_attr(v)
+        end
+
+        @root = parent_of(parent)
+        @path = make_path
+
+        @classes = @obj[:classes].map { SpecializedObject.specialize(_1, self, @provider) }
+        @modules = @obj[:modules].map { SpecializedObject.specialize(_1, self, @provider) }
+      end
+
+      def named_as(n) = ->(o) { o.name == n }
+    end
+  end
+end

data/lib/renderer/defs/specialized_projection.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+class Renderer
+  class Defs
+    class SpecializedProjection < Array
+      def initialize(provider)
+        super()
+        @provider = provider
+        replace((provider.modules + provider.classes)
+          .map { provider.specialize_object _1 }
+          .each(&:prepare_inheritance))
+      end
+
+      def find_path(path)
+        path = @provider.path_of(path) unless path.is_a? Array
+        p = path.dup
+        obj = find { _1.name == p.first }
+        p.shift
+        return unless obj
+
+        until p.empty?
+          obj = obj.resolve(p.first)
+          p.shift
+          return unless obj
+        end
+
+        obj
+      end
+    end
+  end
+end

data/lib/renderer/defs.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require_relative "defs/specialized_object"
+require_relative "defs/specialized_projection"
+
+class Renderer
+  class Defs
+    class << self
+      attr_reader :singleton
+    end
+
+    class << self
+      attr_writer :singleton
+    end
+
+    def initialize(base, metadata)
+      @data = JSON.parse(File.read("#{base}/data.json"), symbolize_names: true)
+      @meta = metadata
+      Defs.singleton = self
+    end
+
+    attr_reader :meta
+
+    def classes = @classes ||= make_paths(@data[:classes])
+    def modules = @modules ||= make_paths(@data[:modules])
+
+    def make_paths(obj)
+      return [] unless obj
+
+      obj.each { set_parent(_1, nil) }
+    end
+
+    def set_parent(obj, parent)
+      obj[:parent] = parent
+      obj[:classes].each { set_parent(_1, obj) }
+      obj[:modules].each { set_parent(_1, obj) }
+    end
+
+    def document_outline
+      (classes + modules).map { outline(_1) }
+    end
+
+    def outline(object, level = 0)
+      defs = object[:defs].values.map { map_method(_1) }.sort_by { _1[:name] }
+      sdefs = object[:sdefs].values.map { map_method(_1) }.sort_by { _1[:name] }
+      attributes = object[:attributes]&.values&.map { prepare_attr(_1) }&.sort_by { _1[:name] }
+
+      {
+        level:,
+        name: object[:name],
+        type: object[:type],
+        classes: object[:classes].map { outline(_1, level + 1) },
+        modules: object[:modules].map { outline(_1, level + 1) },
+        defs: defs + sdefs,
+        attributes:
+      }
+    end
+
+    def map_method(met)
+      decoration = if met[:source] == "inheritance"
+                     "inherited"
+                   elsif met[:overriding]
+                     "override"
+                   end
+
+      obj = find_source(met)
+      type = [].tap do |arr|
+        arr << "Class" if obj[:type] == "defs"
+        arr << "Method"
+      end.join(" ")
+
+      {
+        name: obj[:name],
+        visibility: obj[:visibility],
+        args: obj[:args],
+        type:,
+        short_type: obj[:type],
+        doc: obj[:doc],
+        decoration:
+      }
+    end
+
+    def find_source(met)
+      obj = met
+      obj = obj[:definition] while obj[:source] != "source"
+      obj[:definition]
+    end
+
+    def prepare_attr(met)
+      decoration = if met[:source] == "inheritance"
+                     "inherited"
+                   elsif met[:overriding]
+                     "override"
+                   end
+      origin = met[:source]
+      att = find_source(met)
+      visibility = if att[:reader_visibility] == "public" && att[:writer_visibility] == "public"
+                     "read/write"
+                   elsif att[:reader_visibility] == "public" && att[:writer_visibility] != "public"
+                     "read-only"
+                   else
+                     "write-only"
+                   end
+
+      {
+        name: att[:name],
+        type: "Attribute",
+        visibility:,
+        decoration:,
+        origin:,
+        doc: att[:doc]
+      }
+    end
+
+    def path_of(item)
+      p = []
+      parent = item
+      until parent.nil?
+        p << parent[:name]
+        parent = parent[:parent]
+      end
+      p.reverse
+    end
+
+    def definitions_of(item)
+      item[:defined_by]&.map do |d|
+        path_components = d[:filename].split("/")
+        {
+          name: path_components.last,
+          href: git_url(d)
+        }
+      end
+    end
+
+    def git_url(definition)
+      "#{@meta.git_url}/blob/#{@meta.git_tip}#{definition[:filename].gsub(@meta.git_root,
+                                                                          "")}#L#{definition[:start_at]}"
+    end
+
+    def clean_file_path(definition) = definition[:filename].gsub(meta.git_root, "")
+
+    def specialized_projection
+      @specialized_projection ||= SpecializedProjection.new(self)
+    end
+
+    def specialize_data
+      @specialize_data ||= (data[:modules] + data[:classes])
+                           .map { specialize_object _1 }
+                           .each(&:prepare_inheritance)
+    end
+
+    def specialize_object(obj, parent = nil)
+      SpecializedObject.specialize(obj, parent, self)
+    end
+
+    def by_name(n) = ->(o) { o[:name] == n }
+
+    def doc_for(path)
+      path = path_of(path) if path.is_a? Hash
+      path = path.dup
+      named = by_name(path.shift)
+      root = classes.find(&named) || modules.find(&named)
+
+      return unless root
+
+      find_recursive(path, root)
+    end
+
+    def find_recursive(path, root)
+      return root if path.empty?
+
+      named = by_name(path.shift)
+      next_item = root.classes.find(&named) || root.modules.find(&named)
+
+      return nil unless next_item
+
+      find_recursive(path, next_item)
+    end
+  end
+end