docscribe 1.6.0 → 1.6.2

data/lib/docscribe/cli/update_types.rb

@@ -10,7 +10,7 @@ module Docscribe
     # Two-pass update: rebuild docs then re-merge with RBS types.
     #
     # Usage:
-    #   docscribe update_types [directory]
+    #   docscribe update_types [directory|file]
     #
     # Pass 1: `-AkB --rbs-collection <dir>` — aggressive rebuild, keep descriptions,
     #   no boilerplate, using RBS collection signatures.
@@ -18,7 +18,7 @@ module Docscribe
     #   using RBS collection signatures.
     module UpdateTypes
       BANNER = <<~TEXT
-        Usage: docscribe update_types [directory]
+        Usage: docscribe update_types [directory|file] [options]
 
         Two-pass type-aware documentation update.
 
@@ -28,6 +28,8 @@ module Docscribe
         Pass 2 (safe):        docscribe -aB --rbs-collection <dir>
           safe merge cleanup, no boilerplate
 
+        See `docscribe --help` for type options (--rbs, --sig-dir, --rbs-collection, --[no-]validate-types).
+
       TEXT
 
       class << self
@@ -35,14 +37,15 @@ module Docscribe
         # @return [Integer]
         def run(argv)
           options = parse_options(argv)
-          dir = options[:dir]
+          target = options[:dir]
+          @extra_argv = options[:extra_argv]
 
           announce_start
 
-          exit1 = run_first_pass(dir)
+          exit1 = run_first_pass(target)
           return exit1 unless exit1.zero?
 
-          exit2 = run_second_pass(dir)
+          exit2 = run_second_pass(target)
           return exit2 unless exit2.zero?
 
           announce_complete
@@ -54,13 +57,28 @@ module Docscribe
         # @private
         # @param [Array<String>] argv
         # @return [Hash<Symbol, Object>]
-        def parse_options(argv)
-          options = { dir: '.' }
+        def parse_options(argv) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+          options = { dir: '.', extra_argv: [] }
+          extra_argv = []
           OptionParser.new(BANNER) do |opts|
             opts.on('-h', '--help', 'Show this help') { puts opts or exit 0 }
+            opts.on('--[no-]rbs', 'Use RBS signatures when available') do |v|
+              extra_argv << (v ? '--rbs' : '--no-rbs')
+            end
+            opts.on('--sig-dir DIR', 'Add an RBS signature directory (repeatable). Implies --rbs.') do |v|
+              extra_argv << '--sig-dir' << v
+            end
+            opts.on('--rbs-collection', 'Auto-discover RBS collection from rbs_collection.lock.yaml. Implies --rbs.') do
+              extra_argv << '--rbs-collection'
+            end
+            opts.on('--[no-]validate-types', 'Validate YARD types against inferred/RBS types (optional, default: off)') do |v|
+              extra_argv << (v ? '--validate-types' : '--no-validate-types')
+            end
             opts.parse!(argv)
           end
           options[:dir] = argv.first if argv.any?
+          options[:extra_argv] = extra_argv
+          @extra_argv = extra_argv
           options
         end
 
@@ -72,23 +90,49 @@ module Docscribe
         end
 
         # @private
-        # @param [String] dir
+        # @param [String] target
         # @return [Integer]
-        def run_first_pass(dir)
-          puts 'Pass 1: Aggressive rebuild with RBS collection...'
-          argv1 = ['-AkB', '--rbs-collection', dir]
+        def run_first_pass(target) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+          dir_for_flag = File.file?(target) ? File.dirname(target) : target
+          has_collection = File.exist?(File.join(dir_for_flag, 'rbs_collection.lock.yaml')) || File.exist?('rbs_collection.lock.yaml')
+          flag = has_collection ? '--rbs-collection' : '--rbs'
+          extra = @extra_argv || []
+          filtered = extra.reject { |a| a == '--no-rbs' }
+          has_rbs_flag = extra.any? { |a| %w[--rbs --rbs-collection --no-rbs].include?(a) }
+          has_no_rbs = extra.include?('--no-rbs')
+          argv1 = ['-AkB']
+          argv1.concat(filtered)
+          if has_rbs_flag
+            argv1 << dir_for_flag unless has_no_rbs || argv1.include?(dir_for_flag)
+          else
+            argv1 << flag << dir_for_flag
+          end
+          puts "Pass 1: Aggressive rebuild with #{has_collection ? 'RBS collection' : 'RBS'}#{' + validate-types' if extra.include?('--validate-types')}..."
           options1 = Docscribe::CLI::Options.parse!(argv1)
-          Docscribe::CLI::Run.run(options: options1, argv: [dir])
+          Docscribe::CLI::Run.run(options: options1, argv: [target])
         end
 
         # @private
-        # @param [String] dir
+        # @param [String] target
         # @return [Integer]
