docscribe 1.5.0 → 1.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8183e1f4497ca5a00d13a9cc6457540db7b99ff85438be4bbd7eae2a26f4d785
-  data.tar.gz: d28fd30bfe8a940d43a1c545fccb94a10de2f60dc46870c737fa05fbd0e593be
+  metadata.gz: 6bbceb4704c077ffbe69c69d769bc5790347bbe3c64fce843069638214e53ee6
+  data.tar.gz: 22a7dd5cfa26ea46bac3e3a47e5e228cd3b0c6520fb3a3909dff09e66b1099ee
 SHA512:
-  metadata.gz: 86a886940d37aaab2b0a1f0d3393315a308a7d0f1ca6a1330bfc54977550a49d7b5763067e71a8b581fa97cb1223acfdd005ec3cab59a52e96049c114191f4fc
-  data.tar.gz: fc1e633462359286fcb528d7f9b8e8db9f87a50ba4c131fbfd75cb3fb84ba62ec06bc9bfc00bee467e02a1ea5a9cf04733063aadcd7d2ac127298fb7e11ac452
+  metadata.gz: 576a4645d81448f7cbceb93584e62710d54885d12d099b601d02d50b014d64cec6747756e7ed647d3dda35d12f734646b20508ab9080793e3ae1c26d027da6ba
+  data.tar.gz: f69b8cd81d990e88a292d0ada1eae224e521d9d6d6f4ced608a06cb71550bddbeb88723407332ea82b5c7c1c564ce6a6fd56286829d3ccb3077a7ed0ceb08629

data/README.md

@@ -1,15 +1,17 @@
-# Docscribe
+<p align="center">
+  <img src="assets/icons/icon_128x128.png" alt="Docscribe logo" width="128">
+</p>
 
