docscribe 1.4.1 → 1.5.0

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`.
     #
@@ -8,18 +9,10 @@ module Docscribe
     # Exclude rules win. If no include rules are configured, files are included by default.
     #
     # @param [String] path file path to test
-    # @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 +20,26 @@ module Docscribe
       file_matches_any?(include_patterns, rel)
     end
 
+    # Load normalized file include/exclude patterns from config.
+    #
+    # @return [(Array<String>, Array<String>)]
+    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.
+    #
+    # @param [String] path file path to test
+    # @raise [StandardError]
+    # @return [String] if StandardError
+    # @return [Object] if StandardError
+    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,16 +68,13 @@ module Docscribe
       matches_any?(inc, method_id)
     end
 
-    private
-
     # Normalize file filter patterns:
     # - compact nils
     # - stringify
     # - remove empties
     # - expand shorthand directory forms
     #
-    # @private
-    # @param [Array<String>, nil] list raw pattern list
+    # @param [Array<String>?] list raw pattern list
     # @return [Array<String>]
     def normalize_file_patterns(list)
       Array(list).compact.map(&:to_s).reject(&:empty?).flat_map { |pat| expand_directory_shorthand(pat) }.uniq
@@ -76,8 +86,7 @@ module Docscribe
     # - `"spec/"` => `"spec/**/*"`
     # - `"spec"` => `"spec/**/*"` if `spec` exists as a directory
     #
-    # @private
-    # @param [String] pattern
+    # @param [String] pattern file pattern to expand
     # @return [Array<String>]
     def expand_directory_shorthand(pattern)
       pat = pattern.dup
@@ -93,9 +102,8 @@ module Docscribe
 
     # Check whether a file path matches any configured file pattern.
     #
-    # @private
-    # @param [Array<String>] patterns
-    # @param [String] path
+    # @param [Array<String>] patterns file filter patterns
+    # @param [String] path file path to test
     # @return [Boolean]
     def file_matches_any?(patterns, path)
       patterns.any? { |pat| file_match_pattern?(pat, path) }
@@ -108,13 +116,12 @@ module Docscribe
     # - globs
     # - recursive glob shorthand normalization
     #
-    # @private
-    # @param [String] pattern
-    # @param [String] path
+    # @param [String] pattern file filter pattern
+    # @param [String] path file path to test
     # @return [Boolean]
     def file_match_pattern?(pattern, path)
       if pattern.start_with?('/') && pattern.end_with?('/') && pattern.length >= 2
-        return Regexp.new(pattern[1..-2]).match?(path)
+        return Regexp.new(pattern[1..-2]).match?(path) # steep:ignore
       end
 
       patterns_to_try = [pattern]
@@ -127,34 +134,33 @@ module Docscribe
 
     # Allowed method scopes from config/defaults.
     #
-    # @private
     # @return [Array<String>]
     def filter_scopes
-      Array(raw.dig('filter', 'scopes') || DEFAULT.dig('filter', 'scopes')).map(&:to_s)
+      Array(raw.dig('filter', 'scopes') || DEFAULT.dig('filter', 'scopes')).map(&:to_s) # steep:ignore
     end
 
     # Allowed method visibilities from config/defaults.
     #
-    # @private
     # @return [Array<String>]
     def filter_visibilities
-      Array(raw.dig('filter', 'visibilities') || DEFAULT.dig('filter', 'visibilities')).map(&:to_s)
+      Array(raw.dig('filter', 'visibilities') ||
+            DEFAULT.dig('filter', 'visibilities')).map(&:to_s) # steep:ignore
     end
 
     # Exclude method filter patterns.
     #
-    # @private
     # @return [Array<String>]
     def filter_exclude_patterns
-      Array(raw.dig('filter', 'exclude') || DEFAULT.dig('filter', 'exclude')).map(&:to_s).reject(&:empty?)
+      Array(raw.dig('filter', 'exclude') ||
+            DEFAULT.dig('filter', 'exclude')).map(&:to_s).reject(&:empty?) # steep:ignore
     end
 
     # Include method filter patterns.
     #
-    # @private
     # @return [Array<String>]
     def filter_include_patterns
-      Array(raw.dig('filter', 'include') || DEFAULT.dig('filter', 'include')).map(&:to_s).reject(&:empty?)
+      Array(raw.dig('filter', 'include') ||
+            DEFAULT.dig('filter', 'include')).map(&:to_s).reject(&:empty?) # steep:ignore
     end
   end
 end

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.
     #
@@ -9,10 +10,10 @@ module Docscribe
     # - `docscribe.yml` in the current directory, if present
     # - otherwise defaults only
     #
-    # @param [String, nil] path optional config path
+    # @param [String?] 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')
@@ -27,33 +28,39 @@ module Docscribe
     # and calling {safe_load_compat}.
     #
     # @param [String] path file path
-    # @return [Hash]
+    # @return [Hash<String, Object>]
     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) || {}
+      if YAML.respond_to?(:safe_load_file) # steep:ignore
+        pclasses = [] #: Array[String]
+        psymbols = [] #: Array[Symbol]
+        YAML.safe_load_file(path, # steep:ignore
+                            permitted_classes: pclasses, permitted_symbols: psymbols,
+                            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
 
     # Safely load YAML from a string across Psych API versions.
     #
     # @param [String] yaml YAML document
-    # @param [String, nil] filename optional filename for diagnostics
+    # @param [String?] filename optional filename for diagnostics
     # @raise [ArgumentError]
-    # @return [Hash]
+    # @return [Hash<String, Object>] if ArgumentError
+    # @return [Object] if ArgumentError
     def self.safe_load_compat(yaml, filename: nil)
-      Psych.safe_load(
+      pclasses = [] #: Array[String]
+      psymbols = [] #: Array[Symbol]
+      Psych.safe_load( # steep:ignore
         yaml,
-        permitted_classes: [],
-        permitted_symbols: [],
+        permitted_classes: pclasses, permitted_symbols: psymbols,
         aliases: true,
         filename: filename
-      )
+      ) #: Hash[String, untyped]
     rescue ArgumentError
       # Older Psych signature uses positional args
-      Psych.safe_load(yaml, [], [], true, filename)
+      Psych.safe_load(yaml, [], [], true, filename) # steep:ignore
     end
   end
 end

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.
     #
@@ -14,7 +15,7 @@ module Docscribe
     # @raise [LoadError]
     # @return [void]
     def load_plugins!
-      paths = Array(raw.dig('plugins', 'require')).compact
+      paths = Array(raw.dig('plugins', 'require')).compact #: Array[String]
       return if paths.empty?
 
       require 'docscribe/plugin'

data/lib/docscribe/config/rbs.rb

@@ -1,28 +1,19 @@
 # frozen_string_literal: true
 
 module Docscribe
+  # RBS signature provider configuration.
   class Config
     # Return a memoized RBS provider if RBS integration is enabled and available.
     #
     # If RBS cannot be loaded, this returns nil and Docscribe falls back to
     # inference.
     #
-    # @raise [LoadError]
     # @return [Docscribe::Types::RBS::Provider, nil]
     def rbs_provider
       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 +23,28 @@ module Docscribe
       fetch_bool(%w[rbs enabled], false)
     end
 
-    # Method documentation.
+    # Core rbs provider
     #
-    # @raise [LoadError]
-    # @return [Object]
+    # @return [Docscribe::Types::RBS::Provider, nil]
     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
+
+    # Whether to warn when rbs_collection.lock.yaml exists but --rbs-collection
+    # was not passed.
+    #
+    # Set `rbs.warn_missing_collection: false` in `docscribe.yml` to suppress.
+    #
+    # @return [Boolean]
+    def rbs_warn_missing_collection?
+      fetch_bool(%w[rbs warn_missing_collection], true)
     end
 
     private
 
-    # Method documentation.
+    # Check whether the current Ruby version supports RBS (requires 3.0+).
     #
     # @private
     # @return [Boolean]
@@ -66,12 +58,47 @@ module Docscribe
       false
     end
 
+    # Build rbs provider
+    #
+    # @private
+    # @raise [LoadError]
+    # @return [Docscribe::Types::RBS::Provider, nil] if LoadError
+    # @return [nil] if LoadError
+    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?,
+        collapse_object_generics: rbs_collapse_object_generics?
+      )
+    rescue LoadError
+      warn 'Docscribe: --rbs requires the `rbs` gem. Add `gem "rbs"` to your Gemfile and run `bundle install`.'
+      nil
+    end
+
+    # Build core rbs provider
+    #
+    # @private
+    # @raise [LoadError]
+    # @return [Docscribe::Types::RBS::Provider, nil] if LoadError
+    # @return [nil] if LoadError
+    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
     # @return [Array<String>]
     def rbs_sig_dirs
-      Array(raw.dig('rbs', 'sig_dirs') || DEFAULT.dig('rbs', 'sig_dirs')).map(&:to_s)
+      Array(raw.dig('rbs', 'sig_dirs') || DEFAULT.dig('rbs', 'sig_dirs')).map(&:to_s) # steep:ignore
     end
 
     # RBS collection directories (auto-discovered from rbs_collection.lock.yaml).
@@ -83,7 +110,7 @@ module Docscribe
     # @private
     # @return [Array<String>]
     def rbs_collection_dirs
-      Array(raw.dig('rbs', 'collection_dirs')).map(&:to_s)
+      Array(raw.dig('rbs', 'collection_dirs')).map(&:to_s) # steep:ignore
     end
 
     # Whether generic RBS types should be collapsed to simpler container names.
@@ -93,9 +120,23 @@ module Docscribe
     # - `Array<Integer>`       => `Array`
     #
     # @private
-    # @return [Object]
+    # @return [Boolean]
     def rbs_collapse_generics?
       fetch_bool(%w[rbs collapse_generics], false)
     end
+
+    # Whether to collapse generic types when all inner types are Object.
+    #
+    # Unlike `collapse_generics` (which drops all generic info), this only
+    # collapses when the type arguments provide no useful information:
+    # - `Hash<Symbol, Object>` => stays as is (Symbol is useful)
+    # - `Hash<Object, Object>` => `Hash`
+    # - `Array<Object>`        => `Array`
+    #
+    # @private
+    # @return [Boolean]
+    def rbs_collapse_object_generics?
+      fetch_bool(%w[rbs collapse_object_generics], false)
+    end
   end
 end

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.
     #
@@ -13,28 +14,50 @@ module Docscribe
     #
     # @param [String] source Ruby source being rewritten
     # @param [String] file source name for diagnostics
-    # @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.
+    #
+    # @param [Array<Object>] providers provider list to populate
+    # @param [String] source Ruby source being rewritten
+    # @param [String] file source name for diagnostics
+    # @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).
+    #
+    # @param [String] source Ruby source being rewritten
+    # @param [String] file source name for diagnostics
+    # @raise [LoadError]
+    # @return [Docscribe::Types::Sorbet::SourceProvider, nil] if LoadError
+    # @return [nil] if LoadError
+    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.
+    #
+    # @param [Array<Object>] providers provider list to chain
+    # @return [Docscribe::Types::ProviderChain, nil]
+    def build_provider_chain(providers)
       providers = providers.compact
       return nil if providers.empty?
 
@@ -71,7 +94,7 @@ module Docscribe
     #
     # @return [Array<String>]
     def sorbet_rbi_dirs
-      Array(raw.dig('sorbet', 'rbi_dirs') || DEFAULT.dig('sorbet', 'rbi_dirs')).map(&:to_s)
+      Array(raw.dig('sorbet', 'rbi_dirs') || DEFAULT.dig('sorbet', 'rbi_dirs')).map(&:to_s) # steep:ignore
     end
 
     # Whether generic Sorbet/RBI container types should be simplified.

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.
     #
@@ -16,7 +17,7 @@ module Docscribe
     # @return [Array<String>]
     def tag_order
       Array(raw.dig('doc', 'tag_order') || DEFAULT.dig('doc', 'tag_order')).map do |t|
-        t.to_s.sub(/\A@/, '')
+        t.to_s.sub(/\A@/, '') # steep:ignore
       end
     end
   end

data/lib/docscribe/config/template.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 module Docscribe
+  # Default YAML config template for `docscribe init`.
   class Config
     # Return the default YAML template used by `docscribe init`.
     #
     # The template documents the most common CLI workflows and all supported
     # configuration sections with comments.
-    # @see Docscribe::Config::DEFAULT
     #
     # @return [String]
     def self.default_yaml
@@ -20,6 +20,7 @@ module Docscribe
         #   bundle exec docscribe lib          # check what would change
         #   bundle exec docscribe -a lib       # apply safe updates
         #   bundle exec docscribe -A lib       # rebuild all doc blocks
+        #   bundle exec docscribe -AkB lib     # rebuild, keep descriptions, no boilerplate
 
         emit:
           # What to include in generated documentation
@@ -88,7 +89,9 @@ module Docscribe
           sig_dirs: ["sig"]
           collection_dirs: []                 # auto-discovered from --rbs-collection
           collapse_generics: false            # Hash<Symbol, String> => Hash
+          collapse_object_generics: false     # Hash<Object, Object> => Hash (keep if inner types are useful)
           collection: false                   # auto-discover from rbs_collection.lock.yaml
+          warn_missing_collection: true       # warn if rbs_collection.lock.yaml exists without --rbs-collection
 
         sorbet:
           # Use Sorbet inline sigs and RBI files for better types
@@ -96,6 +99,12 @@ module Docscribe
           rbi_dirs: ["sorbet/rbi", "rbi"]
           collapse_generics: false
 
+        # Preserve existing @param/@return descriptions in aggressive mode
+        keep_descriptions: false
+
+        # Skip @param for anonymous block arguments (&) (Ruby 3.2+)
+        skip_anonymous_block_params: false
+
         plugins:
           # Load custom plugins
           # Example:

data/lib/docscribe/config/utils.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Docscribe
+  # Internal config utility methods.
   class Config
     private
 
@@ -45,7 +46,7 @@ module Docscribe
     # Convert an internal scope symbol into the config key used under `methods`.
     #
     # @private
-    # @param [Symbol] scope
+    # @param [Symbol] scope :instance or :class
     # @return [String]
     def scope_to_key(scope)
       scope == :class ? 'class' : 'instance'
@@ -54,8 +55,8 @@ module Docscribe
     # Check whether any pattern matches the given text.
     #
     # @private
-    # @param [Array<String>] patterns
-    # @param [String] text
+    # @param [Array<String>] patterns filter patterns to match
+    # @param [String] text text to test against patterns
     # @return [Boolean]
     def matches_any?(patterns, text)
       patterns.any? { |pat| match_pattern?(pat, text) }
@@ -68,12 +69,14 @@ module Docscribe
     # - shell-style glob patterns (with `/` translated to `#` since method IDs use `#`)
     #
     # @private