-        def run_second_pass(dir)
-          puts 'Pass 2: Safe merge with RBS collection...'
-          argv2 = ['-aB', '--rbs-collection', dir]
+        def run_second_pass(target) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+          dir_for_flag = File.file?(target) ? File.dirname(target) : target
+          has_collection = File.exist?(File.join(dir_for_flag, 'rbs_collection.lock.yaml')) || File.exist?('rbs_collection.lock.yaml')
+          flag = has_collection ? '--rbs-collection' : '--rbs'
+          extra = @extra_argv || []
+          filtered = extra.reject { |a| a == '--no-rbs' }
+          has_rbs_flag = extra.any? { |a| %w[--rbs --rbs-collection --no-rbs].include?(a) }
+          has_no_rbs = extra.include?('--no-rbs')
+          argv2 = ['-aB']
+          argv2.concat(filtered)
+          if has_rbs_flag
+            argv2 << dir_for_flag unless has_no_rbs || argv2.include?(dir_for_flag)
+          else
+            argv2 << flag << dir_for_flag
+          end
+          puts "Pass 2: Safe merge with #{has_collection ? 'RBS collection' : 'RBS'}#{' + validate-types' if extra.include?('--validate-types')}..."
           options2 = Docscribe::CLI::Options.parse!(argv2)
-          Docscribe::CLI::Run.run(options: options2, argv: [dir])
+          Docscribe::CLI::Run.run(options: options2, argv: [target])
         end
 
         # @private

data/lib/docscribe/cli.rb

@@ -6,6 +6,24 @@ require 'docscribe/cli/run'
 module Docscribe
   # CLI entry point and command dispatch.
   module CLI
+    COMMANDS = {
+      'check_for_comments' => :CheckForComments,
+      'config' => :ConfigDump,
+      'coverage' => :Coverage,
+      'generate' => :Generate,
+      'init' => :Init,
+      'rbs' => :RbsGen,
+      'server' => :ServerCmd,
+      'sigs' => :Sigs,
+      'update_types' => :UpdateTypes
+    }.freeze
+
+    # Subcommands whose file name differs from the command name.
+    SUBCOMMAND_FILES = {
+      'config' => 'config_dump',
+      'rbs' => 'rbs_gen'
+    }.freeze
+
     class << self
       # @param [Array<String>] argv
       # @return [Integer]
@@ -17,18 +35,6 @@ module Docscribe
         Docscribe::CLI::Run.run(options: options, argv: argv)
       end
 
-      COMMANDS = {
-        'check_for_comments' => :CheckForComments,
-        'config' => :ConfigDump,
-        'coverage' => :Coverage,
-        'generate' => :Generate,
-        'init' => :Init,
-        'rbs' => :RbsGen,
-        'server' => :ServerCmd,
-        'sigs' => :Sigs,
-        'update_types' => :UpdateTypes
-      }.freeze
-
       private
 
       # @private
@@ -46,7 +52,7 @@ module Docscribe
         const_name = COMMANDS[cmd]
         return 0 unless const_name
 
-        require "docscribe/cli/#{cmd == 'rbs' ? 'rbs_gen' : cmd}"
+        require "docscribe/cli/#{SUBCOMMAND_FILES.fetch(cmd) { cmd }}"
         Docscribe::CLI.const_get(const_name).run(argv)
       end
     end

data/lib/docscribe/config/defaults.rb

@@ -75,6 +75,7 @@ module Docscribe
       },
       'keep_descriptions' => false,
       'skip_anonymous_block_params' => false,
+      'validate_types' => false,
       'plugins' => {
         'require' => [] #: Array[String]
       }

data/lib/docscribe/config/rbs.rb

@@ -107,10 +107,31 @@ module Docscribe
     # RBS environment errors (e.g. duplicate declarations against core
     # stdlib types) do not silence all RBS lookups.
     #
+    # When no explicit dirs are configured but `rbs.collection: true` is
+    # set, the lock file is auto-discovered (same as `--rbs-collection`),
+    # so plain `check` gets the full environment without extra flags.
+    #
     # @private
     # @return [Array<String>]
     def rbs_collection_dirs
-      Array(raw.dig('rbs', 'collection_dirs')).map(&:to_s) # steep:ignore
+      explicit = Array(raw.dig('rbs', 'collection_dirs')).map(&:to_s) # steep:ignore
+      return explicit unless explicit.empty?
+      return [] unless raw.dig('rbs', 'collection')
+
+      Array(discovered_collection_dir).compact
+    end
+
+    # Resolve the collection directory from rbs_collection.lock.yaml.
+    #
+    # @private
+    # @raise [LoadError]
+    # @return [String, nil] resolved directory or nil when no lock file
+    # @return [nil] if LoadError
+    def discovered_collection_dir
+      require 'docscribe/types/rbs/collection_loader'
+      Docscribe::Types::RBS::CollectionLoader.resolve
+    rescue LoadError
+      nil
     end
 
     # Whether generic RBS types should be collapsed to simpler container names.

data/lib/docscribe/config/template.rb

