docscribe 1.6.1 → 1.6.2

data/lib/docscribe/plugin/registry.rb

@@ -132,6 +132,7 @@ module Docscribe
         @tag_entries.clear
         @collector_entries.clear
         @order_seq = 0
+        nil
       end
     end
   end

data/lib/docscribe/server/base.rb

@@ -27,7 +27,7 @@ module Docscribe
     class << self
       # Start the server daemon if not running.
       #
-      # @param [String, nil] config_path optional config file path
+      # @param [String?] config_path optional config file path
       # @param [Boolean] daemonize redirect stdin/stdout/stderr to /dev/null
       # @param [Integer] timeout max seconds to wait for readiness
       # @return [void]
@@ -48,7 +48,7 @@ module Docscribe
 
       # Start the server daemon and wait for it to become ready.
       #
-      # @param [String, nil] config_path optional config path for socket/pid lookup
+      # @param [String?] config_path optional config path for socket/pid lookup
       # @param [Integer] timeout max seconds to wait for readiness
       # @param [Boolean] raise_on_timeout
       # @raise [StandardError]
@@ -75,7 +75,7 @@ module Docscribe
       # if yes, the daemon is still starting up (don't clean up);
       # if no, removes stale socket and pid files.
       #
-      # @param [String, nil] config_path optional config path for socket lookup
+      # @param [String?] config_path optional config path for socket lookup
       # @raise [Errno::ECONNREFUSED]
       # @raise [Errno::ENOENT]
       # @raise [Errno::ENOTSOCK]
@@ -101,7 +101,7 @@ module Docscribe
       # Handle ECONNREFUSED: check if the pid process is alive.
       # Cleans up only if the process is dead.
       #
-      # @param [String, nil] config_path
+      # @param [String?] config_path
       # @return [Boolean] false (not running)
       def handle_stale_socket?(config_path)
         pid = read_pid(config_path)
@@ -122,9 +122,9 @@ module Docscribe
         false
       end
 
-      # @param [String, nil] config_path
+      # @param [String?] config_path
       # @raise [StandardError]
-      # @return [Integer, nil]
+      # @return [Integer?]
       # @return [nil] if StandardError
       def read_pid(config_path = nil)
         File.read(pid_path(config_path)).to_i if File.exist?(pid_path(config_path))
@@ -134,20 +134,21 @@ module Docscribe
 
       # Remove stale socket and pid files.
       #
-      # @param [String, nil] config_path
+      # @param [String?] config_path
       # @return [void]
       def clean_socket_files(config_path)
         FileUtils.rm_f(socket_path(config_path))
         FileUtils.rm_f(pid_path(config_path))
       end
 
-      # @param [String, nil] config_path
+      # @param [String?] config_path
       # @return [String]
       def pid_path(config_path = nil)
         "#{socket_path(config_path)}.pid"
       end
 
-      ENV_FILES = %w[Gemfile.lock rbs_collection.lock.yaml].freeze
+      ENV_FILES = %w[Gemfile.lock rbs_collection.lock.yaml docscribe.yml].freeze
+      SIG_RBS_GLOB = 'sig/**/*.rbs'
 
       # @param [String] config_path
       # @return [String]
@@ -180,7 +181,7 @@ module Docscribe
       # Environment files (Gemfile.lock, rbs_collection.lock.yaml) are also
       # included so daemon is invalidated when gems or RBS types change.
       #
-      # @param [String, nil] config_path optional config path to differentiate
+      # @param [String?] config_path optional config path to differentiate
       # @return [String]
       def socket_path(config_path = nil)
         seed = +Dir.pwd
@@ -195,19 +196,49 @@ module Docscribe
 
       # Hash of environment files that affect analysis results.
       # When any of these change, the daemon is invalidated (new socket path).
+      # Includes Gemfile.lock, rbs_collection.lock.yaml, docscribe.yml and all sig/**/*.rbs.
       #
       # @return [String]
       def env_hash
