docscribe 1.4.1 → 1.4.2

data/lib/docscribe/cli.rb

@@ -6,6 +6,7 @@ require 'docscribe/cli/options'
 require 'docscribe/cli/run'
 
 module Docscribe
+  # CLI entry point and command dispatch.
   module CLI
     class << self
       # Main CLI entry point.
@@ -19,18 +20,35 @@ module Docscribe
       # @return [Integer] process exit code
       def run(argv)
         argv = argv.dup
+        return dispatch_subcommand(argv) if subcommand?(argv.first)
 
+        options = Docscribe::CLI::Options.parse!(argv)
+        Docscribe::CLI::Run.run(options: options, argv: argv)
+      end
+
+      private
+
+      # @private
+      # @param [String] cmd
+      # @return [Boolean]
+      def subcommand?(cmd)
+        %w[init generate].include?(cmd)
+      end
+
+      # @private
+      # @param [Array<String>] argv
+      # @return [Integer, nil]
+      def dispatch_subcommand(argv)
         case argv.first
         when 'init'
           argv.shift
-          return Docscribe::CLI::Init.run(argv)
+          Docscribe::CLI::Init.run(argv)
         when 'generate'
           argv.shift
-          return Docscribe::CLI::Generate.run(argv)
+          Docscribe::CLI::Generate.run(argv)
+        else
+          0
         end
-
-        options = Docscribe::CLI::Options.parse!(argv)
-        Docscribe::CLI::Run.run(options: options, argv: argv)
       end
     end
   end

data/lib/docscribe/config/defaults.rb

@@ -33,14 +33,14 @@ module Docscribe
       },
       'methods' => {
         'instance' => {
-          'public' => {},
-          'protected' => {},
-          'private' => {}
+          'public' => {}, #: Hash[String, untyped]
+          'protected' => {}, #: Hash[String, untyped]
+          'private' => {} #: Hash[String, untyped]
         },
         'class' => {
-          'public' => {},
-          'protected' => {},
-          'private' => {}
+          'public' => {}, #: Hash[String, untyped]
+          'protected' => {}, #: Hash[String, untyped]
+          'private' => {} #: Hash[String, untyped]
         }
       },
       'inference' => {
@@ -51,10 +51,10 @@ module Docscribe
       'filter' => {
         'visibilities' => %w[public protected private],
         'scopes' => %w[instance class],
-        'include' => [],
-        'exclude' => [],
+        'include' => [], #: Array[String]
+        'exclude' => [], #: Array[String]
         'files' => {
-          'include' => [],
+          'include' => [], #: Array[String]
           'exclude' => ['spec']
         }
       },
@@ -62,7 +62,7 @@ module Docscribe
         'enabled' => false,
         'collection' => false,
         'sig_dirs' => ['sig'],
-        'collection_dirs' => [],
+        'collection_dirs' => [], #: Array[String]
         'collapse_generics' => false
       },
       'sorbet' => {
@@ -71,7 +71,7 @@ module Docscribe
         'collapse_generics' => false
       },
       'plugins' => {
-        'require' => []
+        'require' => [] #: Array[String]
       }
     }.freeze
   end

data/lib/docscribe/config/emit.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Docscribe
+  # Emit-related configuration (headers, visibility tags, etc.).
   class Config
     # Whether to emit method header lines such as:
     #   # +MyClass#foo+ -> Integer

data/lib/docscribe/config/filtering.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Docscribe
+  # File and method include/exclude filtering.
   class Config
     # Decide whether a file path should be processed based on `filter.files`.
     #
@@ -11,15 +12,8 @@ module Docscribe
     # @raise [StandardError]
     # @return [Boolean]
     def process_file?(path)
-      files = raw.dig('filter', 'files') || {}
-      include_patterns = normalize_file_patterns(files['include'])
-      exclude_patterns = normalize_file_patterns(files['exclude'])
-
-      rel = begin
-        Pathname.new(path).expand_path.relative_path_from(Pathname.pwd).cleanpath.to_s
-      rescue StandardError
-        path
-      end
+      include_patterns, exclude_patterns = load_file_patterns
+      rel = relative_path(path)
 
       return false if file_matches_any?(exclude_patterns, rel)
       return true if include_patterns.empty?
