docscribe 1.5.2 → 1.6.1

data/lib/docscribe/infer/behavior.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Docscribe
+  module Infer
+    # Analyzes method behavior (predicates, side effects, mutating calls).
+    module Behavior
+      MUTATING_METHODS = %i[<< push pop delete merge update write save create destroy
+                            insert update_all delete_all].freeze
+
+      class << self
+        # @param [Object] body
+        # @param [Object] method_name
+        # @return [Hash<Symbol, Object>]
+        def analyze(body, method_name)
+          result = default_result(method_name)
+
+          return result unless body.is_a?(Parser::AST::Node)
+
+          analyze_body(body, result)
+          result
+        end
+
+        # @param [Object] method_name
+        # @return [Hash<Symbol, Object>]
+        def default_result(method_name)
+          {
+            predicate: method_name&.to_s&.end_with?('?') || false,
+            bang: method_name&.to_s&.end_with?('!') || false,
+            has_side_effects: false,
+            delegates: nil,
+            returns_self: false,
+            returns_boolean: false
+          }
+        end
+
+        # @param [Hash<Symbol, Object>] analysis
+        # @param [Object] _method_name
+        # @return [String?]
+        def infer_description(analysis, _method_name)
+          return nil unless analysis[:has_side_effects] || analysis[:predicate]
+
+          if analysis[:predicate]
+            'Returns true if the condition is met, false otherwise'
+          elsif analysis[:returns_self]
+            'Returns self to allow method chaining'
+          elsif analysis[:has_side_effects]
+            nil
+          end
+        end
+
+        private
+
+        # @private
+        # @param [Object] node
+        # @param [Hash<Symbol, Object>] result
+        # @return [void]
+        def analyze_body(node, result)
+          case node.type
+          when :ivasgn, :ivar
+            result[:has_side_effects] = true
+          when :send
+            analyze_send(node, result)
+          when :self
+            result[:returns_self] = true if result[:returns_self]
+          end
+
+          recurse_children(node, result)
+        end
+
+        # @private
+        # @param [Object] node
+        # @param [Hash<Symbol, Object>] result
+        # @return [void]
+        def recurse_children(node, result)
+          node.children.each do |child|
+            analyze_body(child, result) if child.is_a?(Parser::AST::Node)
+          end
+        end
+
+        # @private
+        # @param [Object] node
+        # @param [Hash<Symbol, Object>] result
+        # @return [void]
+        def analyze_send(node, result)
+          _receiver, method_name = *node
+          method_sym = method_name.is_a?(Symbol) ? method_name : nil
+          return unless method_sym
+
+          return unless MUTATING_METHODS.include?(method_sym)
+
+          result[:has_side_effects] = true
+        end
+      end
+    end
+  end
+end

data/lib/docscribe/infer/params.rb

@@ -48,9 +48,7 @@ module Docscribe
       # @param [Boolean] treat_options_keyword_as_hash whether to treat 'options:' as Hash
       # @return [String]
       def inferred_param_type(name, default_str, fallback_type, treat_options_keyword_as_hash:)
-        if name.end_with?(':') && default_str.nil?
-          return options_keyword_type(name, treat_options_keyword_as_hash, fallback_type)
-        end
+        return options_keyword_type(name, treat_options_keyword_as_hash, fallback_type) if name.end_with?(':') && default_str.nil?
 
         node = parse_expr(default_str)
         ty = Literals.type_from_literal(node, fallback_type: fallback_type)

data/lib/docscribe/infer.rb

@@ -16,6 +16,7 @@ require_relative 'infer/literals'
 require_relative 'infer/params'
 require_relative 'infer/returns'
 require_relative 'infer/raises'
+require_relative 'infer/behavior'
 
 module Docscribe
   # Best-effort inference utilities used to generate YARD tags.
@@ -37,6 +38,40 @@ module Docscribe
         Raises.infer_raises_from_node(node)
       end
 
