docrb 0.2.0

data/lib/docrb/doc_compiler/doc_blocks.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Docrb
+  class DocCompiler
+    # DocBlocks provides utilities for annotating and formatting documentation
+    # blocks.
+    class DocBlocks
+      # Internal: Transforms a provided reference on a given parent by a
+      # ttempting to resolve it into a specific object.
+      #
+      # ref    - Reference to be resolved
+      # parent - The reference's parent
+      #
+      # Returns the reference itself by augmenting it with :ref_type and
+      # :ref_path information.
+      def self.process_reference(ref, parent)
+        return process_method_reference(ref, parent) if ref[:ref_type] == :method
+        return ref if ref[:ref_type] != :ambiguous
+
+        resolved = parent.resolve_ref(ref)
+        if resolved.nil?
+          ref[:ref_type] = :not_found
+          return ref
+        end
+        ref[:ref_type] = resolved.type
+        ref[:ref_path] = resolved.path
+        ref
+      end
+
+      def self.process_method_reference(ref, parent)
+        if (resolved = parent.resolve_ref(ref))
+          ref[:ref_path] = resolved.path
+        end
+        ref
+      end
+
+      # Internal: Processes a identifier on a provided parent. Returns an
+      # augmented reference with extra location information whenever it can
+      # be resolved.
+      #
+      # id     - Identifier to be processed
+      # parent - Parent on which the identifier appeared.
+      def self.process_identifier(id, parent)
+        resolved = parent.resolve(id[:contents].to_sym)
+        if resolved.nil?
+          puts "Unresolved: #{id[:contents]} on #{parent.path}"
+          return {
+            type: :span,
+            contents: Markdown.inline("`#{id[:contents]}`")
+          }
+        end
+        {
+          type: :ref,
+          ref_type: resolved.type,
+          ref_path: resolved.path,
+          contents: id[:contents]
+        }
+      end
+
+      # Internal: Formats a given TextBlock object by expanding its contents
+      # into markdown annotations and attempting to resolve references and
+      # identifiers.
+      #
+      # Returns the updated block list.
+      def self.format_text_block(block, parent)
+        unless block[:contents].is_a? Array
+          block[:contents] = Markdown.inline(block[:contents])
+          return block
+        end
+        block[:contents].map! do |c|
+          case c[:type]
+          when :span
+            c[:contents] = Markdown.inline(c[:contents])
+          when :ref
+            c = process_reference(c, parent)
+          when :camelcase_identifier
+            c = process_identifier(c, parent)
+          end
+          c
+        end
+        block
+      end
+
+      # Public: Updates a given documentation block by augmenting markdown
+      # elements, references, fields and identifiers.
+      #
+      # doc    - Documentation block to be processed
+      # parent - The parent container to which the block belongs to.
+      #
+      # Returns the updated block.
+      def self.prepare(doc, parent: nil)
+        return unless doc
+
+        doc[:contents].map! do |block|
+          case block[:type]
+          when :text_block
+            format_text_block(block, parent)
+          when :code_example
+            block[:contents] = Markdown.render_source(block[:contents])
+          when :field_block
+            block[:contents] = block[:contents].transform_values { |v| format_text_block(v, parent) }
+          else
+            puts "Skipped block with type #{block[:type]}"
+          end
+          block
+        end
+        doc
+      end
+    end
+  end
+end

data/lib/docrb/doc_compiler/doc_class.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Docrb
+  class DocCompiler
+    # DocClass represents a documented class
+    class DocClass < BaseContainer
+      attr_accessor :inherits, :attributes
+
+      # Initializes a new instance with the provided parent, file, and object.
+      #
+      # parent   - The parent container holding this class definition.
+      # filename - The filename defining this class.
+      # obj      - The parsed class data.
+      def initialize(parent, filename, obj)
+        @inherits = nil
+        @attributes = ObjectContainer.new(self, DocAttribute, always_append: true)
+        super
+      end
+
+      def appended(filename, obj)
+        obj.fetch(:attr_accessor, []).each do |att|
+          @attributes.push(filename, att).accessor!
+        end
+
+        obj.fetch(:attr_reader, []).each do |att|
+          @attributes.push(filename, att).reader!
+        end
+
+        obj.fetch(:attr_writer, []).each do |att|
+          @attributes.push(filename, att).writer!
+        end
+      end
+
+      # Returns a Hash representation of this class definition
+      def to_h
+        super.to_h.merge({
+                           inherits:,
+                           attributes: merged_attributes.transform_values { |v| unpack(v) }
+                         })
+      end
+    end
+  end
+end

