docscribe 1.6.1 → 1.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24df08456004986c5cae869a2e7dc9ba4a1176cbf5dbaaca679cb4661836a3dc
-  data.tar.gz: 746d064972fe321f6b0d7459d87f1fc4cec8c414b4b4b73b9cce916f72b4139d
+  metadata.gz: 3c7164ab1529448e4446137381b717690e22d57ced3cf9042be38ab00ff5f470
+  data.tar.gz: 7dc01723974b29fe8a6179220d04ffe3c9141e471c3ec1fbed309b9e5a780a5e
 SHA512:
-  metadata.gz: 4cf1ba70c9a43ec923abda6c16bbd599b287803fd9c6968b0e4c0ea87079fd8d1dd95317f7a20715f6664a7a1876da46cf008b3f6c21fc115237592b041f29b2
-  data.tar.gz: 0e7e994de57e167edf3a47b3d92ad1c123cb2decf973d137fcc7ac0bcd33f869fc380abd2d2705a2820d09837bce012b12f2f7efc2bbf0fe679da226040e43fb
+  metadata.gz: cee99e8d318b327bc64786555c0347cc995e6a23d5fb42863c13efda6e6467bdc5032bd37f1a7b518ca3f4c41c5967034f278664f0b9ee1110d712f01011f000
+  data.tar.gz: 59ab6f4b18a349fc9e40c3b39f85dd331c76f606bb9162ff410b11e40338f9a3e3d05e8ab002e345c6ef3be47a1ee524cc9d12649ce7d0a7deb149c376c6edd5

data/README.md

