docscribe 1.5.1 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6bbceb4704c077ffbe69c69d769bc5790347bbe3c64fce843069638214e53ee6
-  data.tar.gz: 22a7dd5cfa26ea46bac3e3a47e5e228cd3b0c6520fb3a3909dff09e66b1099ee
+  metadata.gz: 1016144165d119ade7719092f38974b29082a1bd86824864dd3a9b3412268771
+  data.tar.gz: ed2f6bbaf4e6f5892e0977a34c9aecb4924badc7e21ef25892d88bb4b0f8611a
 SHA512:
-  metadata.gz: 576a4645d81448f7cbceb93584e62710d54885d12d099b601d02d50b014d64cec6747756e7ed647d3dda35d12f734646b20508ab9080793e3ae1c26d027da6ba
-  data.tar.gz: f69b8cd81d990e88a292d0ada1eae224e521d9d6d6f4ced608a06cb71550bddbeb88723407332ea82b5c7c1c564ce6a6fd56286829d3ccb3077a7ed0ceb08629
+  metadata.gz: 7d1a11cef005ba87ef7fdf97d594ea699d638bc2a75dd62838ccec6f9260fca9b090e44a3176957584a30506f1159545354566a372c54e16382a2d384ae8248d
+  data.tar.gz: fd23695cdba7b7726e306ac2300665cb1f5eaf2764d2e19946df99fec6f7fee112408459fc774710305358a55d394413c4c8b3c663bd432514ffaf8f939d6dcf

data/README.md

@@ -73,72 +73,74 @@ docscribe -A lib
 
 ## Contents
 