data/lib/docrb/doc_compiler/doc_method.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Docrb
+  class DocCompiler
+    # DocMethod represents a documented method
+    class DocMethod < Resolvable
+      attr_reader :parent, :type, :name, :args, :doc, :visibility,
+                  :overriden_by, :defined_by
+
+      # Initializes a new DocMethod instance with a given parent, path, and
+      # object.
+      #
+      # parent   - The object holding the represented method
+      # filename - The filename on which the method is defined on
+      # obj      - The method definition itself
+      def initialize(parent, filename, obj)
+        super()
+        @parent = parent
+        @type = obj[:type]
+        @name = obj[:name]
+        @args = obj[:args]
+        @doc = obj[:doc]
+        @visibility = obj[:visibility]
+        @overriden_by = nil
+        @defined_by = FileRef.new(nil, filename, obj)
+      end
+
+      # Public: Marks this method as being overriden by a provided object in
+      # a given filename. This method initializes a new DocMethod instance using
+      # this instance's parent, the provided filename and object, and invokes
+      # #override! on it.
+      #
+      # filename - The filename defining the override for this method
+      # obj      - The object representing the override for this method
+      def override(filename, obj)
+        override! DocMethod.new(@parent, filename, obj)
+      end
+
+      # Public: Marks this method as being overriden by the provided method
+      #
+      # method - DocMethod object overriding this method's implementation
+      def override!(method)
+        @overriden_by = method
+      end
+
+      def inspect
+        type = @type == :def ? "method" : "singleton method"
+        overriden = overriden_by.nil? ? "" : " overriden"
+        "#<DocMethod:#{format("0x%08x", object_id * 2)} #{visibility} #{type} #{name}#{overriden}>"
+      end
+
+      # Public: Returns a Hash representation of this method
+      def to_h
+        {
+          type:,
+          name:,
+          args:,
+          doc: DocBlocks.prepare(doc, parent: self),
+          visibility:,
+          overriden_by:,
+          defined_by: defined_by&.to_h
+        }
+      end
+    end
+  end
+end

data/lib/docrb/doc_compiler/doc_module.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Docrb
+  class DocCompiler
+    # DocModule represents a documented Module object
+    class DocModule < BaseContainer
+    end
+  end
+end

data/lib/docrb/doc_compiler/file_ref.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Docrb
+  class DocCompiler
+    # FileRef represents a file reference. This class is used to represent
+    # definition metadata of objects in files. Instances of this class
+    # indicates filenames and boundaries for a represented object.
+    class FileRef
+      attr_reader :filename, :start_at, :end_at
+
+      # Initializes a new FileRef instance.
+      #
+      # _parent  - Unused.
+      # filename - Path to the file being referenced
+      # obj      - The object being referenced in the provided filename
+      #
+      def initialize(_parent, filename, obj)
+        @filename = filename
+        @start_at, @end_at = obj.values_at(:start_at, :end_at)
+      end
+
+      # Public: Returns the source code portion of the represented reference
+      def ruby_source
+        f = File.read(filename).split("\n")[start_at - 1..end_at - 1]
+        f.join("\n")
+      end
+
+      # Public: Returns the reference's Hash representation
+      def to_h
+        source = ruby_source
+        {
+          filename:,
+          start_at:,
+          end_at:,
+          source:,
+          markdown_source: Markdown.render_source(source)
+        }
+      end
+    end
+  end
+end

data/lib/docrb/doc_compiler/object_container.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Docrb
+  class DocCompiler
+    # ObjectContainer implements utilities for representing a container of
+    # objects with a common type.
+    class ObjectContainer
+      extend Forwardable
+
+      attr_reader :objects
+
+      # Initializes a new container with a given parent, containing objects with
+      # a provided class and options.
+      #
+      # parent - The container's parent
+      # cls    - The class of represented items
+      # **opts - Options list. Currently, only `always_append` is supported,
+      #          which indicates that all objects provided to the instance must
+      #          be appended regardless of their type.
+      def initialize(parent, cls, **opts)
+        @cls = cls
+        @objects = []
+        @opts = opts
+        @parent = parent
+      end
+
+      def_delegators :@objects, :length, :each, :map, :find, :filter, :first, :[], :to_json
+
+      # Pushes a new object into the container. May raise ArgumentError in case
+      # the object being pushed is not compatible with the container's base
+      # object.
+      #
+      # filename - Name of the file which defines the object being pushed
+      # obj      - The object being pushed
+      #
+      # Returns the new instance representing the pushed object.
+      def push(filename, obj)
+        if @cls.method_defined?(:name) &&
+           (instance = @objects.find { |o| o.name == obj[:name] }) &&
+           !@opts.fetch(:always_append, false)
+
+          return instance.merge(filename, obj) if instance.respond_to? :merge
+          return instance.override(filename, obj) if instance.respond_to? :override
+          return instance.append(filename, obj) if instance.respond_to? :append
+
+          raise ArgumentError, "cannot handle existing object #{obj[:name]} for container of type #{@cls.name}"
+        end
+
+        inst = @cls.new(@parent, filename, obj)
+        @objects << inst
+        inst
+      end
+
+      def inspect
+        opts = []
+        opts << "always_append" if @opts[:always_append]
+        count = if @objects.count.zero?
+                  "empty"
+                else
+                  "#{@objects.length} object#{@objects.length == 1 ? "" : "s"}"
+                end
+        obj_id = format("0x%08x", object_id * 2)
+        opts_repr = opts.empty? ? "" : " #{opts.join(", ")}"
+        "#<ObjectContainer:#{obj_id} containing #{@cls.name}, #{count}#{opts_repr}>"
+      end
+    end
+  end
+end