-        parts = ENV_FILES.map do |file|
-          path = File.join(Dir.pwd, file)
-          File.exist?(path) ? File.mtime(path).to_f.to_s : '0'
-        end
+        parts = ENV_FILES.map { |file| env_file_mtime(file) }
+        parts.concat(sig_env_parts)
         Digest::MD5.hexdigest(parts.join(':'))
       end
 
+      # Hash of RBS signature files for cache invalidation inside daemon.
+      # Used by Daemon#rewrite_file to detect sig changes without requiring a new socket.
+      #
+      # @return [String]
+      def sig_hash
+        files = sig_files
+        parts = files.map { |p| "#{p}:#{File.mtime(p).to_f}" }
+        parts << "count:#{files.size}"
+        Digest::MD5.hexdigest(parts.join('|'))
+      end
+
+      # @param [String] file
+      # @return [String]
+      def env_file_mtime(file)
+        path = File.join(Dir.pwd, file)
+        File.exist?(path) ? File.mtime(path).to_f.to_s : '0'
+      end
+
+      # @return [Array<String>]
+      def sig_env_parts
+        files = sig_files
+        mtimes = files.map { |p| File.mtime(p).to_f.to_s }
+        mtimes << files.size.to_s
+        mtimes
+      end
+
+      # @return [Array<String>]
+      def sig_files
+        Dir.glob(File.join(Dir.pwd, SIG_RBS_GLOB)).sort
+      end
+
       public :read_pid, :pid_path, :socket_path
 
-      # @param [String, nil] config_path
+      # @param [String?] config_path
       # @param [Boolean] daemonize
       # @return [void]
       def start_daemon_process(config_path:, daemonize:)

data/lib/docscribe/server/client.rb

@@ -6,8 +6,8 @@ module Docscribe
   module Server
     # Client for communicating with a running Docscribe daemon.
     class Client
-      # @param [String, nil] socket_path custom socket path (defaults to server default)
-      # @param [String, nil] config_path optional config path for socket lookup
+      # @param [String?] socket_path custom socket path (defaults to server default)
+      # @param [String?] config_path optional config path for socket lookup
       # @return [void]
       def initialize(socket_path = nil, config_path: nil)
         @socket_path = socket_path || Server.socket_path(config_path)
@@ -17,8 +17,8 @@ module Docscribe
       #
       # @param [String] file path to file to check
       # @param [Symbol] strategy rewrite strategy (:safe, :aggressive)
-      # @param [Hash<Symbol, Object>] rest extra JSON-RPC params (e.g. cli_overrides)
-      # @return [Hash<String, Object>, nil] response hash or nil if server unreachable
+      # @param [Object] rest extra JSON-RPC params (e.g. cli_overrides)
+      # @return [Hash<String, Object>?] response hash or nil if server unreachable
       def check(file:, strategy: :safe, **rest)
         request('check', file: file, strategy: strategy, **rest)
       end
@@ -27,22 +27,31 @@ module Docscribe
       #
       # @param [String] file path to file to fix
       # @param [Symbol] strategy rewrite strategy (:safe, :aggressive)
-      # @param [Hash<Symbol, Object>] rest extra JSON-RPC params (e.g. cli_overrides)
-      # @return [Hash<String, Object>, nil] response hash or nil if server unreachable
+      # @param [Object] rest extra JSON-RPC params (e.g. cli_overrides)
+      # @return [Hash<String, Object>?] response hash or nil if server unreachable
       def fix(file:, strategy: :safe, **rest)
         request('fix', file: file, strategy: strategy, **rest)
       end
 
       # Send a shutdown request to the server.
       #
-      # @return [Hash<String, Object>, nil] response hash or nil if server unreachable
+      # @return [Hash<String, Object>?] response hash or nil if server unreachable
       def shutdown
         request('shutdown')
       end
 
