docscribe 1.4.1 → 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,8 +4,13 @@ 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.
   module CLI
     class << self
       # Main CLI entry point.
@@ -19,19 +24,40 @@ module Docscribe
       # @return [Integer] process exit code
       def run(argv)
         argv = argv.dup
-
-        case argv.first
-        when 'init'
-          argv.shift
-          return Docscribe::CLI::Init.run(argv)
-        when 'generate'
-          argv.shift
-          return Docscribe::CLI::Generate.run(argv)
-        end
+        return dispatch_subcommand(argv) if subcommand?(argv.first)
 
         options = Docscribe::CLI::Options.parse!(argv)
         Docscribe::CLI::Run.run(options: options, argv: argv)
       end
+
+      private
+
+      # Subcommand
+      #
+      # @private
+      # @param [String?] cmd potential subcommand name
+      # @return [Boolean]
+      def subcommand?(cmd)
+        %w[init generate sigs rbs update_types check_for_comments].include?(cmd)
+      end
+
+      # Dispatch subcommand
+      #
+      # @private
+      # @param [Array<String>] argv raw command-line arguments
+      # @return [Integer]
+      def dispatch_subcommand(argv)
+        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
   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,16 +62,20 @@ module Docscribe
         'enabled' => false,
         'collection' => false,
         'sig_dirs' => ['sig'],
-        'collection_dirs' => [],
-        'collapse_generics' => false
+        'collection_dirs' => [], #: Array[String]
+        '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' => []
+        '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
@@ -138,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