@@ -27,6 +21,27 @@ module Docscribe
       file_matches_any?(include_patterns, rel)
     end
 
+    # Load normalized file include/exclude patterns from config.
+    #
+    # @private
+    # @return [Array(Array<String>, Array<String>)] include_patterns, exclude_patterns
+    def load_file_patterns
+      files = raw.dig('filter', 'files') || {}
+      [normalize_file_patterns(files['include']), normalize_file_patterns(files['exclude'])]
+    end
+
+    # Compute the relative path for filtering.
+    #
+    # @private
+    # @param [String] path
+    # @raise [StandardError]
+    # @return [String]
+    def relative_path(path)
+      Pathname.new(path).expand_path.relative_path_from(Pathname.pwd).cleanpath.to_s
+    rescue StandardError
+      path
+    end
+
     # Decide whether a method should be processed based on configured method filters.
     #
     # Method IDs are normalized as:
@@ -55,8 +70,6 @@ module Docscribe
       matches_any?(inc, method_id)
     end
 
-    private
-
     # Normalize file filter patterns:
     # - compact nils
     # - stringify

data/lib/docscribe/config/loader.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Docscribe
+  # YAML config file loading and resolution.
   class Config
     # Load Docscribe configuration from YAML.
     #
@@ -12,7 +13,7 @@ module Docscribe
     # @param [String, nil] path optional config path
     # @return [Docscribe::Config]
     def self.load(path = nil)
-      raw = {}
+      raw = {} #: Hash[String, untyped]
       if path && File.file?(path)
         raw = safe_load_file_compat(path)
       elsif File.file?('docscribe.yml')
@@ -30,10 +31,12 @@ module Docscribe
     # @return [Hash]
     def self.safe_load_file_compat(path)
       if YAML.respond_to?(:safe_load_file)
-        YAML.safe_load_file(path, permitted_classes: [], permitted_symbols: [], aliases: true) || {}
+        YAML.safe_load_file(path,
+                            permitted_classes: [], permitted_symbols: [],
+                            aliases: true) || {} #: Hash[String, untyped]
       else
         yaml = File.open(path, 'r:bom|utf-8', &:read)
-        safe_load_compat(yaml, filename: path) || {}
+        safe_load_compat(yaml, filename: path) || {} #: Hash[String, untyped]
       end
     end
 
@@ -50,7 +53,7 @@ module Docscribe
         permitted_symbols: [],
         aliases: true,
         filename: filename
-      )
+      ) #: Hash[String, untyped]
     rescue ArgumentError
       # Older Psych signature uses positional args
       Psych.safe_load(yaml, [], [], true, filename)

data/lib/docscribe/config/plugin.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Docscribe
+  # Plugin loading and registration from config.
   class Config
     # Load and register plugins declared under `plugins.require` in config.
     #

data/lib/docscribe/config/rbs.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Docscribe
+  # RBS signature provider configuration.
   class Config
     # Return a memoized RBS provider if RBS integration is enabled and available.
     #
@@ -13,16 +14,7 @@ module Docscribe
       return nil unless rbs_enabled?
       return nil unless ruby_supports_rbs?
 
-      @rbs_provider ||= begin
-        require 'docscribe/types/rbs/provider'
-        Docscribe::Types::RBS::Provider.new(
-          sig_dirs: rbs_sig_dirs,
-          collection_dirs: rbs_collection_dirs,
-          collapse_generics: rbs_collapse_generics?
-        )
-      rescue LoadError
-        nil
-      end
+      @rbs_provider ||= build_rbs_provider
     end
 
     # Whether RBS integration is enabled.
@@ -32,27 +24,17 @@ module Docscribe
       fetch_bool(%w[rbs enabled], false)
     end
 
-    # Method documentation.
-    #
     # @raise [LoadError]
     # @return [Object]
     def core_rbs_provider
       return nil unless ruby_supports_rbs?
 
-      @core_rbs_provider ||= begin
-        require 'docscribe/types/rbs/provider'
-        Docscribe::Types::RBS::Provider.new(
-          sig_dirs: [],
-          collapse_generics: false
-        )
-      rescue LoadError
-        nil
-      end
+      @core_rbs_provider ||= build_core_rbs_provider
     end
 
     private
 