+      # Send an update_types request to the server.
+      #
+      # @param [String] dir directory to update (defaults to '.')
+      # @param [Object] rest extra JSON-RPC params (e.g. cli_overrides)
+      # @return [Hash<String, Object>?] response hash or nil if server unreachable
+      def update_types(dir: '.', **rest)
+        request('update_types', dir: dir, **rest)
+      end
+
       # Ping the server and get version/pid/uptime info.
       #
-      # @return [Hash<String, Object>, nil] response hash or nil if server unreachable
+      # @return [Hash<String, Object>?] response hash or nil if server unreachable
       def ping
         request('ping')
       end
@@ -53,8 +62,8 @@ module Docscribe
       #
       # @private
       # @param [String] method method name
-      # @param [Hash<Symbol, Object>] params request parameters
-      # @return [Hash<String, Object>, nil]
+      # @param [Object] params request parameters
+      # @return [Hash<String, Object>?]
       def request(method, **params)
         connect do |socket|
           req = Protocol.build_request(method, params)
@@ -72,7 +81,7 @@ module Docscribe
       # @private
       # @raise [Errno::ECONNREFUSED]
       # @raise [Errno::ENOENT]
-      # @return [T, nil] yield return value or nil on connection error
+      # @return [U?] yield return value or nil on connection error
       def connect
         socket = UNIXSocket.new(@socket_path)
         yield socket

data/lib/docscribe/server/daemon.rb

@@ -4,6 +4,7 @@ require 'socket'
 require 'fileutils'
 require 'time'
 require 'timeout'
+require 'digest/md5'
 require_relative '../lru_cache'
 
 module Docscribe
@@ -18,19 +19,46 @@ module Docscribe
         timeout: -32_010,
         internal: -32_099
       }.freeze
-      # @param [String, nil] socket_path custom socket path
+
+      REQUEST_HANDLERS = {
+        'check' => :handle_check,
+        'fix' => :handle_fix,
+        'check_batch' => :handle_check_batch,
+        'update_types' => :handle_update_types
+      }.freeze
+
+      # @param [String?] socket_path custom socket path
       # @param [Integer] idle_timeout seconds before automatic shutdown
-      # @param [String, nil] config_path custom config path
+      # @param [String?] config_path custom config path
       # @return [void]
       def initialize(socket_path: nil, idle_timeout: IDLE_TIMEOUT, config_path: nil)
+        setup_socket_config(socket_path, config_path, idle_timeout)
+        setup_runtime_state
+        setup_caches
+      end
+
+      # @param [String?] socket_path
+      # @param [String?] config_path
+      # @param [Integer] idle_timeout
+      # @return [void]
+      def setup_socket_config(socket_path, config_path, idle_timeout)
         @socket_path = socket_path || Server.socket_path(config_path)
-        @idle_timeout = idle_timeout
         @config_path = config_path
+        @idle_timeout = idle_timeout
+      end
+
+      # @return [void]
+      def setup_runtime_state
         @last_request_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         @running = false
         @server = nil
-        @file_cache = LRUCache.new
         @started_at = Time.now
+        @last_sig_hash = nil
+      end
+
+      # @return [void]
+      def setup_caches
+        @file_cache = LRUCache.new
         @cache_mutex = Mutex.new
         @config_mutex = Mutex.new
       end
@@ -143,11 +171,29 @@ module Docscribe
       def handle_request(client, request)
         method = request['method']
         params = request['params'] || {}
+        dispatch_request(client, request, method, params)
+      end
+
+      # @private
+      # @param [UNIXSocket] client
+      # @param [Hash<String, Object>] request
+      # @param [String] method
+      # @param [Hash<String, Object>] params
+      # @return [void]
+      def dispatch_request(client, request, method, params)
+        handler = REQUEST_HANDLERS[method]
+        return send(handler, client, request['id'], params) if handler
 
+        dispatch_control_request(client, request, method)
+      end
+
+      # @private
+      # @param [UNIXSocket] client
+      # @param [Hash<String, Object>] request
+      # @param [String] method
+      # @return [void]
+      def dispatch_control_request(client, request, method)
         case method