data/lib/docrb/doc_compiler.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Docrb
+  # DocCompiler implements utilities to post-process documentation data
+  # generated by RubyParser.
+  class DocCompiler < Resolvable
+    autoload :FileRef, "docrb/doc_compiler/file_ref"
+    autoload :BaseContainer, "docrb/doc_compiler/base_container"
+    autoload :DocClass, "docrb/doc_compiler/doc_class"
+    autoload :DocModule, "docrb/doc_compiler/doc_module"
+    autoload :DocMethod, "docrb/doc_compiler/doc_method"
+    autoload :DocAttribute, "docrb/doc_compiler/doc_attribute"
+    autoload :ObjectContainer, "docrb/doc_compiler/object_container"
+    autoload :DocBlocks, "docrb/doc_compiler/doc_blocks"
+
+    attr_reader :classes, :modules, :methods, :parent
+
+    def initialize
+      super
+      @classes = ObjectContainer.new(self, DocClass)
+      @modules = ObjectContainer.new(self, DocModule)
+      @methods = ObjectContainer.new(self, DocMethod)
+      @parent = nil
+    end
+
+    # Appends a given object to the compiler collection. Raises ArgumentError in
+    # case the object cannot be appended to the current container.
+    #
+    # obj - Object to be appended
+    def append(obj)
+      filename = obj[:filename]
+      target = case obj[:type]
+               when :module
+                 @modules
+               when :class
+                 @classes
+               when :def, :defs
+                 @methods
+               end
+
+      raise ArgumentError, "cannot append obj of type #{obj[:type]}" if target.nil?
+
+      target.push(filename, obj)
+    end
+
+    # Transforms the content's of the parser into a Hash representation
+    def to_h
+      {
+        modules: @modules.map(&:to_h),
+        classes: @classes.map(&:to_h),
+        methods: @methods.map(&:to_h)
+      }
+    end
+  end
+end

data/lib/docrb/markdown.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Docrb
+  # Renderer provides a Redcarpet renderer with Rouge extensions
+  class Renderer < Redcarpet::Render::HTML
+    def initialize(extensions = {})
+      super extensions.merge(link_attributes: { target: "_blank" })
+    end
+    include Rouge::Plugins::Redcarpet
+  end
+
+  # InlineRenderer provides a renderer for inline contents. This renderer
+  # does not emit paragraph tags.
+  class InlineRenderer < Renderer
+    def paragraph(text)
+      text
+    end
+  end
+
+  # Markdown provides utilities for generating HTML from markdown contents
+  class Markdown
+    # Internal: Creates a new renderer based on a provided type by setting
+    # sensible defaults.
+    #
+    # type - Type of the renderer to be initialised. Use Docrb::Renderer or
+    #        InlineRenderer
+    def self.make_render(type)
+      Redcarpet::Markdown.new(
+        type,
+        fenced_code_blocks: true,
+        autolink: true
+      )
+    end
+
+    # Renders a given input using the default renderer.
+    #
+    # input - Markdown content to be rendered
+    #
+    # Returns an HTML string containing the rendered Markdown content
+    def self.render(input)
+      make_render(Renderer).render(input)
+    end
+
+    # Renders a given input using the inline renderer.
+    #
+    # input - Markdown content to be rendered
+    #
+    # Returns an HTML string containing the rendered Markdown content
+    def self.inline(input)
+      make_render(InlineRenderer).render(input)
+    end
+
+    # Renders a given Ruby source code into HTML
+    #
+    # source - Source code to be rendered
+    #
+    # Returns an HTML string containing the rendered source code
+    def self.render_source(source)
+      render("```ruby\n#{source}\n```")
+    end
+  end
+end

data/lib/docrb/module_extensions.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+unless Class.respond_to? :try?
+  class Object
+    def try?(method, *args, **kwargs, &)
+      send(method, *args, **kwargs, &) if respond_to?(method)
+    end
+
+    def self.try?(method, *args, **kwargs, &)
+      send(method, *args, **kwargs, &) if respond_to?(method)
+    end
+  end
+end

