docscribe 1.4.2 → 1.5.1

data/lib/docscribe/cli/server.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+module Docscribe
+  module CLI
+    # Handle the `docscribe server` subcommand.
+    module ServerCmd
+      BANNER = <<~TEXT
+        Usage: docscribe server <command> [options]
+
+        Commands:
+          start    Start the background daemon
+          stop     Stop the background daemon
+          status   Show daemon status
+
+        Options:
+          -C, --config <path>    Config file path (default: auto-detect)
+
+        Once the server is running, use `--server` with other commands:
+          docscribe --server check lib/
+          docscribe --server --autocorrect lib/
+      TEXT
+
+      class << self
+        # Run the server subcommand.
+        #
+        # @param [Array<String>] argv subcommand arguments
+        # @return [Integer] exit code
+        def run(argv)
+          config_path, cmd = parse_args(argv)
+          return warn(BANNER) || 1 unless cmd
+
+          case cmd
+          when 'start' then start_server(config_path)
+          when 'stop' then stop_server(config_path)
+          when 'status' then show_status(config_path)
+          else warn(usage) || 1
+          end
+        end
+
+        private
+
+        # @private
+        # @param [Array<String>] argv
+        # @return [(String?, String?)]
+        def parse_args(argv)
+          config_path = nil
+          rest = OptionParser.new do |opts|
+            opts.on('-C', '--config <path>', 'Config file path') { |v| config_path = v }
+          end.parse!(argv.dup)
+          [config_path, rest.first]
+        end
+
+        # Start the background daemon process.
+        #
+        # @private
+        # @param [String?] config_path optional config file path
+        # @return [Integer] exit code
+        def start_server(config_path = nil)
+          require 'docscribe/server'
+          return already_running(config_path) if Docscribe::Server.running?(config_path)
+
+          Docscribe::Server.ensure_running!(daemonize: true, config_path: config_path)
+          pid = Docscribe::Server.read_pid(config_path)
+          warn "Docscribe server started (pid #{pid})"
+          0
+        end
+
+        # @private
+        # @param [String?] config_path optional config file path
+        # @return [Integer]
+        def already_running(config_path = nil)
+          pid = Docscribe::Server.read_pid(config_path)
+          warn "Docscribe server already running (pid #{pid})"
+          0
+        end
+
+        # Stop the background daemon.
+        #
+        # @private
+        # @param [String?] config_path optional config file path
+        # @return [Integer] exit code
+        def stop_server(config_path = nil)
+          require 'docscribe/server'
+          alive = Docscribe::Server::Client.new(config_path: config_path).shutdown
+          warn(alive ? 'Docscribe server stopped' : 'Docscribe server is not running')
+          0
+        end
+
+        # Show the server status.
+        #
+        # @private
+        # @param [String?] config_path optional config file path
+        # @return [Integer] exit code
+        def show_status(config_path = nil)
+          require 'docscribe/server'
+          return warn('Docscribe server is not running') || 0 unless Docscribe::Server.running?(config_path)
+
+          info = Docscribe::Server::Client.new(config_path: config_path).ping
+          info ? show_status_from_ping(info) : show_status_fallback(config_path)
+          0
+        end
+
+        # @private
+        # @param [Hash<String, Object>] info ping response hash
+        # @return [void]
+        def show_status_from_ping(info)
+          pid = info.dig('result', 'pid')
+          version = info.dig('result', 'version')
+          uptime = info.dig('result', 'uptime')
+          sock = info.dig('result', 'socket_path')
+          warn "Docscribe server v#{version} is running (pid #{pid}, socket #{sock}, uptime #{uptime}s)"
+        end
+
+        # @private
+        # @param [String?] config_path
+        # @return [void]
+        def show_status_fallback(config_path)
+          pid = Docscribe::Server.read_pid(config_path)
+          sock = Docscribe::Server.socket_path(config_path)
+          warn "Docscribe server is running (pid #{pid}, socket #{sock})"
+        end
+
+        # Print usage information for the server subcommand.
+        #
+        # @private
+        # @return [String]
+        def usage
+          BANNER
+        end
+      end
+    end
+  end
+end

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]
+        # @return [nil] if Parser::SyntaxError
+        # @return [nil] 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?]
+        # @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>]
+        # @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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'docscribe/cli/init'
-require 'docscribe/cli/generate'
 require 'docscribe/cli/options'
 require 'docscribe/cli/run'
 
@@ -9,15 +7,8 @@ module Docscribe
   # CLI entry point and command dispatch.
   module CLI
     class << self
-      # Main CLI entry point.
-      #
-      # Dispatches:
-      # - `docscribe init ...`     to the config-template generator
-      # - `docscribe generate ...` to the plugin skeleton generator
-      # - all other commands to the main option parser and runner
-      #
-      # @param [Array<String>] argv raw command-line arguments
-      # @return [Integer] process exit code
+      # @param [Array<String>] argv
+      # @return [Integer]
       def run(argv)
         argv = argv.dup
         return dispatch_subcommand(argv) if subcommand?(argv.first)
@@ -26,29 +17,35 @@ module Docscribe
         Docscribe::CLI::Run.run(options: options, argv: argv)
       end
 
+      COMMANDS = {
+        'init' => :Init,
+        'generate' => :Generate,
+        'sigs' => :Sigs,
+        'rbs' => :RbsGen,
+        'update_types' => :UpdateTypes,
+        'check_for_comments' => :CheckForComments,
+        'server' => :ServerCmd
+      }.freeze
+
       private
 
       # @private
-      # @param [String] cmd
+      # @param [String?] cmd
       # @return [Boolean]
       def subcommand?(cmd)
-        %w[init generate].include?(cmd)
+        COMMANDS.key?(cmd)
       end
 
       # @private
       # @param [Array<String>] argv
-      # @return [Integer, nil]
+      # @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
-        end
+        cmd = argv.shift
+        const_name = COMMANDS[cmd]
+        return 0 unless const_name
+
+        require "docscribe/cli/#{cmd == 'rbs' ? 'rbs_gen' : cmd}"
+        Docscribe::CLI.const_get(const_name).run(argv)
       end
     end
   end

data/lib/docscribe/config/defaults.rb

@@ -63,13 +63,18 @@ 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
+        'collapse_generics' => false,
+        'collapse_object_generics' => false
       },
+      'keep_descriptions' => false,
+      'skip_anonymous_block_params' => false,
       'plugins' => {
         'require' => [] #: Array[String]
       }