-    # Method documentation.
+    # Check whether the current Ruby version supports RBS (requires 3.0+).
     #
     # @private
     # @return [Boolean]
@@ -66,6 +48,33 @@ module Docscribe
       false
     end
 
+    # @private
+    # @raise [LoadError]
+    # @return [Docscribe::Types::RBS::Provider, nil]
+    def build_rbs_provider
+      require 'docscribe/types/rbs/provider'
+      Docscribe::Types::RBS::Provider.new(
+        sig_dirs: rbs_sig_dirs,
+        collection_dirs: rbs_collection_dirs,
+        collapse_generics: rbs_collapse_generics?
+      )
+    rescue LoadError
+      nil
+    end
+
+    # @private
+    # @raise [LoadError]
+    # @return [Docscribe::Types::RBS::Provider, nil]
+    def build_core_rbs_provider
+      require 'docscribe/types/rbs/provider'
+      Docscribe::Types::RBS::Provider.new(
+        sig_dirs: [],
+        collapse_generics: false
+      )
+    rescue LoadError
+      nil
+    end
+
     # Signature directories used by the RBS provider.
     #
     # @private

data/lib/docscribe/config/sorbet.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Docscribe
+  # Sorbet and signature provider configuration.
   class Config
     # Build the effective external signature provider chain for a given source.
     #
@@ -16,25 +17,50 @@ module Docscribe
     # @raise [LoadError]
     # @return [Docscribe::Types::ProviderChain, nil]
     def signature_provider_for(source:, file:)
-      providers = []
+      providers = [] #: Array[untyped]
+      append_sorbet_providers(providers, source: source, file: file)
+      providers << rbs_provider if rbs_enabled?
+      build_provider_chain(providers)
+    end
 
-      if sorbet_enabled?
-        begin
-          require 'docscribe/types/sorbet/source_provider'
-          providers << Docscribe::Types::Sorbet::SourceProvider.new(
-            source: source,
-            file: file,
-            collapse_generics: sorbet_collapse_generics?
-          )
-        rescue LoadError
-          # Sorbet support is optional; fall back quietly.
-        end
+    # Append Sorbet-based providers to the list.
+    #
+    # @private
+    # @param [Array] providers
+    # @param [String] source
+    # @param [String] file
+    # @return [void]
+    def append_sorbet_providers(providers, source:, file:)
+      return unless sorbet_enabled?
 
-        providers << sorbet_rbi_provider
-      end
+      providers << sorbet_source_provider(source, file)
+      providers << sorbet_rbi_provider
+    end
 
-      providers << rbs_provider if rbs_enabled?
+    # Build a Sorbet source provider (inline sigs).
+    #
+    # @private
+    # @param [String] source
+    # @param [String] file
+    # @raise [LoadError]
+    # @return [Docscribe::Types::Sorbet::SourceProvider, nil]
+    def sorbet_source_provider(source, file)
+      require 'docscribe/types/sorbet/source_provider'
+      Docscribe::Types::Sorbet::SourceProvider.new(
+        source: source,
+        file: file,
+        collapse_generics: sorbet_collapse_generics?
+      )
+    rescue LoadError
+      nil
+    end
 
+    # Build the provider chain from a non-empty list, or return nil.
+    #
+    # @private
+    # @param [Array] providers
+    # @return [Docscribe::Types::ProviderChain, nil]
+    def build_provider_chain(providers)
       providers = providers.compact
       return nil if providers.empty?
 

data/lib/docscribe/config/sorting.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Docscribe
+  # Tag sorting configuration.
   class Config
     # Whether sortable tag normalization is enabled for doc-like blocks.
     #

data/lib/docscribe/config/template.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Docscribe
+  # Default YAML config template for `docscribe init`.
   class Config
     # Return the default YAML template used by `docscribe init`.
     #

data/lib/docscribe/config/utils.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Docscribe
+  # Internal config utility methods.
   class Config
     private
 

data/lib/docscribe/config.rb

@@ -5,6 +5,7 @@ require 'pathname'
 require 'psych'
 
 module Docscribe
