sleeping_king_studios-docs 0.1.0

data/lib/sleeping_king_studios/docs/commands/write_file.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+require 'cuprum/command'
+require 'cuprum/exception_handling'
+
+require 'sleeping_king_studios/docs/commands'
+
+module SleepingKingStudios::Docs::Commands
+  # Writes the given contents to a file.
+  class WriteFile < Cuprum::Command
+    include Cuprum::ExceptionHandling
+
+    # @!method call(contents:, file_path:)
+    #   Writes the given contents to the specified file.
+    #
+    #   Recursively generates the required directories, if needed.
+    #
+    #   @param contents [String] the contents to write.
+    #   @param file_path [String] the path of the file.
+    #
+    #   @return [Cuprum::Result] a passing result if the directories are
+    #     successfully created and the file is successfully written.
+    #   @return [Cuprum::Result<Cuprum::Error>] a failing result if the command
+    #     was unable to create the directories or write the file.
+
+    # @param force [Boolean] if true, overwrites an existing file.
+    def initialize(force: false)
+      super()
+
+      @force = force
+    end
+
+    # @return [Boolean] if true, overwrites an existing file.
+    def force?
+      @force
+    end
+
+    private
+
+    def check_if_file_exists(file_path:)
+      return if     force?
+      return unless File.exist?(file_path)
+
+      error =
+        SleepingKingStudios::Docs::Errors::FileAlreadyExists
+        .new(path: file_path)
+
+      failure(error)
+    end
+
+    def create_directory(file_path:)
+      dir_path = File.dirname(file_path)
+
+      FileUtils.mkdir_p(dir_path)
+    rescue Errno::EEXIST => exception
+      failure(invalid_directory_error(exception))
+    end
+
+    def create_file(contents:, file_path:)
+      File.write(file_path, contents)
+    rescue Errno::EISDIR => exception
+      failure(invalid_file_error(exception))
+    end
+
+    def invalid_directory_error(exception)
+      dir_path = exception.message.split(' - ').last
+
+      SleepingKingStudios::Docs::Errors::InvalidDirectory.new(path: dir_path)
+    end
+
+    def invalid_file_error(exception)
+      file_path = exception.message.split(' - ').last
+
+      SleepingKingStudios::Docs::Errors::InvalidFile.new(path: file_path)
+    end
+
+    def process(contents:, file_path:)
+      file_path = File.expand_path(file_path)
+
+      step { check_if_file_exists(file_path:) }
+
+      step { create_directory(file_path:) }
+
+      step { create_file(contents:, file_path:) }
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/commands.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs'
+
+module SleepingKingStudios::Docs
+  # Namespace for commands, which parse and generate documentation files.
+  module Commands
+    autoload :Generate,     'sleeping_king_studios/docs/commands/generate'
+    autoload :Generators,   'sleeping_king_studios/docs/commands/generators'
+    autoload :Installation, 'sleeping_king_studios/docs/commands/installation'
+    autoload :Parse,        'sleeping_king_studios/docs/commands/parse'
+    autoload :WriteFile,    'sleeping_king_studios/docs/commands/write_file'
+  end
+end