+      # Analyze method behavior from AST node and method name.
+      #
+      # @param [Object] node def or defs node
+      # @param [Object] method_name
+      # @return [Hash<Symbol, Object>]
+      def analyze_behavior(node, method_name)
+        body = extract_body(node)
+        Behavior.analyze(body, method_name)
+      end
+
+      # Get behavioral description for a method.
+      #
+      # @param [Object] node def or defs node
+      # @param [Object] method_name
+      # @return [String?]
+      def infer_behavior_description(node, method_name)
+        body = extract_body(node)
+        return nil unless body
+
+        analysis = Behavior.analyze(body, method_name)
+        Behavior.infer_description(analysis, method_name)
+      end
+
+      # Extract method body from def/defs node.
+      #
+      # @param [Object] node def or defs node
+      # @return [Object?]
+      def extract_body(node)
+        return nil unless node.is_a?(Parser::AST::Node)
+
+        body_idx = node.type == :def ? 2 : 3
+        node.children[body_idx]
+      end
+
       # Infer a parameter type from its internal name form and optional default
       # expression.
       #

data/lib/docscribe/inline_rewriter/doc_builder.rb

@@ -186,7 +186,7 @@ module Docscribe
       # @param [Hash<Symbol, Object>] opts additional options including
       # @return [Hash<Symbol, Object>]
       def resolve_doc_setup!(setup, node, name, config, opts)
-        external_sig = resolve_external_sig(setup[:container], setup[:scope], name, opts[:signature_provider])
+        external_sig = resolve_external_sig(setup[:container], setup[:scope], name, opts[:signature_provider], node)
         returns_spec = compute_returns_spec(node, config, opts[:param_types], opts[:core_rbs_provider],
                                             signature_provider: opts[:signature_provider],
                                             container: setup[:container])
@@ -219,9 +219,26 @@ module Docscribe
       # @param [Symbol] scope method scope symbol
       # @param [Symbol] name the method name string
       # @param [Docscribe::Types::ProviderChain, nil] signature_provider external sig provider
+      # @param [Parser::AST::Node] node
       # @return [Docscribe::Types::MethodSignature, nil]
-      def resolve_external_sig(container, scope, name, signature_provider)
-        signature_provider&.signature_for(container: container, scope: scope, name: name)
+      def resolve_external_sig(container, scope, name, signature_provider, node = nil)
+        param_count, param_names = extract_sig_param_info(node)
+        signature_provider&.signature_for(container: container, scope: scope, name: name,
+                                          param_count: param_count, param_names: param_names)
+      end
+
+      # @note module_function: defines #extract_sig_param_info (visibility: private)
+      # @param [Parser::AST::Node?] node
+      # @return [(Integer?, Array<String>)]
+      def extract_sig_param_info(node)
+        empty = [] #: Array[String]
+        return [nil, empty] unless node
+
+        args = extract_args_from_node(node)
+        empty = [] #: Array[String]
+        return [nil, empty] unless args
+
+        [args.children.length, args.children.map { |a| a.children.first.to_s if a.respond_to?(:children) }.compact]
       end
 
       # Compute returns spec
@@ -832,9 +849,7 @@ module Docscribe
       # @param [Hash<Symbol, Object>] info parse info hash to update with visibility flags
       # @return [Array<String>]
       def merge_module_function_note_lines(indent, insertion, name, info)
-        unless insertion.respond_to?(:module_function) && insertion.module_function && !info[:has_module_function_note]
-          return []
-        end
+        return [] unless insertion.respond_to?(:module_function) && insertion.module_function && !info[:has_module_function_note]
 
         included_vis = insertion.included_instance_visibility || :private
         ["#{indent}# @note module_function: defines ##{name} (visibility: #{included_vis})"]
@@ -1228,9 +1243,7 @@ module Docscribe
         end
 
         method_name = :"build_#{arg_node.type}_lines"
-        if respond_to?(method_name, true)
-          return send(method_name, arg_node, indent, external_sig, param_types_override, **opts)
-        end
+        return send(method_name, arg_node, indent, external_sig, param_types_override, **opts) if respond_to?(method_name, true)
 
         []
       end

data/lib/docscribe/inline_rewriter.rb

@@ -158,7 +158,8 @@ module Docscribe
       # @param [String] code the Ruby source code string to parse and rewrite
       # @param [Hash<Symbol, Object>] options hash containing :config, :file, and :core_rbs_provider
       # @raise [Docscribe::ParseError]
