docscribe 1.4.2 → 1.5.0

data/lib/docscribe/cli/sigs.rb

@@ -0,0 +1,366 @@
+# frozen_string_literal: true
+
+require 'optparse'
+require 'docscribe/parsing'
+require 'docscribe/types/rbs/provider'
+
+module Docscribe
+  module CLI
+    # Check RBS signature coverage for Ruby source files.
+    #
+    # Usage:
+    #   docscribe sigs [options] [files...]
+    #
+    # Parses Ruby source files, extracts method definitions, and checks
+    # each method against the configured RBS signature directories.
+    # Reports methods that lack RBS type signatures.
+    module Sigs
+      BANNER = <<~TEXT
+        Usage: docscribe sigs [options] [files...]
+
+        Check RBS signature coverage for Ruby source files.
+
+      TEXT
+
+      EXIT_CODES = "\nExit codes:\n    " \
+                   "0 - all methods have signatures\n    " \
+                   "1 - some methods lack signatures\n    " \
+                   '2 - error occurred'
+
+      # @!attribute [rw] name
+      #   @return [Symbol]
+      #   @param [Symbol] value
+      #
+      # @!attribute [rw] scope
+      #   @return [Symbol]
+      #   @param [Symbol] value
+      #
+      # @!attribute [rw] container
+      #   @return [String?]
+      #   @param [String?] value
+      #
+      # @!attribute [rw] file
+      #   @return [String]
+      #   @param [String] value
+      #
+      # @!attribute [rw] line
+      #   @return [Integer]
+      #   @param [Integer] value
+      MethodDef = Struct.new(:name, :scope, :container, :file, :line, keyword_init: true)
+
+      class << self
+        # @param [Array<String>] argv
+        # @return [Integer]
+        def run(argv)
+          warn_ruby_version
+          options = parse_options(argv)
+          paths = expand_paths(argv)
+          return no_files_found if paths.empty?
+
+          run_with(options, extract_methods(paths))
+        end
+
+        private
+
+        # @private
+        # @return [void]
+        def warn_ruby_version
+          return unless Gem::Version.new(RUBY_VERSION) < Gem::Version.new('3.0')
+
+          warn 'Warning: docscribe sigs requires Ruby 3.0+ for RBS support. ' \
+               "You are running Ruby #{RUBY_VERSION}."
+        end
+
+        # @private
+        # @param [Array<String>] argv
+        # @return [Hash<Symbol, Object>]
+        def parse_options(argv)
+          options = { sig_dirs: ['sig'], rbs_collection: false, verbose: false }
+
+          parser = OptionParser.new do |opts|
+            opts.banner = BANNER
+            register_sig_options(opts, options)
+          end
+
+          parser.parse!(argv)
+          options
+        end
+
+        # @private
+        # @param [OptionParser] opts
+        # @param [Hash<Symbol, Object>] options
+        # @return [void]
+        def register_sig_options(opts, options)
+          opts.on('-s', '--sig-dir DIR', 'Add RBS signature directory (repeatable)') { |d| options[:sig_dirs] << d }
+          opts.on('--rbs-collection', 'Use RBS collection') { options[:rbs_collection] = true }
+          opts.on('--verbose', 'Print methods that have signatures too') { options[:verbose] = true }
+          opts.on('-h', '--help', 'Show this help') do
+            puts opts, EXIT_CODES
+            exit 0
+          end
+        end
+
+        # @private
+        # @param [Array<String>] args
+        # @return [Array<String>]
+        def expand_paths(args)
+          files = [] #: Array[String]
+          args = ['.'] if args.empty?
+          args.each { |path| expand_single_path(files, path) }
+          files.uniq.sort
+        end
+
+        # @private
+        # @param [Array<String>] files
+        # @param [String] path
+        # @return [void]
+        def expand_single_path(files, path)
+          if File.directory?(path)
+            files.concat(Dir.glob(File.join(path, '**', '*.rb')))
+          elsif File.file?(path)
+            files << path
+          else
+            warn "Skipping missing path: #{path}"
+          end
+        end
+
+        # @private
+        # @return [Integer]
+        def no_files_found
+          warn 'No files found. Pass files or directories (e.g. `docscribe sigs lib`).'
+          2
+        end
+
+        # @private
+        # @param [Hash<Symbol, Object>] options
+        # @param [Array<Docscribe::CLI::Sigs::MethodDef>] methods
+        # @return [Integer]
+        def run_with(options, methods)
+          return 0 if methods.empty?
+
+          provider = build_provider(options)
+          return 2 unless provider
+
+          missing = check_sigs(methods, provider, verbose: options[:verbose])
+          report_results(methods, missing)
+          missing.empty? ? 0 : 1
+        end
+
+        # @private
+        # @param [Array<String>] paths
+        # @return [Array<Docscribe::CLI::Sigs::MethodDef>]
+        def extract_methods(paths)
+          methods = [] #: Array[MethodDef]
+          paths.each { |path| extract_methods_from_file(path, methods) }
+          methods
+        end
+
+        # @private
+        # @param [String] path
+        # @param [Array<Docscribe::CLI::Sigs::MethodDef>] methods
+        # @raise [Parser::SyntaxError]
+        # @raise [StandardError]
+        # @return [void] if StandardError
+        # @return [Object] if Parser::SyntaxError
+        # @return [Object] if StandardError
+        def extract_methods_from_file(path, methods)
+          src = File.read(path)
+          ast = Docscribe::Parsing.parse(src, file: path)
+          return unless ast
+
+          walk_for_methods(ast, [], methods, path)
+        rescue Parser::SyntaxError => e # steep:ignore
+          warn "Syntax error in #{path}: #{e.message}"
+        rescue StandardError => e
+          warn "Error parsing #{path}: #{e.class}: #{e.message}"
+        end
+
+        # @private
+        # @param [Parser::AST::Node] node
+        # @param [Array<String>] containers
+        # @param [Array<Docscribe::CLI::Sigs::MethodDef>] methods
+        # @param [String] path
+        # @param [Boolean] inside_sclass
+        # @return [void]
+        def walk_for_methods(node, containers, methods, path, inside_sclass: false)
+          return unless node.is_a?(Parser::AST::Node)
+
+          case node.type
+          when :class, :module then walk_class_module(node, containers, methods, path)
+          when :sclass then walk_sclass(node, containers, methods, path)
+          when :def then collect_def(node, containers, methods, path, inside_sclass: inside_sclass)
+          when :defs then collect_defs(node, containers, methods, path)
+          else walk_children(node, containers, methods, path, inside_sclass: inside_sclass)
+          end
+        end
+
+        # @private
+        # @param [Parser::AST::Node] node
+        # @param [Array<String>] containers
+        # @param [Array<Docscribe::CLI::Sigs::MethodDef>] methods
+        # @param [String] path
+        # @return [void]
+        def walk_class_module(node, containers, methods, path)
+          containers.push(const_name(node.children[0]))
+          node.children.drop(1).each { |c| walk_for_methods(c, containers, methods, path) }
+          containers.pop
+        end
+
+        # @private
+        # @param [Parser::AST::Node] node
+        # @param [Array<String>] containers
+        # @param [Array<Docscribe::CLI::Sigs::MethodDef>] methods
+        # @param [String] path
+        # @return [void]
+        def walk_sclass(node, containers, methods, path)
+          node.children.drop(1).each { |c| walk_for_methods(c, containers, methods, path, inside_sclass: true) }
+        end
+
+        # @private
+        # @param [Parser::AST::Node] node
+        # @param [Array<String>] containers
+        # @param [Array<Docscribe::CLI::Sigs::MethodDef>] methods
+        # @param [String] path
+        # @param [Boolean] inside_sclass
+        # @return [void]
+        def walk_children(node, containers, methods, path, inside_sclass: false)
+          node.children.each { |c| walk_for_methods(c, containers, methods, path, inside_sclass: inside_sclass) }
+        end
+
+        # @private
+        # @param [Parser::AST::Node] node
+        # @param [Array<String>] containers
+        # @param [Array<Docscribe::CLI::Sigs::MethodDef>] methods
+        # @param [String] path
+        # @param [Boolean] inside_sclass
+        # @return [void]
+        def collect_def(node, containers, methods, path, inside_sclass: false)
+          methods << MethodDef.new(
+            name: node.children[0],
+            scope: inside_sclass ? :class : :instance,
+            container: container_name(containers),
+            file: path,
+            line: node.loc&.line || 1
+          )
+        end
+
+        # @private
+        # @param [Parser::AST::Node] node
+        # @param [Array<String>] containers
+        # @param [Array<Docscribe::CLI::Sigs::MethodDef>] methods
+        # @param [String] path
+        # @return [void]
+        def collect_defs(node, containers, methods, path)
+          methods << MethodDef.new(
+            name: node.children[1],
+            scope: :class,
+            container: container_name(containers),
+            file: path,
+            line: node.loc&.line || 1
+          )
+        end
+
+        # @private
+        # @param [Array<String>] containers
+        # @return [String?]
+        def container_name(containers)
+          containers.empty? ? nil : containers.join('::')
+        end
+
+        # @private
+        # @param [Parser::AST::Node] node
+        # @return [String]
+        def const_name(node)
+          return node.to_s unless node.is_a?(Parser::AST::Node)
+          return node.children[1].to_s if node.type == :const
+
+          node.children.map { |c| c.is_a?(Parser::AST::Node) ? const_name(c) : c.to_s }.join('::')
+        end
+
+        # @private
+        # @param [Hash<Symbol, Object>] options
+        # @raise [LoadError]
+        # @raise [StandardError]
+        # @return [Docscribe::Types::RBS::Provider?] if StandardError
+        # @return [nil] if LoadError
+        # @return [nil] if StandardError
+        def build_provider(options)
+          dirs = options[:rbs_collection] ? load_collection_dirs : [] #: Array[String]
+          Docscribe::Types::RBS::Provider.new(sig_dirs: options[:sig_dirs], collection_dirs: dirs)
+        rescue LoadError
+          warn 'Docscribe: rbs gem is not installed. Add `gem "rbs"` to your Gemfile ' \
+               'or run `bundle exec rbs collection install`.'
+          nil
+        rescue StandardError => e
+          warn "Docscribe: Failed to initialize RBS provider: #{e.class}: #{e.message}"
+          nil
+        end
+
+        # @private
+        # @raise [StandardError]
+        # @return [Array<String>] if StandardError
+        # @return [Array] if StandardError
+        def load_collection_dirs
+          dir = Docscribe::Types::RBS::CollectionLoader.resolve
+          dir ? [dir] : []
+        rescue StandardError => e
+          warn "Docscribe: Failed to load RBS collection: #{e.class}: #{e.message}"
+          []
+        end
+
+        # @private
+        # @param [Array<Docscribe::CLI::Sigs::MethodDef>] methods
+        # @param [Docscribe::Types::RBS::Provider] provider
+        # @param [Boolean] verbose
+        # @return [Array<Docscribe::CLI::Sigs::MethodDef>]
+        def check_sigs(methods, provider, verbose:)
+          missing = [] #: Array[MethodDef]
+          methods.each do |m|
+            sig = lookup_signature(m, provider)
+            puts "  OK  #{format_method(m)} (#{m.file}:#{m.line})" if sig && verbose
+            puts "  MISS #{format_method(m)} (#{m.file}:#{m.line})" unless sig
+            missing << m unless sig
+          end
+          missing
+        end
+
+        # @private
+        # @param [Docscribe::CLI::Sigs::MethodDef] method_def
+        # @param [Docscribe::Types::RBS::Provider] provider
+        # @return [Object, nil]
+        def lookup_signature(method_def, provider)
+          container = method_def.container
+          return nil unless container
+
+          provider.signature_for(
+            container: container,
+            scope: method_def.scope,
+            name: method_def.name
+          )
+        end
+
+        # @private
+        # @param [Docscribe::CLI::Sigs::MethodDef] method_def
+        # @return [String]
+        def format_method(method_def)
+          prefix = method_def.scope == :class ? 'self.' : ''
+          container = method_def.container ? "#{method_def.container}#" : ''
+          "#{container}#{prefix}#{method_def.name}"
+        end
+
+        # @private
+        # @param [Array<Docscribe::CLI::Sigs::MethodDef>] methods
+        # @param [Array<Docscribe::CLI::Sigs::MethodDef>] missing
+        # @return [void]
+        def report_results(methods, missing)
+          puts
+          if missing.empty?
+            puts "Docscribe: All #{methods.size} methods have RBS signatures"
+          else
+            puts "Docscribe: #{missing.size}/#{methods.size} methods missing RBS signatures"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/docscribe/cli/update_types.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+require 'docscribe/cli/options'
+require 'docscribe/cli/run'
+
+module Docscribe
+  module CLI
+    # Two-pass update: rebuild docs then re-merge with RBS types.
+    #
+    # Usage:
+    #   docscribe update_types [directory]
+    #
+    # Pass 1: `-AkB --rbs-collection <dir>` — aggressive rebuild, keep descriptions,
+    #   no boilerplate, using RBS collection signatures.
+    # Pass 2: `-aB --rbs-collection <dir>` — safe merge cleanup, no boilerplate,
+    #   using RBS collection signatures.
+    module UpdateTypes
+      BANNER = <<~TEXT
+        Usage: docscribe update_types [directory]
+
+        Two-pass type-aware documentation update.
+
+        Pass 1 (aggressive):  docscribe -AkB --rbs-collection <dir>
+          rebuild doc blocks, keep descriptions, no boilerplate
+
+        Pass 2 (safe):        docscribe -aB --rbs-collection <dir>
+          safe merge cleanup, no boilerplate
+
+      TEXT
+
+      class << self
+        # @param [Array<String>] argv
+        # @return [Integer]
+        def run(argv)
+          options = parse_options(argv)
+          dir = options[:dir]
+
+          announce_start
+
+          exit1 = run_first_pass(dir)
+          return exit1 unless exit1.zero?
+
+          exit2 = run_second_pass(dir)
+          return exit2 unless exit2.zero?
+
+          announce_complete
+          0
+        end
+
+        private
+
+        # @private
+        # @param [Array<String>] argv
+        # @return [Hash<Symbol, Object>]
+        def parse_options(argv)
+          options = { dir: '.' }
+          OptionParser.new(BANNER) do |opts|
+            opts.on('-h', '--help', 'Show this help') { puts opts or exit 0 }
+            opts.parse!(argv)
+          end
+          options[:dir] = argv.first if argv.any?
+          options
+        end
+
+        # @private
+        # @return [void]
+        def announce_start
+          puts 'Docscribe: Running type-aware documentation update...'
+          puts
+        end
+
+        # @private
+        # @param [String] dir
+        # @return [Integer]
+        def run_first_pass(dir)
+          puts 'Pass 1: Aggressive rebuild with RBS collection...'
+          argv1 = ['-AkB', '--rbs-collection', dir]
+          options1 = Docscribe::CLI::Options.parse!(argv1)
+          Docscribe::CLI::Run.run(options: options1, argv: [dir])
+        end
+
+        # @private
+        # @param [String] dir
+        # @return [Integer]
+        def run_second_pass(dir)
+          puts 'Pass 2: Safe merge with RBS collection...'
+          argv2 = ['-aB', '--rbs-collection', dir]
+          options2 = Docscribe::CLI::Options.parse!(argv2)
+          Docscribe::CLI::Run.run(options: options2, argv: [dir])
+        end
+
+        # @private
+        # @return [void]
+        def announce_complete
+          puts
+          puts 'Docscribe: Type-aware documentation update complete.'
+        end
+      end
+    end
+  end
+end