data/lib/sleeping_king_studios/docs/data/base.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/tools/toolbelt'
+
+require 'sleeping_king_studios/docs/data'
+
+module SleepingKingStudios::Docs::Data
+  # Base object representing a Ruby object documented in YARD.
+  #
+  # @abstract
+  class Base
+    # @param native [YARD::Tags::Tag] the YARD object representing the
+    #   documented object.
+    def initialize(native:)
+      @native   = native
+      @registry = SleepingKingStudios::Docs::Registry.instance
+    end
+
+    # Generates a JSON-compatible representation of the object.
+    #
+    # @return [Hash] the JSON representation.
+    def as_json
+      {}
+    end
+
+    private
+
+    attr_reader :native
+
+    attr_reader :registry
+
+    def empty?(value)
+      return true if value.nil?
+
+      return false unless value.respond_to?(:empty?)
+
+      value.empty?
+    end
+
+    def slugify(str)
+      tools.string_tools.underscore(str).tr('_', '-')
+    end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/data/class_object.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/data'
+
+module SleepingKingStudios::Docs::Data
+  # Object representing a Ruby class.
+  #
+  # Each class can define the following elements:
+  #
+  # - Defined In files.
+  # - inherited classes.
+  # - extend-ed modules.
+  # - include-ed modules.
+  # - Definitions (classes and modules).
+  # - Constants.
+  # - Class attributes.
+  # - Class methods.
+  # - A constructor method.
+  # - Instance attributes.
+  # - Instance methods.
+  # - Known subclasses.
+  #
+  # Additionally, a class can have a description and metadata tags.
+  #
+  # @see SleepingKingStudios::Docs::Data::Metadata
+  # @see SleepingKingStudios::Docs::Data::ModuleObject
+  class ClassObject < ModuleObject
+    JSON_PROPERTIES = %i[
+      direct_subclasses
+      inherited_classes
+    ].freeze
+    private_constant :JSON_PROPERTIES
+
+    # Generates a JSON-compatible representation of the module.
+    #
+    # Returns a Hash with the following keys:
+    #
+    # - 'name': The full, qualified name of the module.
+    # - 'slug': The name of the module in url-safe format.
+    # - 'files': A list of the files where the module is defined.
+    # - 'short_description': A short description of the module.
+    # - 'constructor': True if the class defines a constructor, otherwise false.
+    #
+    # Additionally, the returned Hash will conditionally include the following
+    # keys, if the module defines at least one of the corresponding code
+    # objects.
+    #
+    # - 'class_attributes': The class attributes, if any.
+    # - 'class_methods': The class methods, if any.
+    # - 'constants': The constants, if any.
+    # - 'defined_classes': The defined Classes, if any.
+    # - 'defined_modules': The defined Modules, if any.
+    # - 'description': The full description of the module, minus the first
+    #   clause.
+    # - 'extended_modules': A list of the modules that extend the module.
+    # - 'included_modules': A list of the modules that are included in the
+    #   module.
+    # - 'instance_attributes': The instance attributes, if any.
+    # - 'instance_methods': The instance methods, if any.
+    # - 'metadata': Additional metadata tags from the documentation.
+    #
+    # @return [Hash{String => Object}] the representation of the module.
+    def as_json
+      JSON_PROPERTIES.reduce(super.merge('constructor' => constructor?)) \
+      do |memo, property_name|
+        value = send(property_name)
+
+        next memo if empty?(value)
+
+        memo.update(property_name.to_s => value)
+      end
+    end
+
+    # @return [Boolean] true if the class defines a constructor, otherwise
+    #   false.
+    def constructor?
+      native.meths.any? { |meth| meth.name == :initialize }
+    end
+
+    # A list of the direct subclasses of the class.
+    #
+    # For each subclass, it returns a Hash with the following keys:
+    #
+    # - 'name': The name of the inherited class.
+    # - 'slug': A url-safe, hyphen-separated representation of the name.
+    # - 'path': The path to the data file for the class.
+    #
+    # @return [Array<Hash{String => String}>] the direct subclasses.
+    def direct_subclasses
+      registry
+        .select do |obj|
+          obj.type == :class && obj.inheritance_tree[1] == native
+        end
+        .map { |obj| format_inclusion(obj) }
+        .sort_by { |hsh| hsh['name'] }
+    end
+
+    # A list of the classes that are inherited by the class.
+    #
+    # For each inherited Class, it returns a Hash with the following keys:
+    #
+    # - 'name': The name of the inherited class.
+    # - 'slug': A url-safe, hyphen-separated representation of the name.
+    # - 'path': The path to the data file for the class.
+    #
+    # @return [Array<Hash{String => String}>] the inherited classes.
+    def inherited_classes
+      @inherited_classes ||=
+        native
+        .inheritance_tree[1..]
+        .map { |obj| format_inclusion(obj) }
+    end
+
+    # @return [String] the type of the namespace.
+    def type
+      'class'
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/data/constant_object.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/data'
+
+module SleepingKingStudios::Docs::Data
+  # Object representing a Ruby constant.
+  #
+  # Each constant has a name and a value. In addition, a constant may have a
+  # short description, a full description, and metadata.
+  class ConstantObject < SleepingKingStudios::Docs::Data::Base
+    JSON_PROPERTIES = %i[
+      data_path
+      description
+      metadata
+    ].freeze
+    private_constant :JSON_PROPERTIES
+
+    PARAGRAPH_BREAK = /\n{2,}/
+    private_constant :PARAGRAPH_BREAK
+
+    # Generates a JSON-compatible representation of the constant.
+    #
+    # Returns a Hash with the following keys:
+    #
+    # - 'name': The full, qualified name of the constant.
+    # - 'slug': The name of the constant in url-safe format.
+    # - 'value': A String representation of the value of the constant.
+    # - 'short_description': A short description of the constant.
+    #
+    # Additionally, the returned Hash will conditionally include the following
+    # keys, if the constant defines at least one of the corresponding code
+    # objects.
+    #
+    # - 'description': The full description of the constant, minus the first
+    #   clause.
+    # - 'metadata': Additional metadata tags from the documentation.
+    #
+    # @return [Hash{String => Object}] the representation of the constant.
+    def as_json
+      JSON_PROPERTIES.reduce(required_json) do |memo, property_name|
+        value = send(property_name)
+
+        next memo if empty?(value)
+
+        memo.update(property_name.to_s => value)
+      end
+    end
+
+    # The path to the data file.
+    #
+    # @return [String] the file path.
+    def data_path
+      @data_path ||= name.split('::').map { |str| slugify(str) }.join('/')
+    end
+
+    # The full description of the constant, minus the first clause.
+    #
+    # The remainder of the constant description, if any, after subtracting the
+    # short description (separated by the first paragraph break).
+    #
+    # @return [String] the remaining description.
+    #
+    # @see #short_description.
+    def description
+      return @description if @description
+
+      @short_description, @description = split_docstring
+
+      @description
+    end
+
+    # Additional metadata tags from the documentation.
+    #
+    # @see SleepingKingStudios::Docs::Data::Metadata.
+    def metadata
+      @metadata ||= format_metadata
+    end
+
+    # The full, qualified name of the constant.
+    #
+    # @return [String] the qualified name.
+    def name
+      @name ||= native.path
+    end
+
+    # The path to the defining class or module's data file.
+    #
+    # @return [String] the file path.
+    def parent_path
+      return @parent_path if @parent_path
+
+      return @parent_path = '' if native.parent.root?
+
+      parent_class  =
+        if native.parent.is_a?(YARD::CodeObjects::ClassObject)
+          SleepingKingStudios::Docs::Data::ClassObject
+        else
+          SleepingKingStudios::Docs::Data::ModuleObject
+        end
+      parent_object = parent_class.new(native: native.parent)
+
+      @parent_path = parent_object.data_path
+    end
+
+    # A short description of the constant.
+    #
+    # The first part of the constant description, separated by the first
+    # paragraph break. Typically should fit on a single line of text.
+    #
+    # @return [String] the short description.
+    #
+    # @see #description.
+    def short_description
+      return @short_description if @short_description
+
+      @short_description, @description = split_docstring
+
+      @short_description
+    end
+
+    # The name of the constant in url-safe format.
+    #
+    # @return [String] the constant name.
+    def slug
+      @slug ||= slugify(name.split('::').last)
+    end
+
+    # A String representation of the value of the constant.
+    #
+    # @return [String] the constant value.
+    def value
+      native.value
+    end
+
+    private
+
+    def required_json
+      {
+        'name'              => name,
+        'parent_path'       => parent_path,
+        'slug'              => slug,
+        'short_description' => short_description,
+        'value'             => value
+      }
+    end
+
+    def format_metadata
+      SleepingKingStudios::Docs::Data::Metadata
+        .new(native:)
+        .as_json
+    end
+
+    def split_docstring
+      match = native.docstring.match(PARAGRAPH_BREAK)
+
+      return native.docstring.to_s unless match
+
+      [match.pre_match.to_s, match.post_match.to_s]
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/data/metadata.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require 'set'
+
+require 'sleeping_king_studios/docs/data'
+
+module SleepingKingStudios::Docs::Data
+  # Object representing the metadata tags for a Ruby module.
+  #
+  # Each module can have the following metadata tags:
+  #
+  # - @example
+  # - @note
+  # - @see
+  # - @todo
+  #
+  # Other tags are not currently supported.
+  #
+  # @see SleepingKingStudios::Docs::Data::ModuleObject.
+  # @see SleepingKingStudios::Docs::Data::SeeTags.
+  class Metadata < SleepingKingStudios::Docs::Data::Base
+    EMPTYABLE_PROPERTIES = Set.new(
+      %i[
+        abstract
+        deprecated
+      ]
+    ).freeze
+    private_constant :EMPTYABLE_PROPERTIES
+
+    METADATA_PROPERTIES = %i[
+      abstract
+      api
+      authors
+      deprecated
+      examples
+      notes
+      see
+      since
+      todos
+      versions
+    ].freeze
+    private_constant :METADATA_PROPERTIES
+
+    # Returns the @abstract tag, if any, defined for the module.
+    #
+    # @return [String] the contents of the @abstract tag, or an empty string if
+    #   the tag does not have contents.
+    # @return [nil] if there is no @abstract tag defined.
+    def abstract
+      @abstract ||=
+        native
+        .tags
+        .find { |tag| tag.tag_name == 'abstract' }
+        &.text
+    end
+
+    # Returns the @api tag, if any, defined for the module.
+    #
+    # @return [String] the contents of the @api tag.
+    # @return [nil] if there is no @api tag defined.
+    def api
+      @api ||=
+        native
+        .tags
+        .find { |tag| tag.tag_name == 'api' }
+        &.text
+    end
+
+    # Generates a JSON-compatible representation of the metadata.
+    #
+    # Returns a Hash with zero or more of the following keys:
+    #
+    # - 'examples': An Array of Hashes with keys 'name' and 'text' and String
+    #   values.
+    # - 'notes': An Array of Strings.
+    # - 'see': An Array of Hashes with String values.
+    # - 'todo': An Array of Strings.
+    #
+    # @return [Hash{String => Object}] the representation of the metadata.
+    def as_json
+      METADATA_PROPERTIES
+        .reduce({}) do |memo, property_name|
+          value = send(property_name)
+
+          next memo if emptyable?(property_name) ? value.nil? : empty?(value)
+
+          memo.update(property_name.to_s => value)
+        end
+    end
+
+    # Collects the @author tags defined for the module.
+    #
+    # @return [Array<String>] the collected authors.
+    def authors
+      @authors ||=
+        select_tags('author') { |tag| !tag.text.empty? }
+        .map(&:text)
+    end
+
+    # Returns the @deprecated tag, if any, defined for the module.
+    #
+    # @return [String] the contents of the @deprecated tag, or an empty string
+    #   if the tag does not have contents.
+    # @return [nil] if there is no @deprecated tag defined.
+    def deprecated
+      @deprecated ||=
+        native
+        .tags
+        .find { |tag| tag.tag_name == 'deprecated' }
+        &.text
+    end
+
+    # Collects the @example tags defined for the module.
+    #
+    # Each @example tag is represented as a Hash with the following keys:
+    #
+    # - 'name': The displayed name of the example. May be an empty String.
+    # - 'text': The text for the example.
+    #
+    # @return [Array<Hash{String => String}>] the collected examples.
+    def examples
+      @examples ||=
+        select_tags('example')
+        .map { |tag| { 'name' => tag.name, 'text' => tag.text } }
+    end
+
+    # Collects the @note tags defined for the module.
+    #
+    # @return [Array<String>] the collected notes.
+    def notes
+      @notes ||= select_tags('note').map(&:text)
+    end
+
+    # Collects the @see tags defined the for the module.
+    #
+    # Each @see tag is represented as a Hash with String keys and values, and
+    # has at a minimum the 'text' key. See the SeeTag#as_json method for
+    # details.
+    #
+    # @return [Array<Hash{String => String}>]
+    def see
+      @see ||= select_tags('see').map { |tag| format_see_tag(tag) }
+    end
+
+    # Collects the @since tags defined for the module.
+    #
+    # @return [Array<String>] the collected @since tags.
+    def since
+      @since ||=
+        select_tags('since') { |tag| !tag.text.empty? }
+        .map(&:text)
+    end
+
+    # Collects the @todo tags defined for the module.
+    #
+    # @return [Array<String>] the collected todos.
+    def todos
+      @todos ||= select_tags('todo').map(&:text)
+    end
+
+    # Collects the @version tags defined for the module.
+    #
+    # @return [Array<String>] the collected @version tags.
+    def versions
+      @versions ||=
+        select_tags('version') { |tag| !tag.text.empty? }
+        .map(&:text)
+    end
+
+    private
+
+    def definition_tag?(tag)
+      tag.type == :class || tag.type == :module # rubocop:disable Style/MultipleComparison
+    end
+
+    def emptyable?(property_name)
+      EMPTYABLE_PROPERTIES.include?(property_name)
+    end
+
+    def format_see_tag(tag)
+      SleepingKingStudios::Docs::Data::SeeTags
+        .build(
+          native: tag,
+          parent: definition_tag?(native) ? native : native.parent
+        )
+        .as_json
+    end
+
+    def select_tags(tag_name)
+      native.tags.select do |tag|
+        (tag.tag_name == tag_name) &&
+          (!block_given? || yield(tag))
+      end
+    end
+  end
+end