docscribe 1.5.1 → 1.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6bbceb4704c077ffbe69c69d769bc5790347bbe3c64fce843069638214e53ee6
-  data.tar.gz: 22a7dd5cfa26ea46bac3e3a47e5e228cd3b0c6520fb3a3909dff09e66b1099ee
+  metadata.gz: 65ef814f594285faee2123170710fc06c47e3cf45471e79d4626fc2cb4885183
+  data.tar.gz: '008dd20fd7a7c3a6c9254be9ac8158005a4a84779d070939a7abdad0476f6df9'
 SHA512:
-  metadata.gz: 576a4645d81448f7cbceb93584e62710d54885d12d099b601d02d50b014d64cec6747756e7ed647d3dda35d12f734646b20508ab9080793e3ae1c26d027da6ba
-  data.tar.gz: f69b8cd81d990e88a292d0ada1eae224e521d9d6d6f4ced608a06cb71550bddbeb88723407332ea82b5c7c1c564ce6a6fd56286829d3ccb3077a7ed0ceb08629
+  metadata.gz: ff68cdf76163fc3a6e59192895b1b59a79116abb87f4921ea18d48b299a6b8f5e0be53ea090da01d089ed5b7cf954e77cfb78ca278012ced7fc97c39d76dfabc
+  data.tar.gz: 9ed8f9e80ceea75d6072077cf08a6a9d2d1c6135dd99ea4478ffca41889169dddc6f329f8f10888d5d1fdeeb82dc84fa046c6a818eaae20fae32639773b5c8e9

data/README.md

@@ -648,7 +648,8 @@ Exit code `0` if no placeholders found, `1` if any are detected.
 ### `docscribe server` — persistent daemon mode
 
 > [!NOTE]
-> Server mode requires **Ruby 3.1+** (`Process.fork` for background daemon).
+> Server mode requires **Ruby 3.1+** and a platform with `Process.fork` and Unix domain sockets.
+> Not available on **Windows** (no Unix sockets) or **JRuby** (no `Process.fork`).
 
 `docscribe server` starts a background daemon that keeps the Ruby runtime loaded and caches parsed ASTs across
 invocations. Subsequent `docscribe` calls with `--server` communicate with the daemon over a Unix socket instead of