-      # @return [Hash<Symbol, Docscribe::Config, String, Parser::Source::Buffer, Parser::AST::Node, Docscribe::Types::ProviderChain, nil, Object, nil>]
+      # @return [Hash<Symbol, Docscribe::Config, String, Parser::Source::Buffer, Parser::AST::Node, Docscribe::Types::ProviderChain, nil, Object, nil>] rewrite environment with keys
+      #   :config, :file, :buffer, :ast, :core_rbs_provider
       def setup_rewrite_env(code, options)
         config = options[:config] || Docscribe::Config.load
         file = (options[:file] || '(inline)').to_s
@@ -454,7 +455,8 @@ module Docscribe
       # Plugin insertion priority
       #
       # @private
-      # @param [Hash<Symbol, Object>, Docscribe::InlineRewriter::Collector::Insertion, Docscribe::InlineRewriter::Collector::AttrInsertion] insertion the collected method insertion
+      # @param [Hash<Symbol, Object>, Docscribe::InlineRewriter::Collector::Insertion, Docscribe::InlineRewriter::Collector::AttrInsertion] insertion the collected
+      #   method insertion (plugin hash or collected insertion object)
       # @raise [StandardError]
       # @return [Integer]
       # @return [Integer] if StandardError
@@ -469,7 +471,8 @@ module Docscribe
       # Plugin insertion label
       #
       # @private
-      # @param [Hash<Symbol, Object>, Docscribe::InlineRewriter::Collector::Insertion, Docscribe::InlineRewriter::Collector::AttrInsertion] insertion the collected method insertion
+      # @param [Hash<Symbol, Object>, Docscribe::InlineRewriter::Collector::Insertion, Docscribe::InlineRewriter::Collector::AttrInsertion] insertion the collected
+      #   method insertion (plugin hash or collected insertion object)
       # @raise [StandardError]
       # @return [String]
       # @return [String] if StandardError
@@ -485,7 +488,8 @@ module Docscribe
       # Plugin insertion line
       #
       # @private
-      # @param [Hash<Symbol, Object>, Docscribe::InlineRewriter::Collector::Insertion, Docscribe::InlineRewriter::Collector::AttrInsertion] insertion the collected method insertion
+      # @param [Hash<Symbol, Object>, Docscribe::InlineRewriter::Collector::Insertion, Docscribe::InlineRewriter::Collector::AttrInsertion] insertion the collected
+      #   method insertion (plugin hash or collected insertion object)
       # @raise [StandardError]
       # @return [Integer, nil]
       # @return [nil] if StandardError
@@ -630,9 +634,7 @@ module Docscribe
       def normalize_plugin_doc(doc, indent, config:, anchor_node:)
         doc = normalize_plugin_doc_indent(doc, indent)
         doc = trim_trailing_blank_lines(doc)
-        if anchor_node && %i[def defs].include?(anchor_node.type) && config.include_default_message?
-          doc = prepend_default_message_if_no_prose(doc, anchor_node, indent, config)
-        end
+        doc = prepend_default_message_if_no_prose(doc, anchor_node, indent, config) if anchor_node && %i[def defs].include?(anchor_node.type) && config.include_default_message?
         doc
       end
 
@@ -794,9 +796,7 @@ module Docscribe
       # @return [void]
       def merge_existing_descriptions!(params, parsed)
         params[:param_descriptions] = parsed[:param_descriptions] if parsed[:param_descriptions].any?
-        if parsed[:return_description] && !parsed[:return_description].start_with?('if ')
-          params[:return_description] = parsed[:return_description]
-        end
+        params[:return_description] = parsed[:return_description] if parsed[:return_description] && !parsed[:return_description].start_with?('if ')
         params[:description] = parsed[:description] if parsed[:description].any?
       end
 
@@ -841,13 +841,27 @@ module Docscribe
       # @return [Docscribe::Types::MethodSignature, nil]
       def resolve_external_signature(insertion, signature_provider)
         node_name = SourceHelpers.node_name(insertion.node) #: Symbol
+        param_count, param_names = extract_param_info(insertion)
         signature_provider&.signature_for(
           container: insertion.container,
           scope: insertion.scope,
-          name: node_name
+          name: node_name,
+          param_count: param_count,
+          param_names: param_names
         )
       end
 