-        when 'check' then handle_check(client, request['id'], params)
-        when 'fix' then handle_fix(client, request['id'], params)
-        when 'check_batch' then handle_check_batch(client, request['id'], params)
         when 'shutdown' then handle_shutdown(client, request['id'])
         when 'ping' then handle_ping(client, request['id'])
         else send_error(client, request['id'], -32_601, "Unknown method: #{method}")
@@ -219,7 +265,7 @@ module Docscribe
       # @private
       # @param [String] file
       # @param [Symbol] strategy
-      # @param [Integer, Float, nil] timeout
+      # @param [Integer, Float?] timeout
       # @raise [Timeout::Error]
       # @raise [StandardError]
       # @return [Hash<String, Object>]
@@ -245,13 +291,14 @@ module Docscribe
       # @return [Hash<String, Object>]
       def run_rewrite(file, strategy)
         src, result = rewrite_file(file, strategy)
-        { 'file' => file, 'status' => result[:output] == src ? 'ok' : 'fail', 'changes' => result[:changes] }
+        changes = result[:changes].map { |c| c.transform_keys(&:to_s) }
+        { 'file' => file, 'status' => result[:output] == src ? 'ok' : 'fail', 'changes' => changes }
       end
 
       # @private
-      # @param [Hash<String, Object>, nil] overrides
+      # @param [Hash<String, Object>?] overrides
       # @return [void]
-      def apply_cli_overrides(overrides)
+      def apply_cli_overrides(overrides) # rubocop:disable SortedMethodsByCall/Waterfall
         @config_mutex.synchronize do
           return reset_effective_config_internal if overrides.nil? || overrides.empty?
           return if @applied_overrides == overrides
@@ -266,7 +313,8 @@ module Docscribe
       def build_effective_config(overrides)
         config = @config or return
         require 'docscribe/cli/config_builder'
-        opts = overrides.transform_keys(&:to_sym)
+        require 'docscribe/cli/options'
+        opts = Docscribe::CLI::Options::DEFAULT.merge(overrides.transform_keys(&:to_sym))
         @effective_config = Docscribe::CLI::ConfigBuilder.build(config, opts)
         @file_cache.clear
         @applied_overrides = overrides
@@ -292,35 +340,164 @@ module Docscribe
       # @param [String] file
       # @param [Symbol] strategy
       # @raise [StandardError]
-      # @return [(String, Hash<Symbol, Object>)]
+      # @return [(String, Hash<Symbol, String, Array<Hash<Symbol, Object>>>)]
       def rewrite_file(file, strategy)
         @cache_mutex.synchronize do
           config = @effective_config || @config or raise 'Docscribe: config not loaded'
           key = [file, strategy]
           mtime = File.mtime(file)
-          hit = @file_cache[key]
-          return [hit[:src], hit[:result]] if hit && hit[:mtime] == mtime
+          sig_hash = sig_hash_for(config)
+          handle_sig_change(sig_hash)
+          cached = cached_result(key, mtime, sig_hash)
+          return cached if cached
 
           rewrite_and_cache(file, strategy, config, key, mtime)
         end
       end
 