-* [Docscribe](#docscribe)
-    * [Quick start](#quick-start)
-    * [Contents](#contents)
-    * [Installation](#installation)
-    * [Architecture](#architecture)
-        * [Data flow](#data-flow)
-    * [CLI](#cli)
-        * [Exit codes](#exit-codes)
-        * [Options](#options)
-        * [Examples](#examples)
-        * [`docscribe sigs` — check RBS signature coverage](#docscribe-sigs--check-rbs-signature-coverage)
-        * [`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)
-        * [Output markers](#output-markers)
-    * [Tips & tricks](#tips--tricks)
-    * [Parser backend (Parser gem vs Prism)](#parser-backend-parser-gem-vs-prism)
-    * [External type integrations (optional)](#external-type-integrations-optional)
-        * [RBS](#rbs)
-            * [RBS collection auto-discovery](#rbs-collection-auto-discovery)
-        * [Sorbet](#sorbet)
-        * [Inline Sorbet example](#inline-sorbet-example)
-        * [Sorbet RBI example](#sorbet-rbi-example)
-        * [Sorbet comment placement](#sorbet-comment-placement)
-        * [Generic type formatting](#generic-type-formatting)
-        * [Notes and fallback behavior](#notes-and-fallback-behavior)
-    * [Type inference](#type-inference)
-    * [Rescue-aware returns and @raise](#rescue-aware-returns-and-raise)
-    * [Visibility semantics](#visibility-semantics)
-    * [API (library) usage](#api-library-usage)
-    * [Plugin system](#plugin-system)
-        * [TagPlugin](#tagplugin)
-        * [CollectorPlugin](#collectorplugin)
-            * [Plugin doc normalization (CollectorPlugin)](#plugin-doc-normalization-collectorplugin)
-            * [`method_override` (structured patch)](#method_override-structured-patch)
-        * [Registering plugins](#registering-plugins)
-        * [Plugin priority](#plugin-priority)
-        * [Idempotency](#idempotency)
-        * [Plugin examples](#plugin-examples)
-    * [Configuration](#configuration)
-        * [Anonymous block parameters](#anonymous-block-parameters)
-        * [Filtering](#filtering)
-        * [`attr_*` example](#attr_-example)
-        * [`Struct.new` examples](#structnew-examples)
-            * [Constant-assigned struct](#constant-assigned-struct)
-            * [Class-based struct](#class-based-struct)
-        * [Merge behavior](#merge-behavior)
-        * [Param tag style](#param-tag-style)
-        * [Create a starter config](#create-a-starter-config)
-        * [Generate a plugin skeleton](#generate-a-plugin-skeleton)
-        * [Full configuration reference](#full-configuration-reference)
-    * [CI integration](#ci-integration)
-    * [Comparison to YARD's parser](#comparison-to-yards-parser)
-    * [Limitations](#limitations)
-    * [Roadmap](#roadmap)
-    * [Editor Integration](#editor-integration)
-        * [VS Code](#vs-code)
-        * [RubyMine](#rubymine)
-    * [Contributing](#contributing)
-    * [Discussion & Community](#discussion--community)
-    * [Logo Attribution](#logo-attribution)
-    * [License](#license)
+* [Quick start](#quick-start)
+* [Contents](#contents)
+* [Installation](#installation)
+* [Architecture](#architecture)
+    * [Data flow](#data-flow)
+* [CLI](#cli)
+    * [Exit codes](#exit-codes)
+    * [Options](#options)
+    * [Examples](#examples)
+    * [`docscribe sigs` — check RBS signature coverage](#docscribe-sigs--check-rbs-signature-coverage)
+    * [`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 init` — project scaffolding](#docscribe-init--project-scaffolding)
+    * [`docscribe config` — view resolved configuration](#docscribe-config--view-resolved-configuration)
+    * [`docscribe coverage` — documentation coverage report](#docscribe-coverage--documentation-coverage-report)
+    * [`docscribe server` — persistent daemon mode](#docscribe-server--persistent-daemon-mode)
+* [Update strategies](#update-strategies)
+    * [Safe strategy](#safe-strategy)
+    * [Aggressive strategy](#aggressive-strategy)
+    * [Output markers](#output-markers)
+* [Tips & tricks](#tips--tricks)
+* [Parser backend (Parser gem vs Prism)](#parser-backend-parser-gem-vs-prism)
+* [External type integrations (optional)](#external-type-integrations-optional)
+    * [RBS](#rbs)
+        * [RBS collection auto-discovery](#rbs-collection-auto-discovery)
+    * [Sorbet](#sorbet)
+    * [Inline Sorbet example](#inline-sorbet-example)
+    * [Sorbet RBI example](#sorbet-rbi-example)
+    * [Sorbet comment placement](#sorbet-comment-placement)
+    * [Generic type formatting](#generic-type-formatting)
+    * [Notes and fallback behavior](#notes-and-fallback-behavior)
+* [Type inference](#type-inference)
+* [Rescue-aware returns and @raise](#rescue-aware-returns-and-raise)
+* [Visibility semantics](#visibility-semantics)
+* [API (library) usage](#api-library-usage)
+* [Plugin system](#plugin-system)
+    * [TagPlugin](#tagplugin)
+    * [CollectorPlugin](#collectorplugin)
+        * [Plugin doc normalization (CollectorPlugin)](#plugin-doc-normalization-collectorplugin)
+        * [`method_override` (structured patch)](#method_override-structured-patch)
+    * [Registering plugins](#registering-plugins)
+    * [Plugin priority](#plugin-priority)
+    * [Idempotency](#idempotency)
+    * [Plugin examples](#plugin-examples)
+* [Configuration](#configuration)
+    * [Anonymous block parameters](#anonymous-block-parameters)
+    * [Filtering](#filtering)
+    * [`attr_*` example](#attr_-example)
+    * [`Struct.new` examples](#structnew-examples)
+        * [Constant-assigned struct](#constant-assigned-struct)
+        * [Class-based struct](#class-based-struct)
+    * [Merge behavior](#merge-behavior)
+    * [Param tag style](#param-tag-style)
+    * [Create a starter config](#create-a-starter-config)
+    * [Generate a plugin skeleton](#generate-a-plugin-skeleton)
+    * [Full configuration reference](#full-configuration-reference)
+* [CI integration](#ci-integration)
+* [Comparison to YARD's parser](#comparison-to-yards-parser)
+* [Limitations](#limitations)
+* [Roadmap](#roadmap)
+* [Editor Integration](#editor-integration)
+    * [VS Code](#vs-code)
+    * [RubyMine](#rubymine)
+* [Contributing](#contributing)
+* [Discussion & Community](#discussion--community)
+* [Logo Attribution](#logo-attribution)
+* [License](#license)
 
 ## Installation
 
@@ -411,6 +413,9 @@ If you pass no files and don't use `--stdin`, Docscribe processes the current di
 - `--progress`  
   Show progress (`[N/total] path/to/file.rb`) on stderr as each file is processed.
 
+- `DOCSCRIBE_THREADS` (env var)  
+  Number of parallel worker threads (default: 4). Set to `1` for sequential processing.
+
 - `--quiet` (`-q`)  
   Only show status, no details (suppresses change reasons).
   Overrides the default detailed output.
@@ -645,10 +650,68 @@ Exit code `0` if no placeholders found, `1` if any are detected.
 
 - `-h`, `--help` — show help.
 
+### `docscribe init` — project scaffolding
+
+`docscribe init` creates a default `docscribe.yml` config file in the current directory. It asks interactive questions
+about your project and writes a tailored configuration.
+
+```shell
+# Create docscribe.yml interactively
+docscribe init
+
+# Create with default settings (non-interactive)
+docscribe init --default
+```
+
+**Flags:**
+
+- `--pre-commit` — generate and install a Git pre-commit hook that checks documentation on staged `.rb` files using
+  `docscribe --verbose`. The hook exits with a warning if staged files lack documentation.
+- `--pre-commit --uninstall` — remove the pre-commit hook.
+- `--pre-commit --dry-run` — preview the hook script without installing.
+- `--default` — skip interactive prompts, write default config.
+- `-h`, `--help` — show help.
+
+### `docscribe config` — view resolved configuration
+
+`docscribe config` prints the fully resolved configuration (defaults + file + CLI overrides) as YAML.
+
+```shell
+# Print resolved config
+docscribe config
+
+# Use a specific config file
+docscribe config --config path/to/docscribe.yml
+```
+
+**Flags:**
+
+- `--config PATH` — path to config file.
+- `-h`, `--help` — show help.
+
+### `docscribe coverage` — documentation coverage report
+
+`docscribe coverage` scans Ruby files and reports the percentage of documented methods, parameters, and return types.
+
+```shell
+# Generate coverage report (text table)
+docscribe coverage lib
+
+# JSON output for tooling
+docscribe coverage --format json lib
+```
+
+**Flags:**
+
+- `--format FORMAT` — output format: `text` (default, human-readable table) or `json` (machine-readable).
+- `--config PATH` — path to config file.
+- `-h`, `--help` — show help.
+
 ### `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 +766,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 +799,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
@@ -743,6 +860,17 @@ Safe strategy:
 
 This is the recommended day-to-day mode.
 
+**`@!attribute` merge policy in safe mode:**
+
+When a method already has a YARD `@!attribute` doc block (e.g. `# @!attribute [rw] name`), safe mode does not
+overwrite it. Instead it merges only the missing parts:
+
+- If the attribute has `[r]` or `[rw]` access and no `@return` tag exists — adds `@return [Type]`.
+- If the attribute has `[w]` or `[rw]` access and no `@param` tag exists — adds `@param value [Type]`.
+- If some attrs from the `attr_*` call are present in the doc block but others are missing — adds only the missing ones.
+
+This preserves hand-written annotations while ensuring complete documentation.
+
 ### Aggressive strategy
 
 Used by:
@@ -1874,16 +2002,10 @@ yard doc -o docs
 
 ## Roadmap
 
-- Method behavior inference from AST;
+- Overload-aware signature selection;
 - Deeper YARD integration — parse `.c` source comments and generate docs for C-extensions;
 - Custom parser plugins — support non-Ruby languages (Crystal, etc.) via the plugin system;
-- Effective config dump;
-- Overload-aware signature selection;
-- Manual `@!attribute` merge policy;
-- Richer inference for common APIs;
-- Documentation coverage report — percentage of documented methods, params, returns;
-- Pre-commit hook auto-install (`docscribe init --pre-commit`);
-- Parallel processing for large codebases.
+- Richer inference for common APIs.
 
 ## Editor Integration
 

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,8 @@ 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/config_dump.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'optparse'
+require 'yaml'
+require 'docscribe/config'
+require 'docscribe/cli/config_builder'
+
+module Docscribe
+  module CLI
+    # Print the fully resolved configuration as YAML.
+    module ConfigDump
+      BANNER = <<~TEXT
+        Usage: docscribe config [options]
+
+        Print the fully resolved configuration as YAML.
+
+        Options:
+      TEXT
+
+      class << self
+        # @param [Array<String>] argv
+        # @return [Integer]
+        def run(argv)
+          opts = parse_options(argv)
+          return 0 if opts[:help]
+
+          conf = Docscribe::Config.load(opts[:config])
+          conf = Docscribe::CLI::ConfigBuilder.build(conf, parse_cli_overrides(argv))
+
+          puts conf.to_h.to_yaml
+          0
+        end
+
+        private
+
+        # @private
+        # @param [Array<String>] argv
+        # @return [Hash<Symbol, Object>]
+        def parse_options(argv)
+          opts = { config: nil }
+          build_parser(opts).parse!(argv)
+          opts
+        end
+
+        # @private
+        # @param [Hash<Symbol, Object>] opts
+        # @return [OptionParser]
+        def build_parser(opts)
+          OptionParser.new do |o|
+            o.banner = BANNER
+            o.on('--config PATH', 'Path to config file') { |v| opts[:config] = v }
+            o.on('-h', '--help', 'Show help') do
+              opts[:help] = true
+              puts o
+            end
+          end
+        end
+
+        # @private
+        # @param [Array<String>] argv
+        # @return [Hash<Symbol, Object>]
+        def parse_cli_overrides(argv)
+          opts = Docscribe::CLI::Options.parse!(argv)
+          opts.slice(:rbs, :rbs_collection, :sorbet, :sig_dirs, :rbi_dirs, :include, :exclude, :include_file,
+                     :exclude_file)
+        end
+      end
+    end
+  end
+end