@@ -106,6 +106,9 @@ module Docscribe
         # Skip @param for anonymous block arguments (&) (Ruby 3.2+)
         skip_anonymous_block_params: false
 
+        # Validate YARD types against inferred/RBS types
+        validate_types: false
+
         plugins:
           # Load custom plugins
           # Example:

data/lib/docscribe/config/validation.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Docscribe
+  # Validation-related configuration.
+  class Config
+    # Whether to validate YARD types against inferred / external types.
+    #
+    # When enabled, `docscribe lib --validate-types` (or `validate_types: true`
+    # in `docscribe.yml`) compares each `@param`/`@return` type written in YARD
+    # against the type inferred from the method body or provided via RBS/Sorbet.
+    # Mismatches are reported as `updated_param` / `updated_return` and, in
+    # check mode, cause exit 1.
+    #
+    # @return [Boolean]
+    def validate_types?
+      fetch_bool(%w[validate_types], false)
+    end
+  end
+end

data/lib/docscribe/config.rb

@@ -49,3 +49,4 @@ require_relative 'config/rbs'
 require_relative 'config/sorting'
 require_relative 'config/sorbet'
 require_relative 'config/plugin'
+require_relative 'config/validation'

data/lib/docscribe/infer/behavior.rb

@@ -8,9 +8,9 @@ module Docscribe
                             insert update_all delete_all].freeze
 
       class << self
-        # @param [Object] body
-        # @param [Object] method_name
-        # @return [Hash<Symbol, Object>]
+        # @param [Parser::AST::Node, nil] body
+        # @param [Symbol?] method_name
+        # @return [Hash<Symbol, Boolean, String, nil>]
         def analyze(body, method_name)
           result = default_result(method_name)
 
@@ -20,8 +20,8 @@ module Docscribe
           result
         end
 
-        # @param [Object] method_name
-        # @return [Hash<Symbol, Object>]
+        # @param [Symbol?] method_name
+        # @return [Hash<Symbol, Boolean, String, nil>]
         def default_result(method_name)
           {
             predicate: method_name&.to_s&.end_with?('?') || false,
@@ -33,8 +33,8 @@ module Docscribe
           }
         end
 
-        # @param [Hash<Symbol, Object>] analysis
-        # @param [Object] _method_name
+        # @param [Hash<Symbol, Boolean, String, nil>] analysis
+        # @param [Symbol?] _method_name
         # @return [String?]
         def infer_description(analysis, _method_name)
           return nil unless analysis[:has_side_effects] || analysis[:predicate]
@@ -51,8 +51,8 @@ module Docscribe
         private
 
         # @private
-        # @param [Object] node
-        # @param [Hash<Symbol, Object>] result
+        # @param [Parser::AST::Node] node
+        # @param [Hash<Symbol, Boolean, String, nil>] result
         # @return [void]
         def analyze_body(node, result)
           case node.type
@@ -68,8 +68,8 @@ module Docscribe
         end
 
         # @private
-        # @param [Object] node
-        # @param [Hash<Symbol, Object>] result
+        # @param [Parser::AST::Node] node
+        # @param [Hash<Symbol, Boolean, String, nil>] result
         # @return [void]
         def recurse_children(node, result)
           node.children.each do |child|
@@ -78,8 +78,8 @@ module Docscribe
         end
 
         # @private
-        # @param [Object] node
-        # @param [Hash<Symbol, Object>] result
+        # @param [Parser::AST::Node] node
+        # @param [Hash<Symbol, Boolean, String, nil>] result
         # @return [void]
         def analyze_send(node, result)
           _receiver, method_name = *node

data/lib/docscribe/infer/params.rb

@@ -33,8 +33,8 @@ module Docscribe
       # @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?('&')
+        return 'Hash' if name.start_with?('**')
+        return 'Proc' if name.start_with?('&')
 
         nil
       end

data/lib/docscribe/infer/raises.rb

@@ -23,10 +23,9 @@ module Docscribe
         raises = [] #: Array[String]
 
         ASTWalk.walk(node) do |n|
-          case n.type
-          when :resbody
+          if n&.type == :resbody
             raises.concat(exception_names_from_rescue_list(n.children[0]))
-          when :send
+          elsif n&.type == :send
             collect_send_raise(raises, n)
           end
         end
@@ -45,9 +44,9 @@ module Docscribe
       # @param [Parser::AST::Node, nil] exc_list rescue exception list node
       # @return [Array<String>]
       def exception_names_from_rescue_list(exc_list)
-        if exc_list.nil?
-          [DEFAULT_ERROR]
-        elsif exc_list.type == :array
+        return [DEFAULT_ERROR] unless exc_list.is_a?(Parser::AST::Node)
+
+        if exc_list.type == :array
           exc_list.children.map { |e| Names.const_full_name(e) || DEFAULT_ERROR }
         else
           [Names.const_full_name(exc_list) || DEFAULT_ERROR]