-[![Gem Version](https://img.shields.io/gem/v/docscribe.svg)](https://rubygems.org/gems/docscribe)
-[![RubyGems Downloads](https://img.shields.io/gem/dt/docscribe.svg)](https://rubygems.org/gems/docscribe)
-[![CI](https://github.com/unurgunite/docscribe/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/unurgunite/docscribe/actions/workflows/ci.yml)
-[![License](https://img.shields.io/github/license/unurgunite/docscribe.svg)](https://github.com/unurgunite/docscribe/blob/master/LICENSE.txt)
-[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%202.7-blue.svg)](#installation)
-[![VS Code](https://img.shields.io/badge/VS%20Code-plugin-blue?logo=visualstudiocode)](https://marketplace.visualstudio.com/items?itemName=unurgunite.docscribe-vscode)
-[![RubyMine](https://img.shields.io/badge/RubyMine-plugin-green?logo=jetbrains)](https://plugins.jetbrains.com/plugin/32349-docscribe)
+<h1 align="center">DocScribe</h1>
 
-<p>
-  <img src="assets/icons/icon_256x256.png" alt="Docscribe logo" width="96">
+<p align="center">
+<a href="https://rubygems.org/gems/docscribe"><img src="https://img.shields.io/gem/v/docscribe.svg" alt="Gem Version"></a>
+<a href="https://rubygems.org/gems/docscribe"><img src="https://img.shields.io/gem/dt/docscribe.svg" alt="RubyGems Downloads"></a>
+<a href="https://github.com/unurgunite/docscribe/actions/workflows/ci.yml"><img src="https://github.com/unurgunite/docscribe/actions/workflows/ci.yml/badge.svg?branch=master" alt="CI"></a>
+<a href="https://github.com/unurgunite/docscribe/blob/master/LICENSE.txt"><img src="https://img.shields.io/github/license/unurgunite/docscribe.svg" alt="License"></a>
+<a href="#installation"><img src="https://img.shields.io/badge/ruby-%3E%3D%202.7-blue.svg" alt="Ruby"></a>
+<a href="https://marketplace.visualstudio.com/items?itemName=unurgunite.docscribe-vscode"><img src="https://img.shields.io/badge/VS%20Code-plugin-blue?logo=visualstudiocode" alt="VS Code"></a>
+<a href="https://plugins.jetbrains.com/plugin/32349-docscribe"><img src="https://img.shields.io/badge/RubyMine-plugin-green?logo=jetbrains" alt="RubyMine"></a>
 </p>
 
 ![Docscribe before/after demo](docs/image.png)
@@ -85,6 +87,7 @@ docscribe -A lib
         * [`docscribe rbs` — generate RBS from YARD](#docscribe-rbs--generate-rbs-from-yard)
         * [`docscribe update_types` — two-pass type-aware documentation update](#docscribe-update_types--two-pass-type-aware-documentation-update)
         * [`docscribe check_for_comments` — find placeholder documentation](#docscribe-check_for_comments--find-placeholder-documentation)
+        * [`docscribe server` — persistent daemon mode](#docscribe-server--persistent-daemon-mode)
     * [Update strategies](#update-strategies)
         * [Safe strategy](#safe-strategy)
         * [Aggressive strategy](#aggressive-strategy)
@@ -166,6 +169,10 @@ loading, then delegates to the core engine which parses source code, collects me
 doc lines — combining heuristic type inference, external RBS/Sorbet signatures, and plugin output — and finally rewrites
 the source via a strategy (safe merge or aggressive replace).
 
+In server mode, a persistent daemon (`docscribe server`) keeps the runtime loaded and caches parsed results across
+invocations via an LRU cache, enabling near-instant repeated checks for IDE plugins. A thin client (`docscribe-client`)
+provides minimal-overhead socket communication without loading the full gem.
+
 ```mermaid
 flowchart TB
     subgraph CLI["CLI Layer"]
@@ -240,7 +247,18 @@ flowchart TB
         YTypes["Yard::Types\n9 AST node types\n(Named, Generic, etc.)"]
     end
 
+    subgraph Server["Server / Daemon"]
+        ThinClient["exe/docscribe-client\nThin client\n· socket send/receive\n· no gem load"]
+        ServerDaemon["Server::Daemon\nSocket listener\n· check / fix / shutdown\n· JSON-RPC 2.0"]
+        Cache["Docscribe::LRUCache\nFile result cache\n(max 1000, by mtime)"]
+    end
+
     Exe --> Run
+    Exe --> ServerDaemon
+    ThinClient --> ServerDaemon
+    ServerDaemon --> ConfigClass
+    ServerDaemon --> Cache
+    ServerDaemon --> InlineRewriter
     Run --> Options
     Run --> InitCmd
     Run --> GenCmd
@@ -249,6 +267,7 @@ flowchart TB
     Run --> SarifFormatter
     Run --> ConfigBuilder
     ConfigBuilder --> ConfigClass
+    ConfigBuilder --> ServerDaemon
     ConfigClass --> Defaults
     ConfigClass --> Loader
     ConfigClass --> Emit
@@ -298,7 +317,25 @@ flowchart TB
 
 ```mermaid
 flowchart LR
-    Input["Source files\n(.rb)"] --> Parse["Parsing.parse_buffer\nParser gem / Prism"]
+    subgraph Entry["Entry Points"]
+        Direct["docscribe lib\n(no --server)"]
+        ViaServer["docscribe --server\nor docscribe-client"]
+    end
+
+    subgraph Daemon["Server Daemon (Unix Socket)"]
+        Socket["Daemon#listen_loop\nJSON-RPC 2.0 dispatch"]
+        CacheCheck{"File cached &\nmtime fresh?"}
+        CacheStorage["LRUCache\n(1000 entries)"]
+        ApplyOverrides["apply_cli_overrides\n(reset on nil)"]
+    end
+
+    ViaServer --> Socket
+    Socket --> ApplyOverrides
+    ApplyOverrides --> CacheCheck
+    CacheCheck -->|Hit| Socket
+    CacheCheck -->|Miss| Parse
+    Direct --> Parse
+    Parse["Parsing.parse_buffer\nParser gem / Prism"]
     Parse --> AST["AST + Comments"]
     AST --> Collect["Collector.process\n· Find methods\n· Track visibility\n· Find attr_*"]
     AST --> CollectPlugins["CollectorPlugin#collect\n· Custom AST walks\n· Non-standard constructs"]
@@ -317,7 +354,11 @@ flowchart LR
     Strategy -->|Aggressive| Replace["Replace entirely"]
     Merge --> Rewritten["Rewriter#process\n-> rewritten source"]
     Replace --> Rewritten
-    Rewritten --> Output["Modified .rb file\n/ STDOUT"]
+    Rewritten --> Result["Result / response"]
+    Rewritten --> CacheStorage
+    CacheStorage --> Socket
+    Result -->|Direct mode| Output["Modified .rb file / STDOUT"]
+    Result -->|Server mode| Socket
 ```
 
 ## CLI
@@ -330,6 +371,7 @@ docscribe sigs [options] [files...]
 docscribe rbs [options] [files...]
 docscribe update_types [directory]
 docscribe check_for_comments [paths...]
+docscribe server [start|status|stop] [options]
 ```
 
 Docscribe has three main ways to run:
@@ -376,6 +418,10 @@ If you pass no files and don't use `--stdin`, Docscribe processes the current di
 - `--explain`  
   Show detailed reasons for each file (default; no-op for compatibility).
 
+- `--server`  
+  Run via a persistent daemon (Unix socket). Speeds up repeated invocations
+  by keeping the Ruby runtime loaded and caching results.
+
 - `-k`, `--keep-descriptions`  
   Preserve existing documentation text when rebuilding doc blocks in aggressive mode.
 
@@ -599,6 +645,84 @@ Exit code `0` if no placeholders found, `1` if any are detected.
 
 - `-h`, `--help` — show help.
 
+### `docscribe server` — persistent daemon mode
+
+> [!NOTE]
+> Server mode requires **Ruby 3.1+** (`Process.fork` for background daemon).
+
+`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
+reloading the entire toolchain.
+
+```shell
+# Start the daemon (auto-detached in background)
+docscribe server start
+
+# Check if the daemon is running
+docscribe server status
+
+# Stop the daemon
+docscribe server stop
+
+# Use the daemon for file checks (much faster on repeated calls)
+docscribe --server lib
+docscribe -a --server lib
+```
+
+**How it works:**
+
+1. `docscribe server start` forks a background process that listens on a Unix socket in the system temp directory.
+2. The socket path is derived from the project root, `Gemfile.lock` mtime, and `rbs_collection.lock.yaml` mtime — so any
+   environment change spawns a fresh daemon automatically.
+3. Client requests (`docscribe --server`) send JSON-RPC 2.0 messages over the socket: `check` (inspect), `fix` (apply
+   changes), `shutdown`, and `ping` (health/version info).
+4. The daemon holds a reusable `Docscribe::Config` instance and an LRU file cache (bounded at 1000 entries), so repeated
+   checks on the same files are nearly instant.
+5. After 5 minutes of inactivity the daemon shuts down automatically.
+
+**Thin client (`docscribe-client`):**
+
+For IDE plugins and CI systems that need minimal startup overhead, a standalone thin client is available as
+`exe/docscribe-client`. It connects to the daemon via the same Unix socket protocol without loading the full docscribe
+gem:
+
+```shell
+# Check a file via the daemon
+docscribe-client --check lib/user.rb
+
+# Apply fixes via the daemon
+docscribe-client --fix lib/user.rb
+
+# Check if the daemon is running
+docscribe-client --status
+
+# Get version, pid, uptime from the daemon
+docscribe-client --ping
+
+# Stop the daemon
+docscribe-client --shutdown
+```
+
+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.
+
+**Environment invalidation:**
+
+The daemon's socket path includes a hash of:
+
+- `Gemfile.lock` mtime — gem changes that may affect RBS signatures.
+- `rbs_collection.lock.yaml` mtime — RBS collection signature updates.
+
+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.
+
+**CLI override handling:**
+
+When CLI overrides (`-C`, `--include`, `--exclude`, etc.) change between requests, the daemon resets its effective
+configuration, clears the file cache, and applies the new overrides before processing. If no overrides are passed, the
+cached state from the initial load is used, preserving performance.
+
 ## Update strategies
 
 Docscribe supports two update strategies: **safe** and **aggressive**.
@@ -1757,7 +1881,6 @@ yard doc -o docs
 - Overload-aware signature selection;
 - Manual `@!attribute` merge policy;
 - Richer inference for common APIs;
-- Editor integration (LSP, VS Code extension);
 - Documentation coverage report — percentage of documented methods, params, returns;
 - Pre-commit hook auto-install (`docscribe init --pre-commit`);
 - Parallel processing for large codebases.
@@ -1784,6 +1907,10 @@ Docscribe provides IDE plugins for a better development experience:
 
 > [!NOTE]
 > Both plugins require **docscribe >= 1.5.0**.
+>
+> For optimal performance, both plugins use the `docscribe-client` thin client
+> to communicate with the docscribe daemon (see [server mode](#docscribe-server--persistent-daemon-mode)).
+> Start the daemon with `docscribe server start` for near-instant diagnostics.
 
 ## Contributing
 

data/exe/docscribe-client

@@ -0,0 +1,105 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'optparse'
+require 'socket'
+require 'json'
+require 'securerandom'
+require 'digest/md5'
+require 'tmpdir'
+
+SOCKET_DIR = begin
+  tmp = Dir.tmpdir || '/tmp'
+  sock_overhead = "/docscribe-#{'a' * 32}.sock".bytesize
+  tmp.bytesize <= 104 - sock_overhead ? tmp : '/tmp'
+end
+ENV_FILES = %w[Gemfile.lock rbs_collection.lock.yaml].freeze
+
+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
+
+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
+
+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
+
+def send_request(sock, method, params = {})
+  socket = UNIXSocket.new(sock)
+  req = build_request(method, params)
+  socket.write("#{JSON.generate(req)}\n")
+  socket.close_write
+  line = socket.gets
+  line ? JSON.parse(line) : nil
+rescue Errno::ECONNREFUSED, Errno::ENOENT
+  nil
+ensure
+  socket&.close
+end
+
+def build_request(method, params = {})
+  { jsonrpc: '2.0', id: SecureRandom.uuid, method: method, params: params }
+end
+
+config_path = nil
+mode = nil
+file = nil
+
+OptionParser.new do |opts|
+  opts.on('-C', '--config <path>', 'Config file path') { |v| config_path = v }
+  opts.on('--check <file>', 'Check a file') do |v|
+    mode = :check
+    file = v
+  end
+  opts.on('--fix <file>', 'Fix a file') do |v|
+    mode = :fix
+    file = v
+  end
+  opts.on('--shutdown', 'Shutdown the server') { mode = :shutdown }
+  opts.on('--status', 'Show server status') { mode = :status }
+  opts.on('--ping', 'Ping the server') { mode = :ping }
+end.parse!
+
+sock = socket_path(config_path)
+
+case mode
+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 :shutdown
+  result = send_request(sock, 'shutdown')
+  puts JSON.generate(result || { error: 'Connection failed' })
+when :ping
+  result = send_request(sock, 'ping')
+  puts JSON.generate(result || { error: 'Connection failed' })
+when :status
+  alive = begin
+    File.exist?(sock) &&
+      UNIXSocket.new(sock).close && true
+  rescue StandardError
+    false
+  end
+  puts JSON.generate(alive ? { status: 'running', socket: sock } : { status: 'not_running' })
+else
+  warn "Usage: #{$PROGRAM_NAME} --check <file> | --fix <file> | --shutdown | --status | --ping"
+  exit 1
+end

data/lib/docscribe/cli/config_builder.rb

@@ -29,7 +29,7 @@ module Docscribe
         apply_rbs_overrides(raw, options) if rbs_overrides?(options)
         apply_sorbet_overrides(raw, options) if sorbet_overrides?(options)
         apply_output_overrides(raw, options)
-        conf = Docscribe::Config.new(raw)
+        conf = Docscribe::Config.new(config_path: base.config_path, **raw)
         warn_missing_rbs_collection(conf, options)
         conf
       end

data/lib/docscribe/cli/generate.rb

@@ -12,6 +12,16 @@ module Docscribe
     #   docscribe generate tag MyPlugin --output lib/docscribe_plugins
     #   docscribe generate tag MyPlugin --stdout
     module Generate
+      BANNER = <<~TEXT
+        Usage: docscribe generate <type> <PluginName> [options]
+
+        Types:
+          tag         Generate a TagPlugin skeleton
+          collector   Generate a CollectorPlugin skeleton
+
+        Options:
+      TEXT
+
       PLUGIN_TYPES = %w[tag collector].freeze
 
       NEXT_STEPS_TEMPLATE = <<~TEXT
@@ -275,29 +285,13 @@ module Docscribe
         # @return [OptionParser]
         def build_option_parser(opts)
           OptionParser.new do |opt|
-            opt.banner = parser_banner
+            opt.banner = BANNER
             register_output_option(opt, opts)
             register_stdout_option(opt, opts)
             register_help_option(opt, opts)
           end
         end
 
-        # Return the usage banner for the generate subcommand parser.
-        #
-        # @private
-        # @return [String]
-        def parser_banner
-          <<~TEXT
-            Usage: docscribe generate <type> <PluginName> [options]
-
-            Types:
-              tag         Generate a TagPlugin skeleton
-              collector   Generate a CollectorPlugin skeleton
-
-            Options:
-          TEXT
-        end
-
         # Register the --output option on the OptionParser.
         #
         # @private

data/lib/docscribe/cli/options.rb

@@ -26,7 +26,8 @@ module Docscribe
         rbs_collection: false,
         keep_descriptions: false,
         no_boilerplate: false,
-        progress: false
+        progress: false,
+        server: false
       }.freeze
 
       module_function
@@ -52,7 +53,8 @@ module Docscribe
 
         Input / config:
                 --stdin                    Read code from STDIN and print rewritten output
-            -C, --config PATH              Path to config YAML (default: docscribe.yml)
+            -C,                 --config PATH              Path to config YAML (default: docscribe.yml)
+                --server                   Use background server for faster repeated runs
 
         Type information:
                 --rbs                      Use RBS signatures for @param/@return when available
@@ -146,6 +148,7 @@ module Docscribe
       def define_input_options(opts, options)
         define_stdin_option(opts, options)
         define_config_option(opts, options)
+        define_server_option(opts, options)
       end
 
       # Define stdin option
@@ -172,6 +175,18 @@ module Docscribe
         end
       end
 
+      # Define server option
+      #
+      # @note module_function: defines #define_server_option (visibility: private)
+      # @param [OptionParser] opts the option parser to configure
+      # @param [Hash<Symbol, Object>] options mutable parsed options hash
+      # @return [void]
+      def define_server_option(opts, options)
+        opts.on('--server', 'Use background server for faster repeated runs') do
+          options[:server] = true
+        end
+      end
+
       # Define type options
       #
       # @note module_function: defines #define_type_options (visibility: private)

data/lib/docscribe/cli/rbs_gen.rb

@@ -162,7 +162,7 @@ module Docscribe
         # @param [Hash<Symbol, Object>] options
         # @raise [Parser::SyntaxError]
         # @raise [StandardError]
-        # @return [Boolean] if StandardError
+        # @return [Boolean]
         # @return [Boolean] if Parser::SyntaxError
         # @return [Boolean] if StandardError
         def generate_for_file(path, options)