sleeping_king_studios-docs 0.1.0

data/lib/sleeping_king_studios/docs/data/types/key_value_type.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/data/types'
+
+module SleepingKingStudios::Docs::Data::Types
+  # Represents a YARD type with lists of key types and value types.
+  class KeyValueType < SleepingKingStudios::Docs::Data::Types::Type
+    # @param keys [Array<SleepingKingStudios::Docs::Data::Types::Type>] the key
+    #   types.
+    # @param name [String] the name of the type.
+    # @param values [Array<SleepingKingStudios::Docs::Data::Types::Type>] the
+    #   value types.
+    def initialize(keys:, name:, values:)
+      super(name:)
+
+      @keys   = keys
+      @values = values
+    end
+
+    # Generates a JSON-compatible representation of the parameterized type.
+    #
+    # Returns a Hash with the following keys:
+    #
+    # - 'name': The name of the type.
+    # - 'keys': A JSON representation of the parameterized keys.
+    # - 'values': A JSON representation of the parameterized values.
+    # - (Optional) 'path': The relative path to the referenced class or module,
+    #   if the class or module is documented by YARD.
+    #
+    # @return [Hash] the JSON representation.
+    def as_json
+      super.merge(
+        'keys'   => keys.map(&:as_json),
+        'values' => values.map(&:as_json)
+      )
+    end
+
+    # @return [Array<SleepingKingStudios::Docs::Data::Types::Type>] the key
+    #   types.
+    attr_reader :keys
+
+    # @return [Array<SleepingKingStudios::Docs::Data::Types::Type>] the value
+    #   types.
+    attr_reader :values
+
+    private
+
+    def inspect_attributes
+      "#{super} " \
+        "@keys=[#{keys.map(&:inspect).join(', ')}] " \
+        "@values=[#{values.map(&:inspect).join(', ')}]"
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/data/types/parameterized_type.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/data/types'
+
+module SleepingKingStudios::Docs::Data::Types
+  # Represents a YARD type with a list of child types.
+  class ParameterizedType < SleepingKingStudios::Docs::Data::Types::Type
+    # @param items [Array<SleepingKingStudios::Docs::Data::Types::Type>] the
+    #   child types.
+    # @param name [String] the name of the type.
+    # @param ordered [Boolean] if true, indicates the type represents an order-
+    #   dependent list.
+    def initialize(items:, name:, ordered: false)
+      super(name:)
+
+      @items   = items
+      @ordered = ordered
+    end
+
+    # @return [Array<SleepingKingStudios::Docs::Data::Types::Type>] the child
+    #   types.
+    attr_reader :items
+
+    # Generates a JSON-compatible representation of the parameterized type.
+    #
+    # Returns a Hash with the following keys:
+    #
+    # - 'name': The name of the type.
+    # - 'items': A JSON representation of the parameterized items.
+    # - (Optional) 'ordered': If true, indicates the type represents an order-
+    #   dependent list.
+    # - (Optional) 'path': The relative path to the referenced class or module,
+    #   if the class or module is documented by YARD.
+    #
+    # @return [Hash] the JSON representation.
+    def as_json
+      json = super.merge('items' => items.map(&:as_json))
+
+      return json unless ordered?
+
+      json.merge('ordered' => true)
+    end
+
+    # @return [Boolean] if true, indicates the type represents an order-
+    #   dependent list.
+    def ordered?
+      @ordered
+    end
+
+    private
+
+    def inspect_attributes
+      "#{super} @ordered=#{ordered?} " \
+        "@items=[#{items.map(&:inspect).join(', ')}]"
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/data/types/parser.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/tools/toolbelt'
+require 'treetop'
+
+require 'sleeping_king_studios/docs/data/types'
+require 'sleeping_king_studios/docs/data/types/grammar'
+
+module SleepingKingStudios::Docs::Data::Types
+  # Parses a YARD type list into a nested data object.
+  #
+  # @note Certain combinations of comparable methods and parameterized types are
+  #   known not to parse: list types with `#<=` or `#>` methods, and hash types
+  #   with `#<`, `#==`, or `#>` keys. As a workaround, add trailing whitespace
+  #   between the method name and any subsequent control characters.
+  #
+  # @see https://www.rubydoc.info/gems/yard/file/docs/Tags.md#types-specifier-list
+  class Parser
+    # Exception raised when encountering an invalid type string.
+    class ParseError < StandardError; end
+
+    def initialize
+      @parser = TypesSpecifierListParser.new
+
+      generate_node_map
+    end
+
+    # Parses a YARD type list.
+    #
+    # @return [Array<[SleepingKingStudios::Docs::Data::Types::Type]>] the parsed
+    #   types.
+    #
+    # @raise [ParserError] if unable to parse the type.
+    def parse(type)
+      return [] if type.nil? || type.empty?
+
+      result = parser.parse(type)
+
+      raise ParseError, "unable to parse type `#{type}'" if result.nil?
+
+      Array(handle_node(result))
+    end
+
+    private
+
+    attr_reader :node_map
+
+    attr_reader :parser
+
+    def build_array(name:, values:, ordered: false)
+      SleepingKingStudios::Docs::Data::Types::ParameterizedType.new(
+        items:   values,
+        name:,
+        ordered:
+      )
+    end
+
+    def build_basic(name:)
+      SleepingKingStudios::Docs::Data::Types::Type.new(name:)
+    end
+
+    def build_hash(name:, keys:, values:)
+      SleepingKingStudios::Docs::Data::Types::KeyValueType.new(
+        keys:,
+        name:,
+        values:
+      )
+    end
+
+    def generate_node_map # rubocop:disable Metrics/MethodLength
+      @node_map =
+        TypesSpecifierList
+        .constants
+        .select { |const_name| const_name.to_s.end_with?('0') }
+        .sort
+        .to_h \
+      do |const_name|
+        ext   = TypesSpecifierList.const_get(const_name)
+        value = tools.string_tools.underscore(const_name.to_s[0...-1]).intern
+
+        [ext, value]
+      end
+    end
+
+    def handle_key_value_type(node)
+      name   = node.elements.first.text_value
+      keys   = Array(handle_node(node.elements[2]))
+      values = Array(handle_node(node.elements[4]))
+
+      build_hash(name:, keys:, values:)
+    end
+
+    def handle_identifier_with_whitespace(node)
+      name = node.text_value.strip
+
+      build_basic(name:)
+    end
+
+    def handle_node(node)
+      node_type = identify_node_type(node)
+      handler   = :"handle_#{node_type}"
+
+      send(handler, node)
+    end
+
+    def handle_ordered_type(node)
+      name   = node.elements.first.text_value
+      values = Array(handle_node(node.elements[2]))
+
+      build_array(name:, ordered: true, values:)
+    end
+
+    def handle_parameterized_type(node)
+      name   = node.elements.first.text_value
+      values = Array(handle_node(node.elements[2]))
+
+      build_array(name:, values:)
+    end
+
+    def handle_type_list(node)
+      if identify_node_type(node.elements.last) == :type_list
+        return [
+          handle_node(node.elements.first),
+          *handle_type_list(node.elements.last)
+        ]
+      end
+
+      [handle_node(node.elements.first), *handle_node(node.elements.last)]
+    end
+
+    def identify_node_type(node)
+      return :text if node.extension_modules.empty?
+
+      node_map
+        .find { |type, _| node.extension_modules.include?(type) }
+        &.last || :unknown_type
+    end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/data/types/type.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/tools/toolbelt'
+
+require 'sleeping_king_studios/docs/data/types'
+
+module SleepingKingStudios::Docs::Data::Types
+  # Base class for a YARD type.
+  class Type
+    LOWERCASE_LETTER = /\A[[:lower:]]/
+    private_constant :LOWERCASE_LETTER
+
+    # @param name [String] the name of the type.
+    def initialize(name:)
+      @name     = name
+      @registry = SleepingKingStudios::Docs::Registry.instance
+    end
+
+    # @return [String] the name of the type.
+    attr_reader :name
+
+    # @return [Boolean] true if the other object is an instance of the same Type
+    #   class and has the same JSON representation; otherwise false.
+    def ==(other)
+      return false unless other.instance_of?(self.class)
+
+      other.as_json == as_json
+    end
+
+    # Generates a JSON-compatible representation of the type.
+    #
+    # Returns a Hash with the following keys:
+    #
+    # - 'name': The name of the type.
+    # - (Optional) 'path': The relative path to the referenced class or module,
+    #   if the class or module is documented by YARD.
+    #
+    # @return [Hash] the JSON representation.
+    def as_json
+      json = { 'name' => name }
+
+      return json unless exists?
+
+      json.merge('path' => path)
+    end
+
+    # @return [Boolean] true if the type is a class or module documented by
+    #   YARD; otherwise false.
+    def exists?
+      return @exists unless @exists.nil?
+
+      return @exists = false if literal? || method?
+
+      @exists =
+        SleepingKingStudios::Docs::RegistryQuery
+        .new(registry:)
+        .definition_exists?(name)
+    end
+
+    # @return [String] a user-friendly representation of the Type.
+    def inspect
+      "#<#{self.class.name.split('::').last} #{inspect_attributes}>"
+    end
+
+    # @return [Boolean] true if the type is a literal value; otherwise false.
+    def literal?
+      name.match?(LOWERCASE_LETTER)
+    end
+
+    # @return [Boolean] true if the name is a method name, otherwise false.
+    def method?
+      name.start_with?('.') || name.start_with?('#')
+    end
+
+    # @return [String, nil] the qualified relative path of the definition, or
+    #   nil if the type is not a class or module or it is not documented by
+    #   YARD.
+    def path
+      return nil unless exists?
+
+      @path ||= name.split('::').map { |str| slugify(str) }.join('/')
+    end
+
+    private
+
+    attr_reader :registry
+
+    def inspect_attributes
+      "@name=#{name.inspect}"
+    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/types.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/data'
+
+module SleepingKingStudios::Docs::Data
+  # Namespace for types, which represent a YARD type list.
+  #
+  # @see https://www.rubydoc.info/gems/yard/file/docs/Tags.md#types-specifier-list
+  module Types
+    autoload :KeyValueType,
+      'sleeping_king_studios/docs/data/types/key_value_type'
+    autoload :ParameterizedType,
+      'sleeping_king_studios/docs/data/types/parameterized_type'
+    autoload :Parser,
+      'sleeping_king_studios/docs/data/types/parser'
+    autoload :Type,
+      'sleeping_king_studios/docs/data/types/type'
+  end
+end