data/lib/docrb/resolvable.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module Docrb
+  # Resolvable implements utilities for resolving names and class paths on a
+  # container context (module/class)
+  class Resolvable
+    # Returns a matcher for a provided name
+    #
+    # name - Name to match against
+    def by_name(name)
+      ->(obj) { obj.name == name }
+    end
+
+    # Returns a matcher for a provided name and type
+    #
+    # name - Name to match against
+    # type - Object type to match against (:def/:sdef/:class/:module...)
+    def by_name_and_type(name, type)
+      ->(obj) { obj.name == name && obj.type == type }
+    end
+
+    # Attempts to resolve a method with a provided name in the container's
+    # context. This method attempts to match for instance methods, class
+    # methods, and finally by recursively calling this method on the inherited
+    # members, if any.
+    #
+    # name - Name of the method to be resolved.
+    #
+    # Returns a method structure, or nil, in case none is found.
+    def resolve_method(name)
+      if (local = try?(:defs)&.find(&by_name(name)))
+        return local
+      end
+
+      if (local = try?(:sdefs)&.find(&by_name(name)))
+        return local
+      end
+
+      # Inherited?
+      if (inherited = try?(:inherits)&.try?(:resolve_method, name, type))
+        return inherited
+      end
+
+      nil
+    end
+
+    # Resolves a container using a provided reference.
+    #
+    # ref - Either a reference hash (containing :class_path, :target, :name), or
+    #       a symbol representing the name of the container being resolved.
+    #
+    # Returns a matched container or nil, in case none is found.
+    def resolve_container(ref)
+      if ref.is_a? Hash
+        path = ref
+               .slice(:class_path, :target, :name)
+               .values
+               .flatten
+               .compact
+        return resolve_container(path)
+      end
+
+      ref = [ref] if ref.is_a? Symbol
+
+      if ref.length == 1
+        name = ref.first
+        # module?
+        if (mod = try?(:modules)&.find(&by_name(name)))
+          return mod
+        end
+
+        # class?
+        if (cls = try?(:classes)&.find(&by_name(name)))
+          return cls
+        end
+
+        # parent?
+        return @parent&.resolve_container(ref)
+      end
+
+      obj = self
+      while ref.length.positive?
+        obj = resolve_container(ref.shift)
+        return nil if obj.nil?
+      end
+
+      obj
+    end
+
+    # Resolves a provided name in the current containter's context. This method
+    # will attempt to return an object matching the provided name by looking for
+    # it in the following subcontainers: modules, classes, methods, attributes,
+    # and recursively performing the resolution on the container's parent, if
+    # any.
+    #
+    # name - Name of the object being resolved
+    #
+    # Returns the first object found by the provided name, or nil, in case none
+    # is found.
+    def resolve(name)
+      return nil if name.nil?
+
+      name = name.to_sym
+
+      # module?
+      if (mod = try?(:modules)&.find(&by_name(name)))
+        return mod
+      end
+
+      # class?
+      if (cls = try?(:classes)&.find(&by_name(name)))
+        return cls
+      end
+
+      # method?
+      if (met = resolve_method(name))
+        return met
+      end
+
+      # attribute?
+      if (att = try?(:attributes)&.find(&by_name(name)))
+        return att
+      end
+
+      if (obj = @parent&.resolve(name))
+        return obj
+      end
+
+      nil
+    end
+
+    # Resolves a provided ref by creating its path string representation and
+    # calling #resolve_qualified
+    #
+    # ref - Hash representing the reference being resolved.
+    #
+    # Returns the object under the provided reference, or nil.
+    def resolve_ref(ref)
+      path = ref
+             .slice(:class_path, :target, :name)
+             .values
+             .flatten
+             .compact
+      return resolve_qualified(path.join("::")) if path.length > 1
+
+      resolve(path[0])
+    end
+
+    # Resolves a qualified path under the current container's context.
+    #
+    # path - Path of the object being resolved. Must be a string containing the
+    #        object name being searched, or a classpath for it (e.g.
+    #        `Foo::Bar::Baz`)
+    def resolve_qualified(path)
+      components = path.split("::").map(&:to_sym)
+      obj = root
+      until components.empty?
+        obj = obj.resolve(components.shift)
+        break if obj.nil?
+      end
+      obj
+    end
+
+    # Returns the root object for the current container
+    def root
+      obj = self
+      obj = obj.parent while obj.parent
+      obj
+    end
+
+    # Returns the container's full qualified path
+    def path
+      return [] if parent.nil?
+
+      parent.path + [name]
+    end
+  end
+end