+      # @private
+      # @param [String] sig_hash
+      # @return [void]
+      def handle_sig_change(sig_hash)
+        if @last_sig_hash && @last_sig_hash != sig_hash
+          [@config, @effective_config].compact.each { |c| clear_rbs_cache(c) }
+          @file_cache.clear
+        end
+        @last_sig_hash = sig_hash
+      end
+
+      # @private
+      # @param [Array<String, Symbol>] key
+      # @param [Time] mtime
+      # @param [String] sig_hash
+      # @return [(String, Hash<Symbol, String, Array<Hash<Symbol, Object>>>)?]
+      def cached_result(key, mtime, sig_hash)
+        hit = @file_cache[key]
+        return nil unless hit && hit[:mtime] == mtime && hit[:sig_hash] == sig_hash
+
+        [hit[:src], hit[:result]]
+      end
+
+      # Clear memoized RBS providers so next request rebuilds env with fresh sig files.
+      #
+      # @private
+      # @param [Docscribe::Config] config
+      # @raise [StandardError]
+      # @return [void]
+      # @return [nil] if StandardError
+      def clear_rbs_cache(config)
+        config.instance_variable_set(:@rbs_provider, nil) if config.instance_variable_defined?(:@rbs_provider)
+        config.instance_variable_set(:@core_rbs_provider, nil) if config.instance_variable_defined?(:@core_rbs_provider)
+      rescue StandardError
+        nil
+      end
+
       # @private
       # @param [String] file
       # @param [Symbol] strategy
-      # @param [Docscribe::Config, nil] config effective or base config
-      # @param [Array<(String, Symbol)>] key cache key
+      # @param [Docscribe::Config] config effective or base config
+      # @param [Array<String, Symbol>] key cache key
       # @param [Time] mtime file modification time
-      # @return [(String, Hash<Symbol, Object>)]
+      # @return [(String, Hash<Symbol, String, Array<Hash<Symbol, Object>>>)]
       def rewrite_and_cache(file, strategy, config, key, mtime)
         src = File.read(file)
         rbs = config.respond_to?(:core_rbs_provider) ? config.core_rbs_provider : nil
         result = Docscribe::InlineRewriter.rewrite_with_report(src, strategy: strategy, config: config,
                                                                     core_rbs_provider: rbs, file: file)
-        @file_cache[key] = { mtime: mtime, src: src, result: result }
+        @file_cache[key] = { mtime: mtime, sig_hash: @last_sig_hash, src: src, result: result }
         [src, result]
       end
 
+      # Hash of RBS signature files for cache invalidation.
+      # Includes all files under sig_dirs (default: sig/**/*.rbs).
+      #
+      # @private
+      # @param [Docscribe::Config] config effective or base config
+      # @raise [StandardError]
+      # @return [String]
+      # @return [String] if StandardError
+      def sig_hash_for(config)
+        files = sig_rbs_files(sig_dirs_for(config))
+        parts = files.map { |p| "#{p}:#{File.mtime(p).to_f}" if File.file?(p) }.compact
+        parts << "count:#{files.size}"
+        Digest::MD5.hexdigest(parts.join('|'))
+      rescue StandardError
+        '0'
+      end
+
+      # @private
+      # @param [Array<String>] dirs
+      # @return [Array<String>]
+      def sig_rbs_files(dirs)
+        dirs.flat_map { |dir| Dir.glob(File.join(Dir.pwd, dir, '**', '*.rbs')) }.uniq.sort
+      end
+
+      # Resolve sig dirs from config, falling back to defaults.
+      #
+      # @private
+      # @param [Docscribe::Config] config
+      # @raise [StandardError]
+      # @return [Array<String>]
+      # @return [Array] if StandardError
+      def sig_dirs_for(config)
+        raw_dirs = config.raw.dig('rbs', 'sig_dirs') if config.respond_to?(:raw)
+        dirs = Array(raw_dirs || Docscribe::Config::DEFAULT.dig('rbs', 'sig_dirs')).map(&:to_s) # steep:ignore
+        dirs.empty? ? ['sig'] : dirs
+      rescue StandardError
+        ['sig']
+      end
+
+      # Handle update_types request (used by RubyMine plugin).
+      #
+      # @private
+      # @param [UNIXSocket] client connected client socket
+      # @param [String, Integer] id request ID
+      # @param [Hash<String, Object>] params request params
+      # @raise [StandardError]
+      # @return [void]
+      # @return [void] if StandardError
+      def handle_update_types(client, id, params)
+        target = update_types_dir(params)
+        apply_cli_overrides(params['cli_overrides'])
+        exit_code = run_update_types(target)
+        @file_cache.clear
+        send_update_types_response(client, id, target, exit_code)
+      rescue StandardError => e
+        @file_cache.clear
+        code, message, data = classify_error(e, 'update_types', params)
+        send_error(client, id, code, message, data)
+      end
+
+      # @private
+      # @param [Hash<String, Object>] params
+      # @return [String]
+      def update_types_dir(params)
+        params['file'] || params['dir'] || params['directory'] || '.'
+      end
+
+      # @private
+      # @param [String] target
+      # @return [Integer]
+      def run_update_types(target)
+        require 'docscribe/cli/update_types'
+        Docscribe::CLI::UpdateTypes.run([target])
+      end
+
+      # @private
+      # @param [UNIXSocket] client
+      # @param [String, Integer] id
+      # @param [String] dir
+      # @param [Integer] exit_code
+      # @return [void]
+      def send_update_types_response(client, id, dir, exit_code)
+        if exit_code.zero?
+          send_result(client, id, 'status' => 'ok', 'dir' => dir, 'exit_code' => exit_code)
+        else
+          send_error(client, id, ERROR_CODES[:internal], "update_types failed with exit code #{exit_code}",
+                     { 'dir' => dir, 'exit_code' => exit_code })
+        end
+      end
+
       # Handle a shutdown request.
       #
       # @private