@@ -703,6 +704,25 @@ docscribe-client --ping
 docscribe-client --shutdown
 ```
 
+Additional thin client commands:
+
+```shell
+# Print the Unix socket path (for IDE plugin integration)
+docscribe-client --socket-path
+
+# Show server info: version, pid, uptime, config path
+docscribe-client --info
+
+# Auto-start the daemon before running a check or fix
+docscribe-client --ensure --check lib/user.rb
+
+# Start the daemon standalone (exits when ready)
+docscribe-client --ensure
+
+# Batch check multiple files in one RPC call
+docscribe-client --check-batch lib/a.rb,lib/b.rb,lib/c.rb
+```
+
 The thin client is used automatically by
 the [VS Code](https://marketplace.visualstudio.com/items?itemName=unurgunite.docscribe-vscode)
 and [RubyMine](https://plugins.jetbrains.com/plugin/32349-docscribe) plugins when the daemon is running.
@@ -717,6 +737,41 @@ The daemon's socket path includes a hash of:
 If any of these files change, the next `docscribe --server` call will start a new daemon automatically. The old daemon
 is left to idle-timeout on its own.
 
+**JSON-RPC protocol (semi-stable API):**
+
+The daemon speaks JSON-RPC 2.0 over Unix socket. Each request is a JSON line, each response is a JSON line.
+
+Methods:
+
+| Method | Parameters | Result |
+|--------|-----------|--------|
+| `check` | `file` (string), `strategy` ("safe"/"aggressive"), `cli_overrides` (hash, optional) | `status`, `changed`, `changes` |
+| `fix` | same as `check` | `status`, `changed`, `changes` |
+| `check_batch` | `files` (array of strings), `strategy`, `cli_overrides`, `timeout` (int, optional) | array of per-file results |
+| `ping` | — | `version`, `pid`, `socket_path`, `started_at`, `uptime` |
+| `shutdown` | — | `status` |
+
+Error codes (standardized for IDE plugin integration):
+
+| Code | Meaning | `error.data` fields |
+|------|---------|-------------------|
+| `-32000` | Gem/dependency not found | `gem` |
+| `-32001` | Syntax error in analyzed file | `file`, `line`, `detail` |
+| `-32002` | Config load failure | — |
+| `-32010` | Timeout | `timeout`, `file` |
+| `-32099` | Internal unhandled error | `backtrace` (first 5 lines) |
+
+**Socket path derivation:**
+
+The socket path is a deterministic hash of:
+- Working directory (`Dir.pwd`)
+- `Gemfile.lock` mtime and `rbs_collection.lock.yaml` mtime (environment invalidation)
+- Config file path and mtime (when `--config` is used)
+
+Result: `/tmp/docscribe-<MD5 hash>.sock`
+
+IDE plugins should use `docscribe-client --socket-path` instead of reimplementing this algorithm.
+
 **CLI override handling:**
 
 When CLI overrides (`-C`, `--include`, `--exclude`, etc.) change between requests, the daemon resets its effective

data/exe/docscribe-client

@@ -60,6 +60,9 @@ end
 config_path = nil
 mode = nil
 file = nil
+ensure_flag = false
+batch_files = nil
+batch_timeout = nil
 
 OptionParser.new do |opts|
   opts.on('-C', '--config <path>', 'Config file path') { |v| config_path = v }
@@ -71,20 +74,65 @@ OptionParser.new do |opts|
     mode = :fix
     file = v
   end
+  opts.on('--check-batch <files>', 'Check multiple files (comma-separated)') do |v|
+    mode = :check_batch
+    batch_files = v
+  end
+  opts.on('--timeout <seconds>', 'Timeout per file in batch mode') { |v| batch_timeout = v.to_f }
   opts.on('--shutdown', 'Shutdown the server') { mode = :shutdown }
   opts.on('--status', 'Show server status') { mode = :status }
   opts.on('--ping', 'Ping the server') { mode = :ping }
+  opts.on('--socket-path', 'Print socket path and exit') { mode = :socket_path }
+  opts.on('--info', 'Show server info') { mode = :info }
+  opts.on('--ensure', 'Ensure server is running before check/fix') { ensure_flag = true }
 end.parse!
 
 sock = socket_path(config_path)
 
+if ensure_flag && mode.nil?
+  require 'docscribe/server'
+  Docscribe::Server.ensure_running!(config_path: config_path)
+  exit 0
+end
+
+if ensure_flag && %i[check fix].include?(mode)
+  begin
+    UNIXSocket.new(sock).close
+  rescue Errno::ECONNREFUSED, Errno::ENOENT
+    require 'docscribe/server'
+    Docscribe::Server.ensure_running!(config_path: config_path)
+  rescue StandardError => e
+    warn "docscribe: #{e.message}"
+    exit 1
+  end
+end
+
 case mode
+when :socket_path
+  puts sock
+when :info
+  result = send_request(sock, 'ping')
+  if result && result['result']
+    info = result['result']
+    info['status'] = 'running'
+    info['config_path'] = config_path if config_path
+    info['cli_overrides'] = {}
+    puts JSON.generate(info)
+  else
+    puts JSON.generate({ status: 'not_running', socket_path: sock })
+  end
 when :check
   result = send_request(sock, 'check', file: file, strategy: :safe)
   puts JSON.generate(result || { error: 'Connection failed' })
 when :fix
   result = send_request(sock, 'fix', file: file, strategy: :safe)
   puts JSON.generate(result || { error: 'Connection failed' })
+when :check_batch
+  files = batch_files.split(',').map(&:strip)
+  params = { files: files, strategy: :safe }
+  params[:timeout] = batch_timeout if batch_timeout
+  result = send_request(sock, 'check_batch', **params)
+  puts JSON.generate(result || { error: 'Connection failed' })
 when :shutdown
   result = send_request(sock, 'shutdown')
   puts JSON.generate(result || { error: 'Connection failed' })
@@ -100,6 +148,6 @@ when :status
   end
   puts JSON.generate(alive ? { status: 'running', socket: sock } : { status: 'not_running' })
 else
-  warn "Usage: #{$PROGRAM_NAME} --check <file> | --fix <file> | --shutdown | --status | --ping"
+  warn "Usage: #{$PROGRAM_NAME} --check <file> | --fix <file> | --check-batch <files> | --shutdown | --status | --ping | --socket-path | --info | --ensure"
   exit 1
 end

data/lib/docscribe/cli/rbs_gen.rb

@@ -167,7 +167,7 @@ module Docscribe
         # @return [Boolean] if StandardError
         def generate_for_file(path, options)
           process_source?(File.read(path), path, options)
-        rescue Parser::SyntaxError => e # steep:ignore
+        rescue Parser::SyntaxError => e
           warn "Syntax error in #{path}: #{e.message}"
           false
         rescue StandardError => e

data/lib/docscribe/cli/sigs.rb

@@ -169,7 +169,7 @@ module Docscribe
           return unless ast
 
           walk_for_methods(ast, [], methods, path)
-        rescue Parser::SyntaxError => e # steep:ignore
+        rescue Parser::SyntaxError => e
           warn "Syntax error in #{path}: #{e.message}"
         rescue StandardError => e
           warn "Error parsing #{path}: #{e.class}: #{e.message}"

data/lib/docscribe/infer/params.rb

@@ -98,7 +98,7 @@ module Docscribe
         buffer = Parser::Source::Buffer.new('(param)')
         buffer.source = src
         Docscribe::Parsing.parse_buffer(buffer)
-      rescue Parser::SyntaxError # steep:ignore
+      rescue Parser::SyntaxError
         nil
       end
     end

data/lib/docscribe/infer/returns.rb

@@ -26,7 +26,7 @@ module Docscribe
         local_var_types = build_local_variable_types(body)
         run_last_expr_type(body, fallback_type: FALLBACK_TYPE, nil_as_optional: true,
                                  local_var_types: local_var_types) || FALLBACK_TYPE
-      rescue Parser::SyntaxError # steep:ignore
+      rescue Parser::SyntaxError
         FALLBACK_TYPE
       end
 

data/lib/docscribe/inline_rewriter/doc_builder.rb

@@ -594,7 +594,7 @@ module Docscribe
 
         return_type = rest[1...type_end] #: String
         desc = rest[(type_end + 1)..]&.strip
-        [return_type, desc&.empty? ? nil : desc]
+        [return_type, desc && desc.empty? ? nil : desc]
       end
 
       # Extract all comment tags from line

data/lib/docscribe/server.rb

@@ -7,6 +7,7 @@ require 'securerandom'
 require 'digest/md5'
 require 'tmpdir'
 require 'time'
+require 'timeout'
 require_relative 'lru_cache'
 
 module Docscribe
@@ -34,11 +35,11 @@ module Docscribe
       # @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
-      # @raise [StandardError]
       # @return [void]
       def ensure_running!(config_path: nil, daemonize: false, timeout: 5)
         return if running?(config_path)
-        raise 'Server mode is unavailable on this Ruby/platform (Process.fork not supported)' unless Process.respond_to?(:fork)
+
+        check_platform_support!
 
         lock_path = "#{socket_path(config_path)}.lock"
         File.open(lock_path, File::RDWR | File::CREAT, 0o644) do |lock|
@@ -86,17 +87,18 @@ module Docscribe
       # @raise [StandardError]
       # @return [Boolean]
       # @return [Boolean] if Errno::ECONNREFUSED
-      # @return [Boolean] if Errno::ENOENT, Errno::ENOTSOCK
+      # @return [void, Boolean] if Errno::ENOENT, Errno::ENOTSOCK
       # @return [Boolean] if StandardError
       def running?(config_path = nil)
+        return false unless defined?(UNIXSocket)
+
         socket = UNIXSocket.new(socket_path(config_path))
         socket.close
         true
       rescue Errno::ECONNREFUSED
         handle_stale_socket?(config_path)
       rescue Errno::ENOENT, Errno::ENOTSOCK
-        clean_socket_files(config_path)
-        false
+        clean_socket_files(config_path) && false
       rescue StandardError
         false
       end
@@ -152,6 +154,29 @@ module Docscribe
 
       ENV_FILES = %w[Gemfile.lock rbs_collection.lock.yaml].freeze
 
+      # @param [String] config_path
+      # @return [String]
+      def config_hash(config_path)
+        resolved = File.expand_path(config_path)
+        mtime = File.exist?(resolved) ? File.mtime(resolved).to_f : 0.0
+        Digest::MD5.hexdigest("#{resolved}:#{mtime}")
+      end
+
+      # Check platform compatibility before starting server.
+      #
+      # @raise [StandardError]
+      # @return [void]
+      def check_platform_support!
+        unless defined?(UNIXSocket)
+          raise 'Server mode requires Unix domain sockets, which are not available on Windows. ' \
+                'Use docscribe directly without --server flag.'
+        end
+        return if Process.respond_to?(:fork)
+
+        raise 'Server mode requires Process.fork, which is not available on JRuby. ' \
+              'Use docscribe directly without --server flag.'
+      end
+
       # Derive a project-specific socket path from the current working directory.
       # Uses MD5 (deterministic across processes) instead of String#hash
       # (which varies per Ruby process due to random seeding).
@@ -173,14 +198,6 @@ module Docscribe
         "#{SOCKET_DIR}/docscribe-#{Digest::MD5.hexdigest(seed)}.sock"
       end
 
-      # @param [String] config_path
-      # @return [String]
-      def config_hash(config_path)
-        resolved = File.expand_path(config_path)
-        mtime = File.exist?(resolved) ? File.mtime(resolved).to_f : 0.0
-        Digest::MD5.hexdigest("#{resolved}:#{mtime}")
-      end
-
       # Hash of environment files that affect analysis results.
       # When any of these change, the daemon is invalidated (new socket path).
       #
@@ -332,6 +349,14 @@ module Docscribe
 
     # Daemon process that loads the Ruby runtime once and serves requests.
     class Daemon
+      # Standardized JSON-RPC error codes.
+      ERROR_CODES = {
+        gem_not_found: -32_000,
+        syntax_error: -32_001,
+        config_load_failure: -32_002,
+        timeout: -32_010,
+        internal: -32_099
+      }.freeze
       # @param [String?] socket_path custom socket path
       # @param [Integer] idle_timeout seconds before automatic shutdown
       # @param [String?] config_path custom config path
@@ -345,6 +370,8 @@ module Docscribe
         @server = nil
         @file_cache = LRUCache.new
         @started_at = Time.now
+        @cache_mutex = Mutex.new
+        @config_mutex = Mutex.new
       end
 
       # Start the daemon: load dependencies, bind socket, enter listen loop.
@@ -415,15 +442,16 @@ module Docscribe
       end
 
       # Accept a client connection if one is available.
+      # Spawns a thread to handle each client concurrently.
       #
       # @private
       # @return [void]
       def accept_client
-        client = @server&.accept if @server&.wait_readable(1)
+        client = @server&.accept if @server&.wait_readable(0.1)
         return unless client
 
-        handle_client(client)
         @last_request_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        Thread.new(client) { |conn| handle_client(conn) }
       end
 
       # Read a request from a client connection and dispatch it.
@@ -437,7 +465,10 @@ module Docscribe
         request = Protocol.parse_response(request_line)
         request ? handle_request(client, request) : send_error(client, nil, -32_700, 'Parse error')
       rescue StandardError => e
-        send_error(client, request&.dig('id'), -32_603, "#{e.class}: #{e.message}")
+        method_name = request&.dig('method')
+        error_params = request&.dig('params') || {}
+        code, message, data = classify_error(e, method_name, error_params)
+        send_error(client, request&.dig('id'), code, message, data)
       ensure
         client.close
       end
@@ -455,6 +486,7 @@ module Docscribe
         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}")
@@ -465,7 +497,9 @@ module Docscribe
       # @param [UNIXSocket] client
       # @param [String, Integer] id
       # @param [Hash<String, Object>] params
+      # @raise [StandardError]
       # @return [void]
+      # @return [void] if StandardError
       def handle_check(client, id, params)
         file = params['file']
         strategy = (params['strategy'] || 'safe').to_sym
@@ -475,13 +509,17 @@ module Docscribe
         src, result = rewrite_file(file, strategy)
         send_result(client, id, 'status' => result[:output] == src ? 'ok' : 'fail',
                                 'changed' => result[:output] != src, 'changes' => result[:changes])
+      rescue StandardError => e
+        handle_request_error(client, id, e, file)
       end
 
       # @private
       # @param [UNIXSocket] client
       # @param [String, Integer] id
       # @param [Hash<String, Object>] params
+      # @raise [StandardError]
       # @return [void]
+      # @return [void] if StandardError
       def handle_fix(client, id, params)
         file = params['file']
         strategy = (params['strategy'] || 'safe').to_sym
@@ -489,18 +527,79 @@ module Docscribe
 
         apply_cli_overrides(params['cli_overrides'])
         src, result = rewrite_file(file, strategy)
-        File.write(file, result[:output]) if result[:output] != src
-        send_result(client, id, 'status' => 'ok',
-                                'changed' => result[:output] != src, 'changes' => result[:changes])
+        changed = result[:output] != src
+        File.write(file, result[:output]) if changed
+        send_result(client, id, 'status' => 'ok', 'changed' => changed, 'changes' => result[:changes])
+      rescue StandardError => e
+        handle_request_error(client, id, e, file)
+      end
+
+      # @private
+      # @param [Object] client
+      # @param [Object] id
+      # @param [Object] params
+      # @return [void]
+      def handle_check_batch(client, id, params)
+        files = params['files']
+        return send_error(client, id, -32_602, 'Missing files parameter') unless files.is_a?(Array) && !files.empty?
+
+        strategy = (params['strategy'] || 'safe').to_sym
+        timeout = params['timeout']
+
+        apply_cli_overrides(params['cli_overrides'])
+
+        results = files.map do |file|
+          process_file_in_batch(file, strategy, timeout)
+        end
+
+        send_result(client, id, { 'results' => results })
+      end
+
+      # @private
+      # @param [String] file
+      # @param [Symbol] strategy
+      # @param [Integer, Float?] timeout
+      # @raise [Timeout::Error]
+      # @raise [StandardError]
+      # @return [Hash<String, Object>]
+      # @return [Hash] if Timeout::Error
+      # @return [Hash] if StandardError
+      def process_file_in_batch(file, strategy, timeout = nil)
+        return { 'file' => file, 'status' => 'error', 'error' => "File not found: #{file}" } unless File.file?(file)
+
+        block = -> { run_rewrite(file, strategy) }
+        timeout ? Timeout.timeout(timeout.to_f, &block) : block.call
+      rescue Timeout::Error
+        { 'file' => file, 'status' => 'error', 'error' => 'Timeout' }
+      rescue StandardError => e
+        { 'file' => file, 'status' => 'error', 'error' => "#{e.class}: #{e.message}" }
+      end
+
+      # @private
+      # @param [String] file
+      # @param [Symbol] strategy
+      # @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] }
       end
 
       # @private
       # @param [Hash<String, Object>?] overrides
       # @return [void]
       def apply_cli_overrides(overrides)
-        return reset_effective_config if overrides.nil? || overrides.empty?
-        return if @applied_overrides == overrides
+        @config_mutex.synchronize do
+          return reset_effective_config_internal if overrides.nil? || overrides.empty?
+          return if @applied_overrides == overrides
 
+          build_effective_config(overrides)
+        end
+      end
+
+      # @private
+      # @param [Hash<String, Object>] overrides
+      # @return [void]
+      def build_effective_config(overrides)
         config = @config or return
         require 'docscribe/cli/config_builder'
         opts = overrides.transform_keys(&:to_sym)
@@ -512,6 +611,12 @@ module Docscribe
       # @private
       # @return [void]
       def reset_effective_config
+        @config_mutex.synchronize { reset_effective_config_internal }
+      end
+
+      # @private
+      # @return [void]
+      def reset_effective_config_internal
         return unless @effective_config
 
         @effective_config = nil
@@ -525,12 +630,25 @@ module Docscribe
       # @raise [StandardError]
       # @return [(String, Hash<Symbol, Object>)]
       def rewrite_file(file, strategy)
-        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
+        @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
+
+          rewrite_and_cache(file, strategy, config, key, mtime)
+        end
+      end
 
+      # @private
+      # @param [String] file
+      # @param [Symbol] strategy
+      # @param [Object] config
+      # @param [Object] key
+      # @param [Object] mtime
+      # @return [(String, 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)
@@ -571,21 +689,131 @@ module Docscribe
       # @private
       # @param [UNIXSocket] client connected client socket
       # @param [String, Integer] id request ID
-      # @param [Hash<String, Object>] result result data
+      # @param [Object] result result data
       # @return [void]
       def send_result(client, id, result)
         response = { jsonrpc: '2.0', id: id, result: result }
         client.write(Protocol.serialize(response))
       end
 
+      # @private
+      # @param [Exception] exception
+      # @param [String?] _method_name
+      # @param [Hash<String, Object>] params
+      # @return [(Integer, String, Object?)]
+      def classify_error(exception, _method_name = nil, params = {})
+        if exception.is_a?(LoadError) || exception.is_a?(Gem::LoadError)
+          classify_gem_error(exception)
+        elsif syntax_error?(exception)
+          classify_syntax_err(exception, params)
+        elsif timeout_error?(exception)
+          classify_timeout_err(exception, params)
+        else
+          classify_internal_err(exception)
+        end
+      end
+
+      # @private
+      # @param [Exception] exception
+      # @return [Boolean]
+      def syntax_error?(exception)
+        exception.is_a?(Docscribe::ParseError) ||
+          (defined?(Parser::SyntaxError) && exception.is_a?(Parser::SyntaxError))
+      end
+
+      # @private
+      # @param [Exception] exception
+      # @return [Boolean]
+      def timeout_error?(exception)
+        !!defined?(Timeout::Error) && exception.is_a?(Timeout::Error)
+      end
+
+      # @private
+      # @param [Object] exception
+      # @return [(Integer, String, Object)]
+      def classify_gem_error(exception)
+        data = { gem: nil }
+        data[:gem] = exception.path if exception.respond_to?(:path) && exception.path
+        [ERROR_CODES[:gem_not_found], "#{exception.class}: #{exception.message}", data]
+      end
+
+      # @private
+      # @param [Object] exception
+      # @param [Hash<String, Object>] params
+      # @return [(Integer, String, Object)]
+      def classify_syntax_err(exception, params)
+        file = (params['file'] if params.is_a?(Hash)).to_s
+        line = if exception.respond_to?(:line)
+                 exception.line
+               elsif exception.respond_to?(:diagnostic)
+                 exception.diagnostic.location.line
+               end
+        data = { file: file, detail: exception.message, line: line }.compact
+        [ERROR_CODES[:syntax_error], "Syntax error in #{file}", data]
+      end
+
+      # @private
+      # @param [Object] exception
+      # @param [Hash<String, Object>] params
+      # @return [(Integer, String, Object)]
+      def classify_timeout_err(exception, params)
+        file = (params['file'] if params.is_a?(Hash)).to_s
+        data = { timeout: @idle_timeout || 30, file: file }
+        [ERROR_CODES[:timeout], "#{exception.class}: #{exception.message}", data]
+      end
+
+      # @private
+      # @param [Object] exception
+      # @return [(Integer, String, Object)]
+      def classify_internal_err(exception)
+        backtrace = exception.backtrace&.first(5) || []
+        data = { backtrace: backtrace }
+        [ERROR_CODES[:internal], "#{exception.class}: #{exception.message}", data]
+      end
+
+      # @private
+      # @param [UNIXSocket] client
+      # @param [String, Integer] id
+      # @param [Object] exception
+      # @param [String] file
+      # @raise [StandardError]
+      # @return [void]
+      def handle_request_error(client, id, exception, file)
+        if exception.is_a?(Docscribe::ParseError) ||
+           (defined?(Parser::SyntaxError) && exception.is_a?(Parser::SyntaxError))
+          send_syntax_error(client, id, exception, file)
+        else
+          raise
+        end
+      end
+
+      # @private
+      # @param [UNIXSocket] client
+      # @param [String, Integer] id
+      # @param [Object] exception
+      # @param [String] file
+      # @return [void]
+      def send_syntax_error(client, id, exception, file)
+        line = if exception.respond_to?(:line)
+                 exception.line
+               elsif exception.respond_to?(:diagnostic)
+                 exception.diagnostic.location.line
+               end
+        data = { file: file, detail: exception.message, line: line }.compact
+        send_error(client, id, ERROR_CODES[:syntax_error], "Syntax error in #{file}", data)
+      end
+
       # @private
       # @param [UNIXSocket] client
       # @param [String, Integer, nil] id
       # @param [Integer] code
       # @param [String] message
+      # @param [Object?] data optional structured error data
       # @return [void]
-      def send_error(client, id, code, message)
-        response = { jsonrpc: '2.0', id: id, error: { code: code, message: message } }
+      def send_error(client, id, code, message, data = nil)
+        error = { code: code, message: message }
+        error[:data] = data if data
+        response = { jsonrpc: '2.0', id: id, error: error }
         client.write(Protocol.serialize(response))
       end
 

data/lib/docscribe/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Docscribe
-  VERSION = '1.5.1'
+  VERSION = '1.5.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docscribe
 version: !ruby/object:Gem::Version
-  version: 1.5.1
+  version: 1.5.2
 platform: ruby
 authors:
 - unurgunite
@@ -230,7 +230,7 @@ metadata:
   changelog_uri: https://github.com/unurgunite/docscribe/blob/master/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message: |
-  You installed docscribe 1.5.1. Your future self (and your team) thank you.
+  You installed docscribe 1.5.2. Your future self (and your team) thank you.
 
     $ docscribe --help
 
@@ -250,7 +250,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.13
+rubygems_version: 4.0.15
 specification_version: 4
 summary: Auto-generate inline YARD documentation for Ruby by analyzing code AST. Supports
   RBS and Sorbet type signatures.