data/lib/sleeping_king_studios/docs/data.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs'
+
+module SleepingKingStudios::Docs
+  # Namespace for data objects, which represent documented code.
+  module Data
+    autoload :Base,
+      'sleeping_king_studios/docs/data/base'
+    autoload :ClassObject,
+      'sleeping_king_studios/docs/data/class_object'
+    autoload :ConstantObject,
+      'sleeping_king_studios/docs/data/constant_object'
+    autoload :Metadata,
+      'sleeping_king_studios/docs/data/metadata'
+    autoload :MethodObject,
+      'sleeping_king_studios/docs/data/method_object'
+    autoload :ModuleObject,
+      'sleeping_king_studios/docs/data/module_object'
+    autoload :NamespaceObject,
+      'sleeping_king_studios/docs/data/namespace_object'
+    autoload :RootObject,
+      'sleeping_king_studios/docs/data/root_object'
+    autoload :SeeTags,
+      'sleeping_king_studios/docs/data/see_tags'
+    autoload :Types,
+      'sleeping_king_studios/docs/data/types'
+  end
+end

data/lib/sleeping_king_studios/docs/errors/file_already_exists.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/errors'
+
+module SleepingKingStudios::Docs::Errors
+  # Error returned when attempting to create an existing file.
+  class FileAlreadyExists < SleepingKingStudios::Docs::Errors::FileError
+    # Short string used to identify the type of error.
+    TYPE = 'sleeping_king_studios.docs.errors.file_already_exists'
+
+    # @param path [String] the invalid file path.
+    def initialize(path:)
+      super(message: default_message(path), path:)
+    end
+
+    private
+
+    def default_message(path)
+      "file already exists at #{path.inspect}"
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/errors/file_error.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'cuprum/error'
+
+require 'sleeping_king_studios/docs/errors'
+
+module SleepingKingStudios::Docs::Errors
+  # Abstract base class for errors interacting with the file system.
+  class FileError < Cuprum::Error
+    # Short string used to identify the type of error.
+    TYPE = 'sleeping_king_studios.docs.errors.file_error'
+
+    # @param message [String] message describing the nature of the error.
+    # @param path [String] the invalid file or directory path.
+    def initialize(message:, path:)
+      super(message:)
+
+      @path = path
+    end
+
+    # @return [String] the invalid file or directory path.
+    attr_reader :path
+
+    private
+
+    def as_json_data
+      { 'path' => path.to_s }
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/errors/file_not_found.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/errors'
+
+module SleepingKingStudios::Docs::Errors
+  # Error returned when attempting to parse an invalid file or directory.
+  class FileNotFound < SleepingKingStudios::Docs::Errors::FileError
+    # Short string used to identify the type of error.
+    TYPE = 'sleeping_king_studios.docs.errors.file_not_found'
+
+    # @param path [String] the invalid file path.
+    def initialize(path:)
+      super(message: default_message(path), path:)
+    end
+
+    private
+
+    def default_message(path)
+      "file or directory not found at #{path.inspect}"
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/errors/invalid_directory.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/errors'
+
+module SleepingKingStudios::Docs::Errors
+  # Error returned when attempting to create an invalid directory.
+  class InvalidDirectory < SleepingKingStudios::Docs::Errors::FileError
+    # Short string used to identify the type of error.
+    TYPE = 'sleeping_king_studios.docs.errors.invalid_directory'
+
+    # @param path [String] the invalid directory path.
+    def initialize(path:)
+      super(message: default_message(path), path:)
+    end
+
+    private
+
+    def default_message(path)
+      "file already exists at #{path.inspect}"
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/errors/invalid_file.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/errors'
+
+module SleepingKingStudios::Docs::Errors
+  # Error returned when attempting to create an invalid file.
+  class InvalidFile < SleepingKingStudios::Docs::Errors::FileError
+    # Short string used to identify the type of error.
+    TYPE = 'sleeping_king_studios.docs.errors.invalid_file'
+
+    # @param path [String] the invalid file path.
+    def initialize(path:)
+      super(message: default_message(path), path:)
+    end
+
+    private
+
+    def default_message(path)
+      "directory already exists at #{path.inspect}"
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/errors.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs'
+
+module SleepingKingStudios::Docs
+  # Namespace for error objects, which encapsulate command failure states.
+  module Errors
+    autoload :FileAlreadyExists,
+      'sleeping_king_studios/docs/errors/file_already_exists'
+    autoload :FileError,
+      'sleeping_king_studios/docs/errors/file_error'
+    autoload :FileNotFound,
+      'sleeping_king_studios/docs/errors/file_not_found'
+    autoload :InvalidDirectory,
+      'sleeping_king_studios/docs/errors/invalid_directory'
+    autoload :InvalidFile,
+      'sleeping_king_studios/docs/errors/invalid_file'
+  end
+end