+  # Application configuration with deep-merge defaults and overrides.
   class Config
     # Raw config hash after deep-merging user config with defaults.
     #

data/lib/docscribe/infer/constants.rb

@@ -7,5 +7,20 @@ module Docscribe
 
     # Ruby's implicit rescue target for bare `rescue`.
     DEFAULT_ERROR = 'StandardError'
+
+    # Node type to literal type name mapping.
+    LITERAL_TYPE_MAP = {
+      int: 'Integer',
+      float: 'Float',
+      str: 'String',
+      dstr: 'String',
+      sym: 'Symbol',
+      true: 'Boolean',
+      false: 'Boolean',
+      nil: 'nil',
+      array: 'Array',
+      hash: 'Hash',
+      regexp: 'Regexp'
+    }.freeze
   end
 end

data/lib/docscribe/infer/literals.rb

@@ -24,31 +24,49 @@ module Docscribe
       def type_from_literal(node, fallback_type: FALLBACK_TYPE)
         return fallback_type unless node
 
-        case node.type
-        when :int then 'Integer'
-        when :float then 'Float'
-        when :str, :dstr then 'String'
-        when :sym then 'Symbol'
-        when :true, :false then 'Boolean' # rubocop:disable Lint/BooleanSymbol
-        when :nil then 'nil'
-        when :array then 'Array'
-        when :hash then 'Hash'
-        when :regexp then 'Regexp'
-
-        when :const
-          node.children.last.to_s
-
-        when :send
-          recv, meth, = node.children
-          if meth == :new && recv && recv.type == :const
-            recv.children.last.to_s
-          else
-            fallback_type
-          end
-
-        else
-          fallback_type
-        end
+        literal_type_for(node.type) || const_type_for(node, fallback_type) ||
+          send_new_type_for(node, fallback_type) || fallback_type
+      end
+
+      # Map a node type symbol to a known literal type name.
+      #
+      # @note module_function: when included, also defines # (instance visibility: private)
+      # @private
+      # @param [Symbol] type node type
+      # @return [String, nil]
+      def literal_type_for(type)
+        LITERAL_TYPE_MAP[type]
+      end
+
+      # Extract a constant name from a `:const` node.
+      #
+      # @note module_function: when included, also defines # (instance visibility: private)
+      # @private
+      # @param [Parser::AST::Node] node
+      # @param [String] fallback_type
+      # @param [String] _fallback_type fallback type string (unused here)
+      # @return [String, nil]
+      def const_type_for(node, _fallback_type)
+        return unless node.type == :const
+
+        node.children.last.to_s
+      end
+
+      # Extract a type from a `Foo.new` send node.
+      #
+      # @note module_function: when included, also defines # (instance visibility: private)
+      # @private
+      # @param [Parser::AST::Node] node
+      # @param [String] fallback_type
+      # @param [String] _fallback_type fallback type string (unused here)
+      # @return [String, nil]
+      def send_new_type_for(node, _fallback_type)
+        return unless node.type == :send
+
+        recv, meth, = node.children
+        return unless meth == :new && recv&.type == :const
+
+        recv.children.last.to_s
       end
     end
   end

data/lib/docscribe/infer/names.rb

@@ -16,26 +16,35 @@ module Docscribe
       # Returns nil for unsupported nodes.
       #
       # @note module_function: when included, also defines #const_full_name (instance visibility: private)
-      # @param [Parser::AST::Node, nil] n constant-like AST node
+      # @param [Parser::AST::Node, nil] node constant-like AST node
       # @return [String, nil]
-      def const_full_name(n)
-        return nil unless n.is_a?(Parser::AST::Node)
+      def const_full_name(node)
+        return nil unless node.is_a?(Parser::AST::Node)
 
-        case n.type
+        case node.type
         when :const
-          scope, name = *n
-          scope_name = const_full_name(scope)
+          build_const_full_name(node)
+        when :cbase
+          ''
+        end
+      end
 