data/lib/docscribe/cli.rb

@@ -4,6 +4,10 @@ require 'docscribe/cli/init'
 require 'docscribe/cli/generate'
 require 'docscribe/cli/options'
 require 'docscribe/cli/run'
+require 'docscribe/cli/sigs'
+require 'docscribe/cli/rbs_gen'
+require 'docscribe/cli/update_types'
+require 'docscribe/cli/check_for_comments'
 
 module Docscribe
   # CLI entry point and command dispatch.
@@ -28,26 +32,30 @@ module Docscribe
 
       private
 
+      # Subcommand
+      #
       # @private
-      # @param [String] cmd
+      # @param [String?] cmd potential subcommand name
       # @return [Boolean]
       def subcommand?(cmd)
-        %w[init generate].include?(cmd)
+        %w[init generate sigs rbs update_types check_for_comments].include?(cmd)
       end
 
+      # Dispatch subcommand
+      #
       # @private
-      # @param [Array<String>] argv
-      # @return [Integer, nil]
+      # @param [Array<String>] argv raw command-line arguments
+      # @return [Integer]
       def dispatch_subcommand(argv)
-        case argv.first
-        when 'init'
-          argv.shift
-          Docscribe::CLI::Init.run(argv)
-        when 'generate'
-          argv.shift
-          Docscribe::CLI::Generate.run(argv)
-        else
-          0
+        cmd = argv.shift
+        case cmd
+        when 'init' then Docscribe::CLI::Init.run(argv)
+        when 'generate' then Docscribe::CLI::Generate.run(argv)
+        when 'sigs' then Docscribe::CLI::Sigs.run(argv)
+        when 'rbs' then Docscribe::CLI::RbsGen.run(argv)
+        when 'update_types' then Docscribe::CLI::UpdateTypes.run(argv)
+        when 'check_for_comments' then Docscribe::CLI::CheckForComments.run(argv)
+        else 0
         end
       end
     end