+      # @private
+      # @param [Object] insertion
+      # @return [(Integer?, Array<Object>)]
+      def extract_param_info(insertion)
+        args = DocBuilder.extract_args_from_node(insertion.node)
+        empty = [] #: Array[untyped]
+        return [nil, empty] unless args
+
+        [args.children.length, args.children.map { |a| a.children.first.to_s if a.respond_to?(:children) }.compact]
+      end
+
       # Resolve param types
       #
       # @private
@@ -1079,7 +1093,8 @@ module Docscribe
       # @param [Docscribe::Config] config the active Docscribe::Config
       # @param [Docscribe::Types::ProviderChain, nil] signature_provider external RBS signature provider
       # @param [Parser::Source::Range] bol_range the beginning-of-line range for the attribute node
-      # @return [Hash<Symbol, Docscribe::InlineRewriter::Collector::AttrInsertion, Docscribe::Config, Docscribe::Types::ProviderChain, nil, Parser::Source::Range>]
+      # @return [Hash<Symbol, Docscribe::InlineRewriter::Collector::AttrInsertion, Docscribe::Config, Docscribe::Types::ProviderChain, nil, Parser::Source::Range>] attr insertion params with keys
+      #   :insertion, :config, :signature_provider, :bol_range
       def attr_insertion_params(insertion, config, signature_provider, bol_range)
         {
           insertion: insertion, config: config,
@@ -1237,19 +1252,52 @@ module Docscribe
       # @return [String, nil]
       # @return [nil] if StandardError
       def build_attr_merge_additions(ins:, existing_lines:, config:, signature_provider:)
-        missing = missing_attr_names(ins, existing_lines)
-        return '' if missing.empty?
-
         indent = SourceHelpers.line_indent(ins.node)
-        lines = [] #: Array[String]
-        lines << "#{indent}#" if existing_lines.any? && existing_lines.last.strip != '#'
-        lines.concat(build_attr_doc_lines(ins, indent: indent, config: config,
-                                               signature_provider: signature_provider, names: missing))
-        lines.map { |l| "#{l}\n" }.join
+        lines = build_attr_merge_missing_lines(ins, existing_lines, indent, config, signature_provider)
+        lines.concat(build_attr_merge_tag_lines(ins, existing_lines, indent, config, signature_provider))
+
+        lines.empty? ? '' : lines.map { |l| "#{l}\n" }.join
       rescue StandardError
         nil
       end
 
+      # @private
+      # @param [Object] ins
+      # @param [Array<String>] existing_lines
+      # @param [String] indent
+      # @param [Docscribe::Config] config
+      # @param [Docscribe::Types::ProviderChain, nil] signature_provider
+      # @return [Array<String>]
+      def build_attr_merge_missing_lines(ins, existing_lines, indent, config, signature_provider)
+        missing = missing_attr_names(ins, existing_lines)
+        lines = [] #: Array[String]
+
+        unless missing.empty?
+          lines << "#{indent}#" if existing_lines.any? && existing_lines.last.strip != '#'
+          lines.concat(build_attr_doc_lines(ins, indent: indent, config: config,
+                                                 signature_provider: signature_provider, names: missing))
+        end
+
+        lines
+      end
+
+      # @private
+      # @param [Object] ins
+      # @param [Array<String>] existing_lines
+      # @param [String] indent
+      # @param [Docscribe::Config] config
+      # @param [Docscribe::Types::ProviderChain, nil] signature_provider
+      # @return [Array<String>]
+      def build_attr_merge_tag_lines(ins, existing_lines, indent, config, signature_provider)
+        tag_additions = build_missing_tag_additions(ins, existing_lines, indent, config, signature_provider)
+        return [] if tag_additions.empty?
+
+        result = [] #: Array[String]
+        result << "#{indent}#" if existing_lines.any? && existing_lines.last.strip != '#'
+        result.concat(tag_additions)
+        result
+      end
+
       # Missing attr names
       #
       # @private
@@ -1278,6 +1326,80 @@ module Docscribe
         names
       end
 
+      # Build missing tag additions for existing @!attribute lines
+      #
+      # @private
+      # @param [Docscribe::InlineRewriter::Collector::AttrInsertion] ins the attribute insertion object
+      # @param [Array<String>] existing_lines array of existing doc comment lines
+      # @param [String] indent whitespace indentation prefix
+      # @param [Docscribe::Config] config the active Docscribe::Config
+      # @param [Docscribe::Types::ProviderChain, nil] signature_provider external RBS signature provider
+      # @return [Array<String>]
+      def build_missing_tag_additions(ins, existing_lines, indent, config, signature_provider)
+        ins.names.each_with_object([]) do |name_sym, additions|
+          idx = existing_attr_line_index(existing_lines, name_sym.to_s)
+          next unless idx
+
+          attr_type = attribute_type(ins, name_sym, config, signature_provider: signature_provider)
+          additions << "#{indent}#   @return [#{attr_type}]" if attr_return_missing?(ins.access, existing_lines, idx)
+          additions << format_attribute_param_tag(indent, 'value', attr_type, style: config.param_tag_style) if attr_param_missing?(ins.access, existing_lines, idx)
+        end
+      end
+
+      # @private
+      # @param [Symbol] access
+      # @param [Array<String>] existing_lines
+      # @param [Integer] idx
+      # @return [Boolean]
+      def attr_return_missing?(access, existing_lines, idx)
+        %i[r rw].include?(access) && !existing_lines_contain_tag?(existing_lines, idx, 'return')
+      end
+
+      # @private
+      # @param [Symbol] access
+      # @param [Array<String>] existing_lines
+      # @param [Integer] idx
+      # @return [Boolean]
+      def attr_param_missing?(access, existing_lines, idx)
+        %i[w rw].include?(access) && !existing_lines_contain_tag?(existing_lines, idx, 'param')
+      end
+
+      # Find index of line containing @!attribute for a specific name
+      #
+      # @private
+      # @param [Array<String>] lines array of existing doc comment lines
+      # @param [String] name the attribute name to search for
+      # @return [Integer?]
+      def existing_attr_line_index(lines, name)
+        Array(lines).each_with_index do |line, idx|
+          return idx if line.match?(/\A\s*#\s*@!attribute\b(?:\s+\[[^\]]+\])?\s+#{Regexp.escape(name)}\b/)
+        end
+        nil
+      end
+
+      # Check if lines after an @!attribute line contain a specific tag
+      #
+      # Walks forward from attr_line_idx + 1, stopping at the next top-level
+      # directive or non-comment line.
+      #
+      # @private
+      # @param [Array<String>] lines array of existing doc comment lines
+      # @param [Integer] attr_line_idx index of the @!attribute line
+      # @param [String] tag_name the tag name to search for (e.g. "return", "param")
+      # @return [Boolean]
+      def existing_lines_contain_tag?(lines, attr_line_idx, tag_name)
+        i = attr_line_idx + 1
+        while i < lines.length
+          line = lines[i]
+          break unless line.match?(/\A\s*#/) # not a comment line
+          break if line.match?(/\A\s*# @(?!@)/) # next top-level directive (single space)
+          return true if line.match?(/\A\s*#\s{2,}@#{tag_name}\b/)
+
+          i += 1
+        end
+        false
+      end
+
       # Attribute allowed
       #
       # @private

data/lib/docscribe/server/base.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require 'socket'
+require 'fileutils'
+require 'digest/md5'
+require 'tmpdir'
+
+module Docscribe
+  # Server/daemon mode for persistent multi-request operation.
+  #
+  # Architecture:
+  # - Daemon process loads Ruby runtime once, listens on a Unix socket
+  # - Client sends JSON-line requests, receives JSON-line responses
+  # - Auto-shutdown after idle timeout
+  # - Protocol: JSON-RPC 2.0 over Unix socket
+  module Server
+    # Unix socket path max is 104 bytes on macOS (the more restrictive).
+    # Dir.tmpdir on macOS often returns a long path under /var/folders/.../T
+    # that exceeds this limit, so we fall back to /tmp when needed.
+    SOCKET_DIR = begin
+      tmp = Dir.tmpdir || '/tmp'
+      sock_overhead = "/docscribe-#{'a' * 32}.sock".bytesize # 48
+      tmp.bytesize <= 104 - sock_overhead ? tmp : '/tmp'
+    end
+    IDLE_TIMEOUT = 300
+
+    class << self
+      # Start the server daemon if not running.
+      #
+      # @param [String, nil] 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]
+      def ensure_running!(config_path: nil, daemonize: false, timeout: 5)
+        return if running?(config_path)
+
+        check_platform_support!
+
+        lock_path = "#{socket_path(config_path)}.lock"
+        File.open(lock_path, File::RDWR | File::CREAT, 0o644) do |lock|
+          lock.flock(File::LOCK_EX)
+          next if running?(config_path)
+
+          start_daemon_process(config_path: config_path, daemonize: daemonize)
+        end
+        wait_for_ready(config_path: config_path, timeout: timeout)
+      end
+
+      # Start the server daemon and wait for it to become ready.
+      #
+      # @param [String, nil] 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]
+      # @return [Boolean]
+      def wait_for_ready(config_path: nil, timeout: 5, raise_on_timeout: true) # rubocop:disable SortedMethodsByCall/Waterfall
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        loop do
+          return true if running?(config_path)
+
+          if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+            raise('Docscribe: server failed to start') if raise_on_timeout
+
+            warn('Docscribe server failed to start within timeout')
+            return false
+          end
+
+          sleep 0.1
+        end
+      end
+
+      # Whether a server process is listening on the socket.
+      #
+      # On ECONNREFUSED, checks whether the PID process is still alive:
+      # 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
+      # @raise [Errno::ECONNREFUSED]
+      # @raise [Errno::ENOENT]
+      # @raise [Errno::ENOTSOCK]
+      # @raise [StandardError]
+      # @return [Boolean]
+      # @return [Boolean] if Errno::ECONNREFUSED
+      # @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
+      rescue StandardError
+        false
+      end
+
+      # Handle ECONNREFUSED: check if the pid process is alive.
+      # Cleans up only if the process is dead.
+      #
+      # @param [String, nil] config_path
+      # @return [Boolean] false (not running)
+      def handle_stale_socket?(config_path)
+        pid = read_pid(config_path)
+        return false if pid && process_alive?(pid)
+
+        clean_socket_files(config_path)
+        false
+      end
+
+      # @param [Integer] pid
+      # @raise [Errno::ESRCH]
+      # @return [Boolean]
+      # @return [Boolean] if Errno::ESRCH
+      def process_alive?(pid)
+        Process.kill(0, pid)
+        true
+      rescue Errno::ESRCH
+        false
+      end
+
+      # @param [String, nil] config_path
+      # @raise [StandardError]
+      # @return [Integer, nil]
+      # @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))
+      rescue StandardError
+        nil
+      end
+
+      # Remove stale socket and pid files.
+      #
+      # @param [String, nil] 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
+      # @return [String]
+      def pid_path(config_path = nil)
+        "#{socket_path(config_path)}.pid"
+      end
+
+      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).
+      # When a config_path is given, its path + mtime are included in the hash
+      # so different configs get different daemons.
+      # 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
+      # @return [String]
+      def socket_path(config_path = nil)
+        seed = +Dir.pwd
+        seed << ":#{env_hash}"
+        if config_path
+          resolved = File.expand_path(config_path)
+          mtime = File.exist?(resolved) ? File.mtime(resolved).to_f : 0.0
+          seed << ":#{resolved}:#{mtime}"
+        end
+        "#{SOCKET_DIR}/docscribe-#{Digest::MD5.hexdigest(seed)}.sock"
+      end
+
+      # Hash of environment files that affect analysis results.
+      # When any of these change, the daemon is invalidated (new socket path).
+      #
+      # @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
+        Digest::MD5.hexdigest(parts.join(':'))
+      end
+
+      public :read_pid, :pid_path, :socket_path
+
+      # @param [String, nil] config_path
+      # @param [Boolean] daemonize
+      # @return [void]
+      def start_daemon_process(config_path:, daemonize:)
+        warn 'Docscribe: starting server...' if daemonize
+        pid = Process.fork do # steep:ignore NoMethod
+          [$stdin, $stdout].each { _1.reopen(File::NULL) }
+          $stderr.reopen(File::NULL)
+          Daemon.new(config_path: config_path).start
+        end
+        Process.detach(pid)
+      end
+    end
+  end
+end