-    # @param [String] pattern
-    # @param [String] text
+    # @param [String] pattern filter pattern to match
+    # @param [String] text method ID to test
     # @return [Boolean]
     def match_pattern?(pattern, text)
       if pattern.start_with?('/') && pattern.end_with?('/') && pattern.length >= 2
-        Regexp.new(pattern[1..-2]).match?(text)
+        Regexp.new(pattern[1..-2]).match?(text) # steep:ignore
+      elsif pattern.count('*?[{').zero?
+        File.fnmatch?("*#{pattern.tr('/', '#')}*", text, File::FNM_EXTGLOB)
       else
         File.fnmatch?(pattern.tr('/', '#'), text, File::FNM_EXTGLOB)
       end
@@ -84,9 +87,9 @@ module Docscribe
     # Nested hashes are merged recursively; non-hash values are replaced.
     #
     # @private
-    # @param [Hash] hash1 base hash
-    # @param [Hash, nil] hash2 override hash
-    # @return [Hash]
+    # @param [Hash<Object, Object>] hash1 base hash
+    # @param [Hash<Object, Object>, nil] hash2 override hash
+    # @return [Hash<Object, Object>]
     def deep_merge(hash1, hash2)
       return hash1 unless hash2
 

data/lib/docscribe/config.rb

@@ -5,18 +5,17 @@ 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.
-    #
     # @!attribute [r] raw
-    #   @return [Hash]
+    #   @return [Hash<String, Object>]
     attr_reader :raw
 
     # Create a configuration object from a raw config hash.
     #
     # Missing keys are filled from {DEFAULT} via deep merge.
     #
-    # @param [Hash, nil] raw user-provided config hash
+    # @param [Hash<String, Object>] raw user-provided config hash
     # @return [void]
     def initialize(raw = {})
       @raw = deep_merge(DEFAULT, raw || {})

data/lib/docscribe/infer/ast_walk.rb

@@ -11,7 +11,7 @@ module Docscribe
       # Yields each node exactly once, descending recursively through child nodes.
       # Non-AST values are ignored.
       #
-      # @note module_function: when included, also defines #walk (instance visibility: private)
+      # @note module_function: defines #walk (visibility: private)
       # @param [Parser::AST::Node, nil] node root AST node
       # @param [Proc] block visitor block
       # @return [void]

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