data/lib/docscribe/config/defaults.rb

@@ -63,13 +63,17 @@ module Docscribe
         'collection' => false,
         'sig_dirs' => ['sig'],
         'collection_dirs' => [], #: Array[String]
-        'collapse_generics' => false
+        'collapse_generics' => false,
+        'warn_missing_collection' => true,
+        'collapse_object_generics' => false
       },
       'sorbet' => {
         'enabled' => false,
         'rbi_dirs' => ['sorbet/rbi', 'rbi'],
         'collapse_generics' => false
       },
+      'keep_descriptions' => false,
+      'skip_anonymous_block_params' => false,
       'plugins' => {
         'require' => [] #: Array[String]
       }

data/lib/docscribe/config/emit.rb

@@ -139,5 +139,22 @@ module Docscribe
     def include_param_documentation?
       fetch_bool(%w[emit include_param_documentation], true)
     end
+
+    # Whether to preserve existing @param/@return descriptions in aggressive mode.
+    #
+    # @return [Boolean]
+    def keep_descriptions?
+      fetch_bool(%w[keep_descriptions], false)
+    end
+
+    # Whether to skip @param generation for anonymous block arguments (&).
+    #
+    # Ruby 3.2+ allows `def foo(&)`. When enabled, no @param is generated
+    # for anonymous block parameters since they have no name to reference.
+    #
+    # @return [Boolean]
+    def skip_anonymous_block_params?
+      fetch_bool(%w[skip_anonymous_block_params], false)
+    end
   end
 end

data/lib/docscribe/config/filtering.rb

@@ -9,7 +9,6 @@ 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)
       include_patterns, exclude_patterns = load_file_patterns
@@ -23,8 +22,7 @@ module Docscribe
 
     # Load normalized file include/exclude patterns from config.
     #
-    # @private
-    # @return [Array(Array<String>, Array<String>)] include_patterns, exclude_patterns
+    # @return [(Array<String>, Array<String>)]
     def load_file_patterns
       files = raw.dig('filter', 'files') || {}
       [normalize_file_patterns(files['include']), normalize_file_patterns(files['exclude'])]
@@ -32,10 +30,10 @@ module Docscribe
 
     # Compute the relative path for filtering.
     #
-    # @private
-    # @param [String] path
+    # @param [String] path file path to test
     # @raise [StandardError]
-    # @return [String]
+    # @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
@@ -76,8 +74,7 @@ module Docscribe
     # - 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
@@ -89,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
@@ -106,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) }
@@ -121,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]
@@ -140,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