-          if scope_name && !scope_name.empty?
-            "#{scope_name}::#{name}"
-          elsif scope_name == '' # leading ::
-            "::#{name}"
-          else
-            name.to_s
-          end
+      # Build the fully qualified name from a `:const` node.
+      #
+      # @note module_function: when included, also defines # (instance visibility: private)
+      # @private
+      # @param [Parser::AST::Node] node a `:const` node
+      # @return [String]
+      def build_const_full_name(node)
+        scope, name = *node
+        scope_name = const_full_name(scope)
 
-        when :cbase
-          '' # represents leading :: scope
+        if scope_name && !scope_name.empty?
+          "#{scope_name}::#{name}"
+        elsif scope_name == ''
+          "::#{name}"
+        else
+          name.to_s
         end
       end
     end

data/lib/docscribe/infer/params.rb

@@ -23,23 +23,69 @@ module Docscribe
       #   be treated specially as Hash
       # @return [String]
       def infer_param_type(name, default_str, fallback_type: FALLBACK_TYPE, treat_options_keyword_as_hash: true)
+        prefix_param_type(name) || inferred_param_type(name, default_str, fallback_type,
+                                                       treat_options_keyword_as_hash: treat_options_keyword_as_hash)
+      end
+
+      # Return type for special parameter prefixes.
+      #
+      # @note module_function: when included, also defines # (instance visibility: private)
+      # @private
+      # @param [String] name parameter name
+      # @return [String, nil]
+      def prefix_param_type(name)
         return 'Array' if name.start_with?('*') && !name.start_with?('**')
         return 'Hash'  if name.start_with?('**')
         return 'Proc'  if name.start_with?('&')
 
-        is_kw = name.end_with?(':')
-        node = parse_expr(default_str)
-        ty = Literals.type_from_literal(node, fallback_type: fallback_type)
+        nil
+      end
 
-        if is_kw && default_str.nil?
-          return (treat_options_keyword_as_hash && name == 'options:' ? 'Hash' : fallback_type)
+      # Infer type for a regular or keyword parameter with optional default.
+      #
+      # @note module_function: when included, also defines # (instance visibility: private)
+      # @private
+      # @param [String] name parameter name
+      # @param [String, nil] default_str default expression source
+      # @param [String] fallback_type
+      # @param [Boolean] treat_options_keyword_as_hash
+      # @return [String]
+      def inferred_param_type(name, default_str, fallback_type, treat_options_keyword_as_hash:)
+        if name.end_with?(':') && default_str.nil?
+          return options_keyword_type(name, treat_options_keyword_as_hash, fallback_type)
         end
 
-        return 'Hash' if treat_options_keyword_as_hash && name == 'options:' && (default_str == '{}' || ty == 'Hash')
+        node = parse_expr(default_str)
+        ty = Literals.type_from_literal(node, fallback_type: fallback_type)
+
+        return 'Hash' if options_hash_keyword?(name, default_str, ty, treat_options_keyword_as_hash)
 
         ty
       end
 
+      # Return 'Hash' for a keyword parameter named 'options:' when special-cased, else fallback.
+      #
+      # @note module_function: when included, also defines #options_keyword_type (instance visibility: private)
+      # @param [String] name parameter name
+      # @param [Boolean] treat_options_keyword_as_hash whether to treat 'options:' as Hash
+      # @param [String] fallback_type type returned when not special-cased
+      # @return [String]
+      def options_keyword_type(name, treat_options_keyword_as_hash, fallback_type)
+        treat_options_keyword_as_hash && name == 'options:' ? 'Hash' : fallback_type
+      end
+
+      # Whether a keyword parameter named 'options:' with a hash default should be typed as Hash.
+      #
+      # @note module_function: when included, also defines #options_hash_keyword? (instance visibility: private)
+      # @param [String] name parameter name
+      # @param [String, nil] default_str default expression source
+      # @param [String] type inferred type
+      # @param [Boolean] treat_options_keyword_as_hash whether to treat 'options:' as Hash
+      # @return [Boolean]
+      def options_hash_keyword?(name, default_str, type, treat_options_keyword_as_hash)
+        treat_options_keyword_as_hash && name == 'options:' && (default_str == '{}' || type == 'Hash')
+      end
+
       # Parse a standalone expression for parameter-default inference.
       #
       # Returns nil if the expression is empty or cannot be parsed.