data/lib/sleeping_king_studios/docs/registry.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'yard'
+
+require 'sleeping_king_studios/docs'
+
+module SleepingKingStudios::Docs
+  # Dependency injection provider wrapping the YARD registry.
+  module Registry
+    # Clears the cached registry, if any.
+    def self.clear
+      @instance = nil
+    end
+
+    # Caches and returns the contents of the YARD registry.
+    #
+    # @return [Array] the cached registry.
+    def self.instance
+      @instance ||= [::YARD::Registry.root, *::YARD::Registry.to_a]
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/registry_query.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs'
+
+module SleepingKingStudios::Docs
+  # Checks for the presence of requested data in the YARD registry.
+  class RegistryQuery
+    # @param registry [Enumerable] the YARD registry.
+    def initialize(registry:)
+      @registry = registry
+    end
+
+    # Checks if the given class method is defined in the registry.
+    #
+    # @param method_name [String] the name of the method and defining namespace,
+    #   if any.
+    #
+    # @return [Boolean] true if the class method exists, otherwise false.
+    def class_method_exists?(method_name)
+      # Handle top-level class methods.
+      if method_name.start_with?('.')
+        return top_level_class_method_exists?(method_name)
+      end
+
+      # Handle legacy ::class_method format.
+      unless method_name.include?('.')
+        return legacy_class_method_exists?(method_name)
+      end
+
+      registry.any? do |obj|
+        obj.type == :method && obj.scope == :class && obj.title == method_name
+      end
+    end
+
+    # Checks if the given constant is defined in the registry.
+    #
+    # @param constant_name [String] the name of the constant and defining
+    #   namespace, if any.
+    #
+    # @return [Boolean] true if the constant exists, otherwise false.
+    def constant_exists?(constant_name)
+      registry.any? do |obj|
+        obj.type == :constant && obj.title == constant_name
+      end
+    end
+
+    # Checks if the given class or module is defined in the registry.
+    #
+    # @param module_name [String] the name of the class or module and defining
+    #   namespace, if any.
+    #
+    # @return [Boolean] true if the class or module exists, otherwise false.
+    def definition_exists?(module_name)
+      registry.any? do |obj|
+        (obj.type == :module || obj.type == :class) && obj.title == module_name # rubocop:disable Style/MultipleComparison
+      end
+    end
+
+    # Checks if the given instance method is defined in the registry.
+    #
+    # @param method_name [String] the name of the method and defining namespace,
+    #   if any.
+    #
+    # @return [Boolean] true if the instance method exists, otherwise false.
+    def instance_method_exists?(method_name)
+      registry.any? do |obj|
+        obj.type == :method &&
+          obj.scope == :instance &&
+          obj.title == method_name
+      end
+    end
+
+    private
+
+    attr_reader :registry
+
+    def legacy_class_method_exists?(method_name)
+      method_name = method_name.reverse.sub('::', '.').reverse
+
+      registry.any? do |obj|
+        obj.type == :method && obj.scope == :class && obj.title == method_name
+      end
+    end
+
+    def top_level_class_method_exists?(method_name)
+      method_name = "::#{method_name[1..]}"
+
+      registry.any? do |obj|
+        obj.type == :method && obj.scope == :class && obj.title == method_name
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'thor'
+
+require 'sleeping_king_studios/tools/toolbelt'
+
+require 'sleeping_king_studios/docs'
+
+module SleepingKingStudios::Docs
+  module Tasks
+    # Generic base CLI task.
+    class Base < Thor
+      private
+
+      def tools
+        SleepingKingStudios::Tools::Toolbelt.instance
+      end
+    end
+  end
+end