@@ -78,6 +78,7 @@ docscribe -A lib
 * [Installation](#installation)
 * [Architecture](#architecture)
     * [Data flow](#data-flow)
+    * [IDE plugin and gem interaction](#ide-plugin-and-gem-interaction)
 * [CLI](#cli)
     * [Exit codes](#exit-codes)
     * [Options](#options)
@@ -175,193 +176,31 @@ In server mode, a persistent daemon (`docscribe server`) keeps the runtime loade
 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"]
-        Exe["exe/docscribe\nEntry point"]
-        Run["CLI::Run\nMain execution\n· expand paths\n· iterate files\n· report results"]
-        Options["CLI::Options\nARGV parsing\n(mode, strategy,\nfilters, flags)"]
-        InitCmd["CLI::Init\ndocscribe init\nGenerate config"]
-        GenCmd["CLI::Generate\ndocscribe generate\nScaffold plugins"]
-        SigsCmd["CLI::Sigs\ndocscribe sigs\nCheck RBS coverage"]
-        RbsGenCmd["CLI::RbsGen\ndocscribe rbs\nGenerate RBS from YARD"]
-        SarifFormatter["CLI::Formatters::Sarif\nSARIF 2.1 JSON\nCode Scanning"]
-        ConfigBuilder["CLI::ConfigBuilder\nApply CLI overrides\nto config"]
-    end
-
-    subgraph Config["Configuration"]
-        ConfigClass["Config\nCentral config object\n· raw hash\n· query methods"]
-        Defaults["config/defaults.rb\nDEFAULT hash"]
-        Loader["config/loader.rb\nYAML loading\n+ deep merge"]
-        Emit["config/emit.rb\nEmission toggles\n(header, tags, etc.)"]
-        Filtering["config/filtering.rb\nFile/method\ninclude/exclude"]
-        RBSConfig["config/rbs.rb\nRBS provider\nfactory"]
-        SorbetConfig["config/sorbet.rb\nSorbet provider\nchain factory"]
-        PluginConfig["config/plugin.rb\nPlugin loading\nfrom YAML"]
-    end
+<img src="assets/diagrams/architecture.svg" alt="Docscribe architecture">
 
-    subgraph Parsing["Parsing"]
-        ParsingModule["Parsing\nBackend selection\n(:parser / :prism)"]
-        ParserGem["Parser gem\n(whitequark/parser)"]
-        Prism["Prism translator\n(Ruby 3.4+)"]
-    end
+Source: [assets/diagrams/architecture.mmd](assets/diagrams/architecture.mmd) — regenerate with `bash assets/diagrams/render.sh`.
 
-    subgraph Core["Core Engine"]
-        InlineRewriter["InlineRewriter\n· parse -> collect\n· deduplicate -> dispatch\n· rewrite"]
-        Collector["Collector\n< Parser::AST::Processor\nAST walker\n· find methods/attrs\n· track visibility\n· track containers"]
-        DocBuilder["DocBuilder\nGenerate YARD doc lines\n· combine inference\n· external signatures\n· plugin tags"]
-        DocBlock["DocBlock\nSafe strategy:\nparse -> merge -> sort\nexisting doc blocks"]
-        SourceHelpers["SourceHelpers\nPosition/range\nutilities"]
-    end
+### Data flow
 
-    subgraph Infer["Inference Engine"]
-        InferModule["Infer\nEntry point"]
-        Params["Infer::Params\nParameter type\nfrom name + default"]
-        Returns["Infer::Returns\nReturn type\nfrom method body"]
-        Raises["Infer::Raises\n@raise tags\nfrom raise/rescue"]
-        Literals["Infer::Literals\nAST literal ->\ntype string"]
-        Names["Infer::Names\n:const node ->\nFQN string"]
-        ASTWalk["Infer::ASTWalk\nRecursive DFS\nAST traversal"]
-    end
+<img src="assets/diagrams/dataflow.svg" alt="Docscribe data flow">
 
-    subgraph Plugins["Plugin System"]
-        PluginModule["Plugin\nTag/Collector\ndispatch"]
-        Registry["Plugin::Registry\nGlobal registry\n· register -> route\n· tag_entries\n· collector_entries"]
-        TagPlugin["Base::TagPlugin\nOverride #call(context)\n-> Array<Tag>"]
-        CollectorPlugin["Base::CollectorPlugin\nOverride #collect(ast, buffer)\n-> Array<Hash>"]
-        TagValue["Plugin::Tag\nStruct (name, text, types)"]
-        Context["Plugin::Context\nMethod snapshot struct"]
-    end
+Source: [assets/diagrams/dataflow.mmd](assets/diagrams/dataflow.mmd) — regenerate with `bash assets/diagrams/render.sh`.
 
-    subgraph Types["External Type System"]
-        ProviderChain["ProviderChain\nComposite:\nquery in order\nfirst match wins"]
-        RBSProvider["RBS::Provider\n.rbs files\n-> RBS lib"]
-        RBSFormatter["RBS::TypeFormatter\nRBS type ->\nYARD type string"]
-        RBSCollection["RBS::CollectionLoader\nrbs_collection\n.lock.yaml"]
-        SorbetBase["Sorbet::BaseProvider\nRBS::Prototype::RBI\nbridge"]
-        SorbetSource["Sorbet::SourceProvider\nInline sig{}\ndeclarations"]
-        SorbetRBI["Sorbet::RBIProvider\n.rbi files\ndirectories"]
-    end
+### IDE plugin and gem interaction
 
-    subgraph YardTypes["YARD Type Parser"]
-        YParser["Yard::Parser\nParse YARD type\nstrings -> AST"]
-        YFormatter["Yard::Formatter\nYARD AST ->\nRBS string"]
-        YTypes["Yard::Types\n9 AST node types\n(Named, Generic, etc.)"]
-    end
+<img src="assets/diagrams/plugin-gem.svg" alt="RubyMine plugin and gem interaction">
 
-    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
+Source: [assets/diagrams/plugin-gem.mmd](assets/diagrams/plugin-gem.mmd) — regenerate with `bash assets/diagrams/render.sh`.
 
-    Exe --> Run
-    Exe --> ServerDaemon
-    ThinClient --> ServerDaemon
-    ServerDaemon --> ConfigClass
-    ServerDaemon --> Cache
-    ServerDaemon --> InlineRewriter
-    Run --> Options
-    Run --> InitCmd
-    Run --> GenCmd
-    Run --> SigsCmd
-    Run --> RbsGenCmd
-    Run --> SarifFormatter
-    Run --> ConfigBuilder
-    ConfigBuilder --> ConfigClass
-    ConfigBuilder --> ServerDaemon
-    ConfigClass --> Defaults
-    ConfigClass --> Loader
-    ConfigClass --> Emit
-    ConfigClass --> Filtering
-    ConfigClass --> RBSConfig
-    ConfigClass --> SorbetConfig
-    ConfigClass --> PluginConfig
-    Run --> InlineRewriter
-    InlineRewriter --> ParsingModule
-    ParsingModule --> ParserGem
-    ParsingModule --> Prism
-    InlineRewriter --> Collector
-    Collector --> PluginModule
-    PluginModule --> Registry
-    Registry --> CollectorPlugin
-    InlineRewriter --> DocBuilder
-    DocBuilder --> InferModule
-    InferModule --> Params
-    InferModule --> Returns
-    InferModule --> Raises
-    Params --> Literals
-    Returns --> Literals
-    Raises --> ASTWalk
-    Raises --> Names
-    DocBuilder --> ProviderChain
-    ProviderChain --> SorbetSource
-    ProviderChain --> SorbetRBI
-    ProviderChain --> RBSProvider
-    SorbetSource --> SorbetBase
-    SorbetRBI --> SorbetBase
-    RBSProvider --> RBSFormatter
-    RBSProvider --> RBSCollection
-    DocBuilder --> PluginModule
-    PluginModule --> Registry
-    Registry --> TagPlugin
-    TagPlugin --> TagValue
-    TagPlugin --> Context
-    InlineRewriter --> DocBlock
-    InlineRewriter --> SourceHelpers
-    RbsGenCmd --> ParsingModule
-    RbsGenCmd --> YParser
-    YParser --> YTypes
-    YParser --> YFormatter
-```
+How it works, briefly: the IDE annotator collects file info on open/type/save, asks the gem daemon (`check` over Unix-socket JSON-RPC, CLI fallback), maps offenses to YARD tag lines with per-cop quick-fixes, and caches by file stamp + config hash. Daemon errors surface as file-level errors instead of silence; quick-fixes run `fix` or file-scoped `update_types`; workspace check aggregates `check_batch` into a balloon.
 
-### Data flow
+Version gates (plugin behavior by gem version):
 
-```mermaid
-flowchart LR
-    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"]
-    Collect --> Insertions["Insertion list\n(sorted by position)"]
-    CollectPlugins --> Insertions
-    Insertions --> Dedup["Deduplicate\n(override by position)"]
-    Dedup --> Build["DocBuilder.build_doc_lines\nper insertion"]
-    Build --> Infer["Infer params / returns / raises\n(heuristic fallback)"]
-    Build --> SigQuery["ProviderChain\nquery external types"]
-    Build --> TagPlugins["TagPlugin#call\n(add extra @tags)"]
-    Infer --> ResultDoc["Generated YARD doc block"]
-    SigQuery --> ResultDoc
-    TagPlugins --> ResultDoc
-    ResultDoc --> Strategy{"Strategy?"}
-    Strategy -->|Safe| Merge["DocBlock.merge\npreserve + append + sort"]
-    Strategy -->|Aggressive| Replace["Replace entirely"]
-    Merge --> Rewritten["Rewriter#process\n-> rewritten source"]
-    Replace --> Rewritten
-    Rewritten --> Result["Result / response"]
-    Rewritten --> CacheStorage
-    CacheStorage --> Socket
-    Result -->|Direct mode| Output["Modified .rb file / STDOUT"]
-    Result -->|Server mode| Socket
-```
+| Gem version | Plugin behavior                                             |
+|-------------|-------------------------------------------------------------|
+| `< 1.5.1`   | always CLI, no daemon mode                                  |
+| `< 1.5.2`   | no batch mode (workspace check scans the directory via CLI) |
+| `< 1.6.2`   | `update_types` falls back to CLI on unknown method          |
 
 ## CLI
 
@@ -371,7 +210,7 @@ docscribe init [options]
 docscribe generate [type] [name] [options]
 docscribe sigs [options] [files...]
 docscribe rbs [options] [files...]
-docscribe update_types [directory]
+docscribe update_types [directory|file] [options]
 docscribe check_for_comments [paths...]
 docscribe server [start|status|stop] [options]
 ```
@@ -437,6 +276,10 @@ If you pass no files and don't use `--stdin`, Docscribe processes the current di
 - `--format FORMAT`  
   Output format: `text` (default, human-readable), `json` (machine-readable, RuboCop-compatible), or `sarif` (SARIF 2.1
   JSON, compatible with GitHub Code Scanning).
+  Every JSON offense carries `cop_name`, `message`, `location`, plus machine-readable `type`
+  (`updated_return`, `missing_param`, ...) and, for type mismatches, `source` (`"rbs"`, `"infer"` or `"syntax"`).
+  Files are grouped by normalized path, so the same file passed under different spellings
+  (absolute, relative, symlinked) appears once.
 
 - `--rbs`  
   Use RBS signatures for `@param`/`@return` when available (falls back to inference).
@@ -450,6 +293,10 @@ If you pass no files and don't use `--stdin`, Docscribe processes the current di
 - `--rbi-dir DIR`  
   Add an Sorbet RBI directory (repeatable). Implies `--sorbet`.
 
+- `--[no-]validate-types`  
+  Validate YARD types against inferred/RBS types and report mismatches.
+  `--no-validate-types` overrides `validate_types: true` from the config file.
+
 - `--include PATTERN`  
   Include PATTERN (method id or file path; glob or `/regex/`).
 
@@ -611,21 +458,28 @@ end
 ### `docscribe update_types` — two-pass type-aware documentation update
 
 > [!NOTE]
-> `docscribe update_types` is a convenience alias for the two-pass workflow above. It requires Ruby 3.0+ and the `rbs`
-> gem (because of `--rbs-collection`). The RBS collection must be set up first with
-> `bundle exec rbs collection install`. Type accuracy depends on your RBS signatures — if signatures are incomplete or
-> missing, types will fall back to AST inference.
+> `docscribe update_types` is a convenience alias for the two-pass workflow above. RBS features require Ruby 3.0+ and
+> the `rbs` gem; pass `--no-rbs` to skip them. If `rbs.collection: true` is set in `docscribe.yml`, the collection is
+> discovered automatically (otherwise run `bundle exec rbs collection install` first). Type accuracy depends on your
+> RBS signatures — if signatures are incomplete or missing, types will fall back to AST inference.
 
-`docscribe update_types` runs two passes to bring both docs and RBS signatures up to date:
+`docscribe update_types` runs two passes to bring both docs and RBS signatures up to date. The target can be a
+directory **or a single file** (handy for IDE quick-fixes — only that file is touched):
 
 1. **Pass 1** — `docscribe -AkB --rbs-collection <dir>`: aggressively rebuilds doc blocks, preserves existing
    descriptions, suppresses boilerplate, uses RBS collection types.
 2. **Pass 2** — `docscribe -aB --rbs-collection <dir>`: safe merge cleanup with no boilerplate.
 
+Extra flags (`--rbs`, `--sig-dir DIR` (repeatable), `--rbs-collection`, `--[no-]validate-types`, `--no-rbs`) are
+passed through to both passes.
+
 ```shell
 # Update docs in lib/ using RBS collection
 docscribe update_types lib
 
+# Update a single file only
+docscribe update_types lib/user.rb
+
 # Defaults to current directory
 docscribe update_types
 ```
@@ -805,13 +659,17 @@ The daemon speaks JSON-RPC 2.0 over Unix socket. Each request is a JSON line, ea
 
 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`                                                |
+| 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                               |
+| `update_types` | `file` (string, optional), `dir` (string, optional; `file` wins)                    | `status`, `changed`, `changes`                          |
+| `ping`         | —                                                                                   | `version`, `pid`, `socket_path`, `started_at`, `uptime` |
+| `shutdown`     | —                                                                                   | `status`                                                |
+
+Each entry in `changes` carries `type`, `line`, `message` and, for type mismatches, `source` (`"rbs"`, `"infer"` or
+`"syntax"`) plus `param` where applicable — IDE plugins use `source` to pick the right fix (RBS update vs YARD fix).
 
 Error codes (standardized for IDE plugin integration):
 
@@ -931,11 +789,12 @@ Useful flag combinations for common workflows:
   projects.
 - `docscribe -a --sorbet --rbi-dir sorbet/rbi lib` — safe autocorrect using Sorbet RBI signatures.
 - `docscribe update_types lib` — two-pass type-aware update: aggressively rebuilds docs with kept descriptions and RBS
-  collection, then safe-merges to clean up.
+  collection, then safe-merges to clean up. Accepts a single file too: `docscribe update_types lib/user.rb`.
   See [docscribe update_types](#docscribe-update_types--two-pass-type-aware-documentation-update).
 
 > [!NOTE]
-> `docscribe update_types` is a convenient shortcut, but be aware it uses `--rbs-collection` under the hood.
+> `docscribe update_types` is a convenient shortcut, but be aware it uses `--rbs-collection` under the hood
+> (or `rbs.collection: true` from the config — then no flag is needed).
 > If your RBS signatures are incomplete, types may fall back to AST inference.
 
 ## Parser backend (Parser gem vs Prism)
@@ -1096,6 +955,13 @@ You can combine `--rbs-collection` with `--sig-dir` to mix gem signatures with y
 docscribe -a --rbs-collection --sig-dir sig lib
 ```
 
+If `rbs.collection: true` is set in `docscribe.yml`, the collection is discovered automatically and the flag
+can be omitted everywhere (including plain `check` and the daemon):
+
+```shell
+docscribe -a lib
+```
+
 > [!NOTE]
 > `--rbs-collection` only improves types for methods defined in gems that ship RBS
 > signatures. For your own classes, provide a `sig/` directory with hand-written or
@@ -1301,7 +1167,7 @@ Heuristics (best-effort).
 Parameters:
 
 - `*args` -> `Array`
-- `**kwargs` -> `Hash`
+- `**kwargs` -> `Hash[Symbol, untyped]` with RBS, `Hash<Symbol, Object>` in YARD, bare `Hash` from pure inference
 - `&block` -> `Proc`
 - keyword args:
     - `verbose: true` -> `Boolean`
@@ -1316,6 +1182,18 @@ Return values:
 - For simple bodies, Docscribe looks at the last expression or explicit `return`.
 - Unions with `nil` become optional types (e.g. `String` or `nil` -> `String?`).
 - For control flow (`if`/`case`), it unifies branches conservatively.
+- Blocks resolve to generics where possible: `map`/`then` over known elements give `Array<String>` instead of
+  bare `Array`; `arr << x` and `x += 1` resolve through RBS (`self`-returns stay `self`); `&.`/`||`/`()` receivers
+  are unwrapped before lookup; `each_with_index` chains infer `Enumerator`/`Hash` element types
+  (`arr.each_with_index.to_h { |x, i| [k, v] }` infers `Hash<K, V>` from the pair literal;
+  the second block parameter is always the `Integer` index).
+- Generic compatibility is structural, not textual: `Hash` matches `Hash<Symbol, Config>`, `Array` matches
+  `Array<String>`, `String?` equals `String, nil` and `String|nil`, and `String` is accepted where `Object` is
+  expected. YARD `[]` and RBS `<>` (plus `untyped`/`Object`) are normalized before comparison.
+- `void` understands Ruby idioms: initializers and `setup` may return `Hash`/`self`/`Boolean`, predicates
+  (`valid?`) may return `Boolean`.
+- One crashing method never blanks the whole file: the error goes to stderr (`Docscribe: skipping method foo ...`)
+  and the remaining methods are still processed.
 
 > [!TIP]
 > Docscribe resolves return types for core Ruby methods (`Integer#positive?`, `String#upcase`, etc.)
@@ -1340,6 +1218,9 @@ Docscribe detects exceptions and rescue branches:
 
 - Conditional return types for rescue branches:
     - Docscribe adds `@return [Type] if ExceptionA, ExceptionB` for each rescue clause
+    - Conditional tags never overwrite the main `@return` type, so `check` and `update_types` agree with each other
+      (no ping-pong between runs). Rescue bodies referencing constants resolve to the constant's value type when
+      the constant is visible from the method's scope.
 
 ## Visibility semantics
 
@@ -1889,6 +1770,7 @@ The generated file contains:
 |-------------------------------------------|------------|----------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|
 | `keep_descriptions`                       | `bool`     | `false`                                                                                      | Preserve existing doc text in aggressive mode                              |
 | `skip_anonymous_block_params`             | `bool`     | `false`                                                                                      | Skip `@param [Proc] block` for anonymous `&` params                        |
+| `validate_types`                          | `bool`     | `false`                                                                                      | Validate YARD types against inferred/RBS types and report mismatches       |
 | `emit.header`                             | `bool`     | `false`                                                                                      | Generate method header line (`+#foo+ -> ...`)                              |
 | `emit.include_default_message`            | `bool`     | `true`                                                                                       | Insert default message (`Method documentation.`)                           |
 | `emit.include_param_documentation`        | `bool`     | `true`                                                                                       | Insert param description text (`Param documentation.`)                     |
@@ -1998,6 +1880,7 @@ yard doc -o docs
 - Safe mode only merges into existing **doc-like** comment blocks. Ordinary comments that are not recognized as
   documentation are preserved and treated conservatively.
 - Type inference is heuristic. Complex flows and meta-programming will fall back to `Object` or best-effort types.
+- A method that crashes documentation generation is skipped with a stderr warning instead of failing the whole file.
 - Aggressive mode (`-A`) replaces existing doc blocks and should be reviewed carefully.
 
 ## Roadmap

data/exe/docscribe-client

@@ -13,7 +13,8 @@ SOCKET_DIR = begin
   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
+ENV_FILES = %w[Gemfile.lock rbs_collection.lock.yaml docscribe.yml].freeze
+SIG_RBS_GLOB = 'sig/**/*.rbs'
 
 def socket_path(config_path = nil)
   seed = +Dir.pwd
@@ -27,13 +28,27 @@ def socket_path(config_path = nil)
 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
+  parts = ENV_FILES.map { |file| env_file_mtime(file) }
+  parts.concat(sig_env_parts)
   Digest::MD5.hexdigest(parts.join(':'))
 end
 
+def env_file_mtime(file)
+  path = File.join(Dir.pwd, file)
+  File.exist?(path) ? File.mtime(path).to_f.to_s : '0'
+end
+
+def sig_env_parts
+  files = sig_files
+  mtimes = files.map { |p| File.mtime(p).to_f.to_s }
+  mtimes << files.size.to_s
+  mtimes
+end
+
+def sig_files
+  Dir.glob(File.join(Dir.pwd, SIG_RBS_GLOB)).sort
+end
+
 def config_hash(config_path)
   resolved = File.expand_path(config_path)
   mtime = File.exist?(resolved) ? File.mtime(resolved).to_f : 0.0
@@ -141,8 +156,12 @@ when :ping
   puts JSON.generate(result || { error: 'Connection failed' })
 when :status
   alive = begin
-    File.exist?(sock) &&
-      UNIXSocket.new(sock).close && true
+    if File.exist?(sock)
+      UNIXSocket.new(sock).close
+      true
+    else
+      false
+    end
   rescue StandardError
     false
   end

data/lib/docscribe/cli/config_builder.rb

@@ -22,13 +22,14 @@ module Docscribe
       # @param [Hash<Symbol, Object>] options parsed CLI options
       # @return [Docscribe::Config] merged effective config
       def build(base, options)
-        return base unless needs_override?(options)
+        return warn_and_return_base(base, options) unless needs_override?(options)
 
         raw = Marshal.load(Marshal.dump(base.raw))
         apply_filter_overrides(raw, options)
         apply_rbs_overrides(raw, options) if rbs_overrides?(options)
         apply_sorbet_overrides(raw, options) if sorbet_overrides?(options)
         apply_output_overrides(raw, options)
+        apply_validation_overrides(raw, options) if validation_overrides?(options)
         conf = Docscribe::Config.new(config_path: base.config_path, **raw)
         warn_missing_rbs_collection(conf, options)
         conf
@@ -43,7 +44,21 @@ module Docscribe
         filter_overrides?(options) ||
           rbs_overrides?(options) ||
           sorbet_overrides?(options) ||
-          output_overrides?(options)
+          output_overrides?(options) ||
+          validation_overrides?(options)
+      end
+
+      # Warn about a missing collection opt-in and return the base config unchanged.
+      #
+      # Used when no CLI override is present so the nudge still fires on plain runs.
+      #
+      # @note module_function: defines #warn_and_return_base (visibility: private)
+      # @param [Docscribe::Config] base base config loaded from YAML/defaults
+      # @param [Hash<Symbol, Object>] options parsed CLI options
+      # @return [Docscribe::Config] base config unchanged
+      def warn_and_return_base(base, options)
+        warn_missing_rbs_collection(base, options)
+        base
       end
 
       # Whether any method or file filter CLI options were provided.
@@ -195,6 +210,25 @@ module Docscribe
         raw['emit']['include_param_documentation'] = false if options[:no_boilerplate]
       end
 
+      # Whether any validation-related CLI options were provided.
+      #
+      # @note module_function: defines #validation_overrides? (visibility: private)
+      # @param [Hash<Symbol, Object>] options parsed CLI options
+      # @return [Boolean]
+      def validation_overrides?(options)
+        !options[:validate_types].nil?
+      end
+
+      # Apply validation-related CLI overrides to the raw config.
+      #
+      # @note module_function: defines #apply_validation_overrides (visibility: private)
+      # @param [Hash<String, Object>] raw raw config hash
+      # @param [Hash<Symbol, Object>] options parsed CLI options
+      # @return [void]
+      def apply_validation_overrides(raw, options)
+        raw['validate_types'] = options[:validate_types]
+      end
+
       # Warn when rbs_collection.lock.yaml exists but --rbs-collection was not passed.
       #
       # The warning can be suppressed by setting `rbs.warn_missing_collection: false`
@@ -206,6 +240,7 @@ module Docscribe
       # @return [void]
       def warn_missing_rbs_collection(conf, options)
         return if options[:rbs_collection]
+        return if conf.raw.dig('rbs', 'collection')
         return unless conf.rbs_warn_missing_collection?
         return unless File.exist?('rbs_collection.lock.yaml')
 

data/lib/docscribe/cli/coverage.rb

@@ -172,7 +172,7 @@ module Docscribe
         end
 
         # @private
-        # @param [Object] node
+        # @param [Parser::AST::Node] node
         # @param [Docscribe::CLI::Coverage::CoverageStats] stats
         # @param [String] src
         # @return [void]
@@ -185,7 +185,7 @@ module Docscribe
         end
 
         # @private
-        # @param [Object] node
+        # @param [Parser::AST::Node] node
         # @param [Docscribe::CLI::Coverage::CoverageStats] stats
         # @param [String] src
         # @return [void]
@@ -202,7 +202,7 @@ module Docscribe
         end
 
         # @private
-        # @param [Object] node
+        # @param [Parser::AST::Node] node
         # @param [Docscribe::CLI::Coverage::CoverageStats] stats
         # @param [String] doc_comment
         # @return [void]
@@ -218,7 +218,7 @@ module Docscribe
         end
 
         # @private
-        # @param [Object] node
+        # @param [Parser::AST::Node] node
         # @param [Docscribe::CLI::Coverage::CoverageStats] stats
         # @return [void]
         def count_method_params(node, stats)
@@ -226,7 +226,7 @@ module Docscribe
         end
 
         # @private
-        # @param [Object] node
+        # @param [Parser::AST::Node] node
         # @return [Integer]
         def count_params(node)
           args_node = node.children[2] || node.children[1]