@@ -363,9 +540,9 @@ module Docscribe
 
       # @private
       # @param [Exception] exception
-      # @param [String, nil] _method_name
+      # @param [String?] _method_name
       # @param [Hash<String, Object>] params
-      # @return [(Integer, String, Object)]
+      # @return [(Integer, String, Hash<Symbol, Object, nil>, nil)]
       def classify_error(exception, _method_name = nil, params = {})
         if exception.is_a?(LoadError) || exception.is_a?(Gem::LoadError)
           classify_gem_error(exception)
@@ -395,7 +572,7 @@ module Docscribe
 
       # @private
       # @param [Exception] exception
-      # @return [(Integer, String, Hash<Symbol, String>)]
+      # @return [(Integer, String, Hash<Symbol, String, nil>)]
       def classify_gem_error(exception)
         data = { gem: nil }
         data[:gem] = exception.path if exception.respond_to?(:path) && exception.path
@@ -473,7 +650,7 @@ module Docscribe
       # @param [String, Integer, nil] id
       # @param [Integer] code
       # @param [String] message
-      # @param [Hash<Symbol, Object>, nil] data optional structured error data
+      # @param [Hash<Symbol, Object>?] data optional structured error data
       # @return [void]
       def send_error(client, id, code, message, data = nil)
         error = { code: code, message: message }

data/lib/docscribe/server/protocol.rb

@@ -13,8 +13,8 @@ module Docscribe
       #
       # @note module_function: defines #build_request (visibility: private)
       # @param [String] method method name
-      # @param [Hash<Symbol, Object>] params request parameters
-      # @return [Hash<Symbol, Object>]
+      # @param [Hash<Symbol, T>] params request parameters
+      # @return [Hash<Symbol, String, Hash<Symbol, T>>]
       def build_request(method, params = {})
         {
           jsonrpc: '2.0',
@@ -29,7 +29,7 @@ module Docscribe
       # @note module_function: defines #parse_response (visibility: private)
       # @param [String] line raw JSON line
       # @raise [JSON::ParserError]
-      # @return [Hash<String, Object>, nil]
+      # @return [Hash<String, Object>?]
       # @return [nil] if JSON::ParserError
       def parse_response(line)
         JSON.parse(line)
@@ -40,7 +40,7 @@ module Docscribe
       # Serialize a hash to a JSON line.
       #
       # @note module_function: defines #serialize (visibility: private)
-      # @param [Hash<Object, Object>] hash
+      # @param [Object] hash
       # @return [String]
       def serialize(hash)
         "#{JSON.generate(hash)}\n"