docscribe 1.6.1 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +258 -51
  3. data/exe/docscribe-client +26 -7
  4. data/lib/docscribe/cli/config_builder.rb +69 -8
  5. data/lib/docscribe/cli/config_dump.rb +88 -7
  6. data/lib/docscribe/cli/coverage.rb +5 -5
  7. data/lib/docscribe/cli/formatters/json.rb +74 -29
  8. data/lib/docscribe/cli/formatters/sarif.rb +20 -3
  9. data/lib/docscribe/cli/options.rb +36 -2
  10. data/lib/docscribe/cli/rbs_gen.rb +4 -4
  11. data/lib/docscribe/cli/run.rb +297 -52
  12. data/lib/docscribe/cli/update_types.rb +61 -17
  13. data/lib/docscribe/cli.rb +19 -13
  14. data/lib/docscribe/config/defaults.rb +2 -0
  15. data/lib/docscribe/config/plugin.rb +4 -4
  16. data/lib/docscribe/config/rbs.rb +30 -12
  17. data/lib/docscribe/config/sorbet.rb +3 -1
  18. data/lib/docscribe/config/template.rb +6 -0
  19. data/lib/docscribe/config/utils.rb +15 -0
  20. data/lib/docscribe/config/validation.rb +34 -0
  21. data/lib/docscribe/config.rb +35 -1
  22. data/lib/docscribe/infer/behavior.rb +13 -13
  23. data/lib/docscribe/infer/params.rb +2 -2
  24. data/lib/docscribe/infer/raises.rb +5 -6
  25. data/lib/docscribe/infer/returns.rb +1642 -151
  26. data/lib/docscribe/infer.rb +7 -7
  27. data/lib/docscribe/inline_rewriter/doc_builder.rb +551 -102
  28. data/lib/docscribe/inline_rewriter.rb +367 -98
  29. data/lib/docscribe/plugin/registry.rb +1 -0
  30. data/lib/docscribe/server/base.rb +73 -21
  31. data/lib/docscribe/server/client.rb +20 -11
  32. data/lib/docscribe/server/daemon.rb +209 -23
  33. data/lib/docscribe/server/protocol.rb +4 -4
  34. data/lib/docscribe/types/primitive.rb +160 -0
  35. data/lib/docscribe/types/rbs/provider.rb +5 -2
  36. data/lib/docscribe/types/sorbet/base_provider.rb +33 -1
  37. data/lib/docscribe/types/yard/formatter.rb +35 -6
  38. data/lib/docscribe/types/yard/parser.rb +32 -22
  39. data/lib/docscribe/types/yard/repair.rb +142 -0
  40. data/lib/docscribe/types/yard/validator.rb +131 -0
  41. data/lib/docscribe/validator/generic_compatibility.rb +698 -0
  42. data/lib/docscribe/validator/type_mismatch_validator.rb +287 -0
  43. data/lib/docscribe/version.rb +1 -1
  44. metadata +9 -3
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 24df08456004986c5cae869a2e7dc9ba4a1176cbf5dbaaca679cb4661836a3dc
4
- data.tar.gz: 746d064972fe321f6b0d7459d87f1fc4cec8c414b4b4b73b9cce916f72b4139d
3
+ metadata.gz: 58018ff6ce9cc837ebe99189ccf04770567d4ca922f9a970c6157e81df7e0374
4
+ data.tar.gz: 8356662fe2fbd4fc3e6e9c94ff5c77c10700f8afa9159aaecf0feebcf29e8a2d
5
5
  SHA512:
6
- metadata.gz: 4cf1ba70c9a43ec923abda6c16bbd599b287803fd9c6968b0e4c0ea87079fd8d1dd95317f7a20715f6664a7a1876da46cf008b3f6c21fc115237592b041f29b2
7
- data.tar.gz: 0e7e994de57e167edf3a47b3d92ad1c123cb2decf973d137fcc7ac0bcd33f869fc380abd2d2705a2820d09837bce012b12f2f7efc2bbf0fe679da226040e43fb
6
+ metadata.gz: a26b97d57f0440c84ebc0a3148ab654790ffc47559dd304a595bb30c7aceb4c9ebf220e90060cf84506f95919257d50fff164dadaea000be971be5e3e65fc71c
7
+ data.tar.gz: 2976adfbd46d61f7488a80c65d23b7519de358742f55fcd96a3d913f35f85f9836d2e020d9b8c7d9087a0238df468d30625196a1b3d1d0a234b599f93a7e21df
data/README.md CHANGED
@@ -78,6 +78,7 @@ docscribe -A lib
78
78
  * [Installation](#installation)
79
79
  * [Architecture](#architecture)
80
80
  * [Data flow](#data-flow)
81
+ * [IDE plugin and gem interaction](#ide-plugin-and-gem-interaction)
81
82
  * [CLI](#cli)
82
83
  * [Exit codes](#exit-codes)
83
84
  * [Options](#options)
@@ -167,9 +168,9 @@ Requires Ruby 2.7+.
167
168
  ## Architecture
168
169
 
169
170
  Docscribe is organized into several subsystems. The CLI layer receives user input and orchestrates configuration
170
- loading, then delegates to the core engine which parses source code, collects methods (using an AST walker), builds YARD
171
- doc lines — combining heuristic type inference, external RBS/Sorbet signatures, and plugin output — and finally rewrites
172
- the source via a strategy (safe merge or aggressive replace).
171
+ loading. It then delegates to the core engine, which parses source code and collects methods using an AST walker. From
172
+ there it builds YARD doc lines, combining heuristic type inference, external RBS/Sorbet signatures, and plugin output.
173
+ Finally, it rewrites the source via a strategy: safe merge or aggressive replace.
173
174
 
174
175
  In server mode, a persistent daemon (`docscribe server`) keeps the runtime loaded and caches parsed results across
175
176
  invocations via an LRU cache, enabling near-instant repeated checks for IDE plugins. A thin client (`docscribe-client`)
@@ -181,10 +182,17 @@ flowchart TB
181
182
  Exe["exe/docscribe\nEntry point"]
182
183
  Run["CLI::Run\nMain execution\n· expand paths\n· iterate files\n· report results"]
183
184
  Options["CLI::Options\nARGV parsing\n(mode, strategy,\nfilters, flags)"]
185
+ CLIDispatch["CLI.dispatch_subcommand"]
184
186
  InitCmd["CLI::Init\ndocscribe init\nGenerate config"]
185
187
  GenCmd["CLI::Generate\ndocscribe generate\nScaffold plugins"]
186
188
  SigsCmd["CLI::Sigs\ndocscribe sigs\nCheck RBS coverage"]
187
189
  RbsGenCmd["CLI::RbsGen\ndocscribe rbs\nGenerate RBS from YARD"]
190
+ UpdateTypesCmd["CLI::UpdateTypes\ntwo-pass rebuild"]
191
+ ConfigDumpCmd["CLI::ConfigDump\ndocscribe config\n· resolved config\n· --only-changed\n· --format yaml/json/text"]
192
+ CoverageCmd["CLI::Coverage\ndocscribe coverage\nDocumentation coverage\n· text / json report"]
193
+ CheckCommentsCmd["CLI::CheckForComments\ndocscribe check_for_comments"]
194
+ ServerCmd["CLI::ServerCmd\ndocscribe server"]
195
+ JsonFormatter["CLI::Formatters::Json\nJSON offenses\n(type, source)"]
188
196
  SarifFormatter["CLI::Formatters::Sarif\nSARIF 2.1 JSON\nCode Scanning"]
189
197
  ConfigBuilder["CLI::ConfigBuilder\nApply CLI overrides\nto config"]
190
198
  end
@@ -198,6 +206,9 @@ flowchart TB
198
206
  RBSConfig["config/rbs.rb\nRBS provider\nfactory"]
199
207
  SorbetConfig["config/sorbet.rb\nSorbet provider\nchain factory"]
200
208
  PluginConfig["config/plugin.rb\nPlugin loading\nfrom YAML"]
209
+ ValidateCfg["config/validation.rb\nvalidate_types?"]
210
+ SortingCfg["config/sorting.rb\nsort_tags / tag_order"]
211
+ TemplateCfg["config/template.rb\ndefault YAML"]
201
212
  end
202
213
 
203
214
  subgraph Parsing["Parsing"]
@@ -210,12 +221,16 @@ flowchart TB
210
221
  InlineRewriter["InlineRewriter\n· parse -> collect\n· deduplicate -> dispatch\n· rewrite"]
211
222
  Collector["Collector\n< Parser::AST::Processor\nAST walker\n· find methods/attrs\n· track visibility\n· track containers"]
212
223
  DocBuilder["DocBuilder\nGenerate YARD doc lines\n· combine inference\n· external signatures\n· plugin tags"]
224
+ ValidSvc["Validator\nGenericCompatibility +\nTypeMismatchValidator"]
225
+ RunFork["CLI::Run parallel path\n· --parallel / --jobs N\n· warm env once, then fork\n· COW-inherited RBS env\n· sequential fallback\n when fork absent"]
213
226
  DocBlock["DocBlock\nSafe strategy:\nparse -> merge -> sort\nexisting doc blocks"]
214
227
  SourceHelpers["SourceHelpers\nPosition/range\nutilities"]
215
228
  end
216
229
 
217
230
  subgraph Infer["Inference Engine"]
218
231
  InferModule["Infer\nEntry point"]
232
+ InferBehavior["Infer::Behavior"]
233
+ InferConsts["Infer::Constants"]
219
234
  Params["Infer::Params\nParameter type\nfrom name + default"]
220
235
  Returns["Infer::Returns\nReturn type\nfrom method body"]
221
236
  Raises["Infer::Raises\n@raise tags\nfrom raise/rescue"]
@@ -230,7 +245,7 @@ flowchart TB
230
245
  TagPlugin["Base::TagPlugin\nOverride #call(context)\n-> Array<Tag>"]
231
246
  CollectorPlugin["Base::CollectorPlugin\nOverride #collect(ast, buffer)\n-> Array<Hash>"]
232
247
  TagValue["Plugin::Tag\nStruct (name, text, types)"]
233
- Context["Plugin::Context\nMethod snapshot struct"]
248
+ Context["Plugin::Context\nMethod snapshot struct\nnode/container/scope/\nvisibility/method/params/return/source"]
234
249
  end
235
250
 
236
251
  subgraph Types["External Type System"]
@@ -241,35 +256,51 @@ flowchart TB
241
256
  SorbetBase["Sorbet::BaseProvider\nRBS::Prototype::RBI\nbridge"]
242
257
  SorbetSource["Sorbet::SourceProvider\nInline sig{}\ndeclarations"]
243
258
  SorbetRBI["Sorbet::RBIProvider\n.rbi files\ndirectories"]
259
+ OverloadSel["OverloadSelector"]
244
260
  end
245
261
 
246
262
  subgraph YardTypes["YARD Type Parser"]
247
263
  YParser["Yard::Parser\nParse YARD type\nstrings -> AST"]
248
264
  YFormatter["Yard::Formatter\nYARD AST ->\nRBS string"]
249
265
  YTypes["Yard::Types\n9 AST node types\n(Named, Generic, etc.)"]
266
+ YRepair["Yard::Repair\nRepair whitespace-split\ntype names\n([Sym bol] -> [Symbol])\nonly known primitives"]
250
267
  end
251
268
 
252
269
  subgraph Server["Server / Daemon"]
253
- ThinClient["exe/docscribe-client\nThin client\n· socket send/receive\n· no gem load"]
254
- ServerDaemon["Server::Daemon\nSocket listener\n· check / fix / shutdown\n· JSON-RPC 2.0"]
255
- Cache["Docscribe::LRUCache\nFile result cache\n(max 1000, by mtime)"]
270
+ ThinClient["exe/docscribe-client\nThin client\n· socket send/receive\n· no gem load\nexcept --ensure"]
271
+ ServerDaemon["Server::Daemon\nSocket listener\n· check / fix / check_batch\n· update_types / ping / shutdown\n· JSON-RPC 2.0"]
272
+ Cache["Docscribe::LRUCache\nFile result cache\n(max 1000, key [file, strategy])\nhit = mtime== AND sig_hash=="]
256
273
  end
257
274
 
258
275
  Exe --> Run
259
- Exe --> ServerDaemon
276
+ Exe --> CLIDispatch
277
+ Exe --> ServerCmd
278
+ ServerCmd --> ServerDaemon
279
+ CLIDispatch --> Run
280
+ CLIDispatch --> InitCmd
281
+ CLIDispatch --> GenCmd
282
+ CLIDispatch --> SigsCmd
283
+ CLIDispatch --> RbsGenCmd
284
+ CLIDispatch --> ConfigDumpCmd
285
+ CLIDispatch --> CoverageCmd
286
+ CLIDispatch --> CheckCommentsCmd
260
287
  ThinClient --> ServerDaemon
261
288
  ServerDaemon --> ConfigClass
262
289
  ServerDaemon --> Cache
263
290
  ServerDaemon --> InlineRewriter
264
- Run --> Options
265
- Run --> InitCmd
266
- Run --> GenCmd
267
- Run --> SigsCmd
268
- Run --> RbsGenCmd
291
+ Options --> Run
292
+ Run --> JsonFormatter
269
293
  Run --> SarifFormatter
270
294
  Run --> ConfigBuilder
295
+ Run --> UpdateTypesCmd
296
+ Run --> RunFork
297
+ RunFork --> InlineRewriter
298
+ ConfigDumpCmd --> ConfigClass
299
+ ConfigDumpCmd --> Options
300
+ CoverageCmd --> InlineRewriter
301
+ ConfigBuilder --> ValidationOverrides["validation overrides\n(validate_types,\nwarn_invalid_yard)"]
302
+ ValidationOverrides --> ConfigClass
271
303
  ConfigBuilder --> ConfigClass
272
- ConfigBuilder --> ServerDaemon
273
304
  ConfigClass --> Defaults
274
305
  ConfigClass --> Loader
275
306
  ConfigClass --> Emit
@@ -277,6 +308,9 @@ flowchart TB
277
308
  ConfigClass --> RBSConfig
278
309
  ConfigClass --> SorbetConfig
279
310
  ConfigClass --> PluginConfig
311
+ ConfigClass --> ValidateCfg
312
+ ConfigClass --> SortingCfg
313
+ ConfigClass --> TemplateCfg
280
314
  Run --> InlineRewriter
281
315
  InlineRewriter --> ParsingModule
282
316
  ParsingModule --> ParserGem
@@ -287,6 +321,9 @@ flowchart TB
287
321
  Registry --> CollectorPlugin
288
322
  InlineRewriter --> DocBuilder
289
323
  DocBuilder --> InferModule
324
+ DocBuilder --> ValidSvc
325
+ InferModule --> InferBehavior
326
+ InferModule --> InferConsts
290
327
  InferModule --> Params
291
328
  InferModule --> Returns
292
329
  InferModule --> Raises
@@ -295,6 +332,7 @@ flowchart TB
295
332
  Raises --> ASTWalk
296
333
  Raises --> Names
297
334
  DocBuilder --> ProviderChain
335
+ ProviderChain --> OverloadSel
298
336
  ProviderChain --> SorbetSource
299
337
  ProviderChain --> SorbetRBI
300
338
  ProviderChain --> RBSProvider
@@ -313,15 +351,31 @@ flowchart TB
313
351
  RbsGenCmd --> YParser
314
352
  YParser --> YTypes
315
353
  YParser --> YFormatter
354
+ DocBuilder --> YRepair
355
+ YRepair --> YParser
316
356
  ```
317
357
 
358
+ Source: [assets/diagrams/architecture.mmd](assets/diagrams/architecture.mmd) — GitHub renders this block directly; `bash assets/diagrams/render.sh` produces SVG for viewers without Mermaid support.
359
+
318
360
  ### Data flow
319
361
 
320
362
  ```mermaid
321
363
  flowchart LR
322
364
  subgraph Entry["Entry Points"]
323
365
  Direct["docscribe lib\n(no --server)"]
366
+ Parallel["docscribe --parallel\n/ --jobs N"]
324
367
  ViaServer["docscribe --server\nor docscribe-client"]
368
+ UpdateTypesFlow["update_types\ntwo-pass: aggressive → safe"]
369
+ end
370
+
371
+ subgraph Fork["Forked Workers (1.7.0+)"]
372
+ JobCount["parallel_job_count\n--jobs > DOCSCRIBE_THREADS\n> CPU count"]
373
+ ForkCheck{"Process.respond_to?\n(:fork)?"}
374
+ Warm["warm_rewrite_env\n· load gems\n· build RBS provider\n· rewrite one file"]
375
+ Split["split_paths\ncontiguous slices"]
376
+ Children["fork() per slice\ninherit warm env (COW)"]
377
+ Fallback["sequential\n(identical results)"]
378
+ Gather["merge_forked_slices\nMarshal payload over pipe\nmerge_state under mutex"]
325
379
  end
326
380
 
327
381
  subgraph Daemon["Server Daemon (Unix Socket)"]
@@ -331,21 +385,36 @@ flowchart LR
331
385
  ApplyOverrides["apply_cli_overrides\n(reset on nil)"]
332
386
  end
333
387
 
388
+ Parallel --> JobCount
389
+ JobCount --> ForkCheck
390
+ ForkCheck -->|yes| Warm
391
+ ForkCheck -->|no| Fallback
392
+ Warm --> Split
393
+ Split --> Children
394
+ Children --> Parse
395
+ Fallback --> Parse
396
+ Children --> Gather
397
+ Gather --> Output
334
398
  ViaServer --> Socket
335
399
  Socket --> ApplyOverrides
336
400
  ApplyOverrides --> CacheCheck
337
401
  CacheCheck -->|Hit| Socket
338
402
  CacheCheck -->|Miss| Parse
339
403
  Direct --> Parse
404
+ Entry --> UpdateTypesFlow
405
+ UpdateTypesFlow --> Parse
340
406
  Parse["Parsing.parse_buffer\nParser gem / Prism"]
341
- Parse --> AST["AST + Comments"]
407
+ Parse --> AST["AST"]
408
+ AST -.-> CommentScan["comment scan\n(buffer text)"]
342
409
  AST --> Collect["Collector.process\n· Find methods\n· Track visibility\n· Find attr_*"]
343
410
  AST --> CollectPlugins["CollectorPlugin#collect\n· Custom AST walks\n· Non-standard constructs"]
344
- Collect --> Insertions["Insertion list\n(sorted by position)"]
411
+ Collect --> Insertions["Insertion list\n(sorted by position)\n(sort_by pos at dispatch)"]
345
412
  CollectPlugins --> Insertions
346
413
  Insertions --> Dedup["Deduplicate\n(override by position)"]
347
- Dedup --> Build["DocBuilder.build_doc_lines\nper insertion"]
348
- Build --> Infer["Infer params / returns / raises\n(heuristic fallback)"]
414
+ Dedup --> Build["DocBuilder.build\n(entry point)\nper insertion"]
415
+ Build -.-> RescueNote["per-method rescue:\nerror to stderr,\nrest applies"]
416
+ Build --> TypeGuard["warn_invalid_yard gate\n· invalid_yard_type?\n· Repair known names\n· else report invalid_type"]
417
+ TypeGuard --> Infer["Infer params / returns / raises\n(heuristic fallback)"]
349
418
  Build --> SigQuery["ProviderChain\nquery external types"]
350
419
  Build --> TagPlugins["TagPlugin#call\n(add extra @tags)"]
351
420
  Infer --> ResultDoc["Generated YARD doc block"]
@@ -354,15 +423,78 @@ flowchart LR
354
423
  ResultDoc --> Strategy{"Strategy?"}
355
424
  Strategy -->|Safe| Merge["DocBlock.merge\npreserve + append + sort"]
356
425
  Strategy -->|Aggressive| Replace["Replace entirely"]
357
- Merge --> Rewritten["Rewriter#process\n-> rewritten source"]
426
+ Merge --> Rewritten["TreeRewriter#process\n(Parser::Source)\n-> rewritten source"]
358
427
  Replace --> Rewritten
359
428
  Rewritten --> Result["Result / response"]
360
429
  Rewritten --> CacheStorage
361
430
  CacheStorage --> Socket
362
- Result -->|Direct mode| Output["Modified .rb file / STDOUT"]
431
+ Result -.-> ExitCodes["exit codes:\n0 ok / 1 changes / 2 error"]
432
+ Children -.-> Progress["--progress\nstderr, per child"]
433
+ Result -->|Direct mode| Output["write-mode: file\ncheck: STDOUT summary"]
363
434
  Result -->|Server mode| Socket
364
435
  ```
365
436
 
437
+ Source: [assets/diagrams/dataflow.mmd](assets/diagrams/dataflow.mmd) — regenerate with `bash assets/diagrams/render.sh`.
438
+
439
+ ### IDE plugin and gem interaction
440
+
441
+ ```mermaid
442
+ sequenceDiagram
443
+ autonumber
444
+ participant U as User / IDE
445
+ participant A as DocscribeAnnotator<br/>(ExternalAnnotator)
446
+ participant R as Runner<br/>(DocscribeDaemon)
447
+ participant D as Gem daemon<br/>(Unix socket, JSON-RPC 2.0)
448
+ participant E as Engine<br/>(InlineRewriter)
449
+ Note over A: open / type / save (.rb, .rake, Rakefile)
450
+ A ->> A: collectInformation (EDT)<br/>filters, unsaved-skip (non-RBS),<br/>configHash w/o I/O, PSI stamp
451
+ U ->> A: background pass
452
+ A ->> A: doAnnotate - generation++<br/>bgConfigHash + rbsHash(sig/**)
453
+ A ->> A: cache get (project, file, hash)<br/>+ stamp check
454
+ alt cache hit (incl. empty = clean)
455
+ A ->> U: apply cached / null (no gem call)
456
+ else cache miss
457
+ A ->> A: saveDocument (so daemon sees disk)
458
+ A ->> R: executeWithFallback(check)<br/>RunOptions(file, CHECK, json)
459
+ R ->> R: ensureRunning - socket alive?<br/>gem 1.5.1 or newer? ruby/SDK resolve<br/>start ruby -e (15s timeout)
460
+ alt daemon OK
461
+ R ->> D: check {file, project_dir,<br/>no_boilerplate, cli_overrides?}
462
+ Note over R, D: cli_overrides - rbs / rbs_collection<br/>(RbsDetector) + validate_types (setting)
463
+ D ->> E: rewrite_with_report (safe)
464
+ E ->> D: changes[] {type, line, method,<br/>message, source?}
465
+ D ->> R: {status ok/fail, changed, changes}
466
+ R ->> R: buildCheckJson to parseJson
467
+ else daemon down / RPC null
468
+ R ->> R: CLI fallback - bundle exec<br/>docscribe --format json file
469
+ end
470
+ R ->> A: RunResult(success, exit, stdout, stderr)
471
+ A ->> A: generation still current?<br/>else discard (null)
472
+ alt success is false
473
+ A ->> A: synthetic Docscribe/Error at 1:1<br/>do NOT cache
474
+ else blank stdout
475
+ A ->> A: empty result (legit clean, cache it)
476
+ else parsed
477
+ A ->> A: cache put (non-error only)
478
+ end
479
+ A ->> U: apply - line = findYardTagLine<br/>(at-param/at-return above def)<br/>WARNING squiggle + fix by cop<br/>Updated to UpdateTypes<br/>InvalidType to Fix YARD (local)<br/>other to safe Fix / Error no fix
480
+ end
481
+
482
+ Note over U, R: Quick-fix (bulb) - save to fix {strategy}<br/>or update_types {dir} (whole project)<br/>refresh + balloon. Check action -<br/>same check, balloon with counts.
483
+ Note over U, R: Workspace - menu to collectRubyFiles<br/>chunks of 10 to check_batch {files}<br/>aggregate balloon only (no squigglies -<br/>error files counted, not shown)
484
+ ```
485
+
486
+ Source: [assets/diagrams/plugin-gem.mmd](assets/diagrams/plugin-gem.mmd) — regenerate with `bash assets/diagrams/render.sh`.
487
+
488
+ 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.
489
+
490
+ Version gates (plugin behavior by gem version):
491
+
492
+ | Gem version | Plugin behavior |
493
+ |-------------|-------------------------------------------------------------|
494
+ | `< 1.5.1` | always CLI, no daemon mode |
495
+ | `< 1.5.2` | no batch mode (workspace check scans the directory via CLI) |
496
+ | `< 1.6.2` | `update_types` falls back to CLI on unknown method |
497
+
366
498
  ## CLI
367
499
 
368
500
  ```shell
@@ -371,7 +503,7 @@ docscribe init [options]
371
503
  docscribe generate [type] [name] [options]
372
504
  docscribe sigs [options] [files...]
373
505
  docscribe rbs [options] [files...]
374
- docscribe update_types [directory]
506
+ docscribe update_types [directory|file] [options]
375
507
  docscribe check_for_comments [paths...]
376
508
  docscribe server [start|status|stop] [options]
377
509
  ```
@@ -413,8 +545,19 @@ If you pass no files and don't use `--stdin`, Docscribe processes the current di
413
545
  - `--progress`
414
546
  Show progress (`[N/total] path/to/file.rb`) on stderr as each file is processed.
415
547
 
416
- - `DOCSCRIBE_THREADS` (env var)
417
- Number of parallel worker threads (default: 4). Set to `1` for sequential processing.
548
+ - `--parallel`
549
+ Process files in parallel using forked worker processes. Each worker inherits
550
+ the warmed process (gems, config, RBS environment) through copy-on-write, so
551
+ forking skips the cold-start cost that made thread-based work slower than a
552
+ sequential run.
553
+
554
+ - `--jobs N`
555
+ Number of parallel workers (implies `--parallel`). Defaults to the number of
556
+ available CPUs.
557
+
558
+ - `DOCSCRIBE_THREADS` (env var)
559
+ Default worker count when `--jobs` is not passed. Falls back to the CPU count.
560
+ Set to `1` for sequential processing.
418
561
 
419
562
  - `--quiet` (`-q`)
420
563
  Only show status, no details (suppresses change reasons).
@@ -437,6 +580,10 @@ If you pass no files and don't use `--stdin`, Docscribe processes the current di
437
580
  - `--format FORMAT`
438
581
  Output format: `text` (default, human-readable), `json` (machine-readable, RuboCop-compatible), or `sarif` (SARIF 2.1
439
582
  JSON, compatible with GitHub Code Scanning).
583
+ Every JSON offense carries `cop_name`, `message`, `location`, plus machine-readable `type`
584
+ (`updated_return`, `missing_param`, ...) and, for type mismatches, `source` (`"rbs"`, `"infer"` or `"syntax"`).
585
+ Files are grouped by normalized path, so the same file passed under different spellings
586
+ (absolute, relative, symlinked) appears once.
440
587
 
441
588
  - `--rbs`
442
589
  Use RBS signatures for `@param`/`@return` when available (falls back to inference).
@@ -450,6 +597,17 @@ If you pass no files and don't use `--stdin`, Docscribe processes the current di
450
597
  - `--rbi-dir DIR`
451
598
  Add an Sorbet RBI directory (repeatable). Implies `--sorbet`.
452
599
 
600
+ - `--[no-]validate-types`
601
+ Validate YARD types against inferred/RBS types and report mismatches.
602
+ `--no-validate-types` overrides `validate_types: true` from the config file.
603
+
604
+ - `--[no-]warn-invalid-yard`
605
+ Report syntactically broken YARD types such as `[Sym bol]` and apply the safe fix to
606
+ `[Symbol]`. Enabled by default. Independent of `--validate-types`: syntax validity does
607
+ not depend on inferred or external types. `--no-warn-invalid-yard` silences it and
608
+ leaves broken types untouched. `--no-warn-invalid-yard` overrides
609
+ `warn_invalid_yard: true` from the config file.
610
+
453
611
  - `--include PATTERN`
454
612
  Include PATTERN (method id or file path; glob or `/regex/`).
455
613
 
@@ -598,34 +756,43 @@ end
598
756
 
599
757
  ```shell
600
758
  docscribe rbs lib
601
- # Generated sig/user.rbs
759
+ # Generated sig/lib/user.rbs
602
760
  ```
603
761
 
604
762
  ```ruby.rbs
605
- # sig/user.rbs
763
+ # sig/lib/user.rbs
606
764
  class User
607
- def initialize: (String name, Integer age) -> User
765
+ def initialize: (String name, Integer age) -> User
608
766
  end
609
767
  ```
610
768
 
769
+ The output path mirrors the source path relative to the working directory, so `lib/user.rb`becomes `sig/lib/user.rbs` (not `sig/user.rbs`).
770
+
611
771
  ### `docscribe update_types` — two-pass type-aware documentation update
612
772
 
613
773
  > [!NOTE]
614
- > `docscribe update_types` is a convenience alias for the two-pass workflow above. It requires Ruby 3.0+ and the `rbs`
615
- > gem (because of `--rbs-collection`). The RBS collection must be set up first with
616
- > `bundle exec rbs collection install`. Type accuracy depends on your RBS signatures — if signatures are incomplete or
617
- > missing, types will fall back to AST inference.
774
+ > `docscribe update_types` is a convenience alias for the two-pass workflow above. RBS features require Ruby 3.0+ and
775
+ > the `rbs` gem; pass `--no-rbs` to skip them. If `rbs.collection: true` is set in `docscribe.yml`, the collection is
776
+ > discovered automatically (otherwise run `bundle exec rbs collection install` first). Type accuracy depends on your
777
+ > RBS signatures — if signatures are incomplete or missing, types will fall back to AST inference.
618
778
 
619
- `docscribe update_types` runs two passes to bring both docs and RBS signatures up to date:
779
+ `docscribe update_types` runs two passes to bring both docs and RBS signatures up to date. The target can be a
780
+ directory **or a single file** (handy for IDE quick-fixes — only that file is touched):
620
781
 
621
782
  1. **Pass 1** — `docscribe -AkB --rbs-collection <dir>`: aggressively rebuilds doc blocks, preserves existing
622
783
  descriptions, suppresses boilerplate, uses RBS collection types.
623
784
  2. **Pass 2** — `docscribe -aB --rbs-collection <dir>`: safe merge cleanup with no boilerplate.
624
785
 
786
+ Extra flags (`--rbs`, `--sig-dir DIR` (repeatable), `--rbs-collection`, `--[no-]validate-types`, `--no-rbs`) are
787
+ passed through to both passes.
788
+
625
789
  ```shell
626
790
  # Update docs in lib/ using RBS collection
627
791
  docscribe update_types lib
628
792
 
793
+ # Update a single file only
794
+ docscribe update_types lib/user.rb
795
+
629
796
  # Defaults to current directory
630
797
  docscribe update_types
631
798
  ```
@@ -659,17 +826,22 @@ about your project and writes a tailored configuration.
659
826
  # Create docscribe.yml interactively
660
827
  docscribe init
661
828
 
662
- # Create with default settings (non-interactive)
663
- docscribe init --default
829
+ # Write the default config without prompting
830
+ docscribe init --force
831
+
832
+ # Print the template to stdout instead of writing a file
833
+ docscribe init --stdout
664
834
  ```
665
835
 
666
836
  **Flags:**
667
837
 
838
+ - `--config PATH` — where to write the config (default: `docscribe.yml`).
839
+ - `-f`, `--force` — overwrite if the file already exists.
840
+ - `--stdout` — print the config template to stdout instead of writing a file.
668
841
  - `--pre-commit` — generate and install a Git pre-commit hook that checks documentation on staged `.rb` files using
669
842
  `docscribe --verbose`. The hook exits with a warning if staged files lack documentation.
670
843
  - `--pre-commit --uninstall` — remove the pre-commit hook.
671
844
  - `--pre-commit --dry-run` — preview the hook script without installing.
672
- - `--default` — skip interactive prompts, write default config.
673
845
  - `-h`, `--help` — show help.
674
846
 
675
847
  ### `docscribe config` — view resolved configuration
@@ -805,13 +977,17 @@ The daemon speaks JSON-RPC 2.0 over Unix socket. Each request is a JSON line, ea
805
977
 
806
978
  Methods:
807
979
 
808
- | Method | Parameters | Result |
809
- |---------------|-------------------------------------------------------------------------------------|---------------------------------------------------------|
810
- | `check` | `file` (string), `strategy` ("safe"/"aggressive"), `cli_overrides` (hash, optional) | `status`, `changed`, `changes` |
811
- | `fix` | same as `check` | `status`, `changed`, `changes` |
812
- | `check_batch` | `files` (array of strings), `strategy`, `cli_overrides`, `timeout` (int, optional) | array of per-file results |
813
- | `ping` | — | `version`, `pid`, `socket_path`, `started_at`, `uptime` |
814
- | `shutdown` | — | `status` |
980
+ | Method | Parameters | Result |
981
+ |----------------|-------------------------------------------------------------------------------------|---------------------------------------------------------|
982
+ | `check` | `file` (string), `strategy` ("safe"/"aggressive"), `cli_overrides` (hash, optional) | `status`, `changed`, `changes` |
983
+ | `fix` | same as `check` | `status`, `changed`, `changes` |
984
+ | `check_batch` | `files` (array of strings), `strategy`, `cli_overrides`, `timeout` (int, optional) | array of per-file results |
985
+ | `update_types` | `file` (string, optional), `dir` (string, optional; `file` wins) | `status`, `changed`, `changes` |
986
+ | `ping` | — | `version`, `pid`, `socket_path`, `started_at`, `uptime` |
987
+ | `shutdown` | — | `status` |
988
+
989
+ Each entry in `changes` carries `type`, `line`, `message` and, for type mismatches, `source` (`"rbs"`, `"infer"` or
990
+ `"syntax"`) plus `param` where applicable — IDE plugins use `source` to pick the right fix (RBS update vs YARD fix).
815
991
 
816
992
  Error codes (standardized for IDE plugin integration):
817
993
 
@@ -906,7 +1082,8 @@ In write modes:
906
1082
 
907
1083
  > [!IMPORTANT]
908
1084
  > The `M` marker only appears when `--rbs` or `--sorbet` is enabled, since type mismatches are detected by
909
- > comparing external signatures against inferred types.
1085
+ > comparing external signatures against inferred types. It also requires `--no-validate-types`: with
1086
+ > `validate_types` on (the default) a signature mismatch is reported as a fixable difference (`F`), not as `M`.
910
1087
 
911
1088
  With `--verbose`, Docscribe prints per-file statuses instead; type mismatches show as `MT` with the specific difference.
912
1089
 
@@ -931,11 +1108,12 @@ Useful flag combinations for common workflows:
931
1108
  projects.
932
1109
  - `docscribe -a --sorbet --rbi-dir sorbet/rbi lib` — safe autocorrect using Sorbet RBI signatures.
933
1110
  - `docscribe update_types lib` — two-pass type-aware update: aggressively rebuilds docs with kept descriptions and RBS
934
- collection, then safe-merges to clean up.
1111
+ collection, then safe-merges to clean up. Accepts a single file too: `docscribe update_types lib/user.rb`.
935
1112
  See [docscribe update_types](#docscribe-update_types--two-pass-type-aware-documentation-update).
936
1113
 
937
1114
  > [!NOTE]
938
- > `docscribe update_types` is a convenient shortcut, but be aware it uses `--rbs-collection` under the hood.
1115
+ > `docscribe update_types` is a convenient shortcut, but be aware it uses `--rbs-collection` under the hood
1116
+ > (or `rbs.collection: true` from the config — then no flag is needed).
939
1117
  > If your RBS signatures are incomplete, types may fall back to AST inference.
940
1118
 
941
1119
  ## Parser backend (Parser gem vs Prism)
@@ -1045,7 +1223,8 @@ class Demo
1045
1223
  end
1046
1224
  ```
1047
1225
 
1048
- Generated docs will prefer the RBS signature over inferred Ruby types:
1226
+ Generated docs will prefer the RBS signature over inferred Ruby types (`emit.header: true`
1227
+ in the example below adds the `+#foo+ -> ...` header line; it is off by default):
1049
1228
 
1050
1229
  ```ruby
1051
1230
  class Demo
@@ -1096,6 +1275,13 @@ You can combine `--rbs-collection` with `--sig-dir` to mix gem signatures with y
1096
1275
  docscribe -a --rbs-collection --sig-dir sig lib
1097
1276
  ```
1098
1277
 
1278
+ If `rbs.collection: true` is set in `docscribe.yml`, the collection is discovered automatically and the flag
1279
+ can be omitted everywhere (including plain `check` and the daemon):
1280
+
1281
+ ```shell
1282
+ docscribe -a lib
1283
+ ```
1284
+
1099
1285
  > [!NOTE]
1100
1286
  > `--rbs-collection` only improves types for methods defined in gems that ship RBS
1101
1287
  > signatures. For your own classes, provide a `sig/` directory with hand-written or
@@ -1155,7 +1341,8 @@ class Demo
1155
1341
  end
1156
1342
  ```
1157
1343
 
1158
- Docscribe will use the Sorbet signature instead of the inferred body type:
1344
+ Docscribe will use the Sorbet signature instead of the inferred body type (`emit.header: true`, off by default, adds the
1345
+ header line):
1159
1346
 
1160
1347
  ```ruby
1161
1348
  class Demo
@@ -1228,7 +1415,7 @@ class Demo
1228
1415
  end
1229
1416
  ```
1230
1417
 
1231
- Example output:
1418
+ Example output (with `emit.header: true`; off by default):
1232
1419
 
1233
1420
  ```ruby
1234
1421
  # demo.rb
@@ -1301,7 +1488,7 @@ Heuristics (best-effort).
1301
1488
  Parameters:
1302
1489
 
1303
1490
  - `*args` -> `Array`
1304
- - `**kwargs` -> `Hash`
1491
+ - `**kwargs` -> `Hash[Symbol, untyped]` with RBS, `Hash<Symbol, Object>` in YARD, bare `Hash` from pure inference
1305
1492
  - `&block` -> `Proc`
1306
1493
  - keyword args:
1307
1494
  - `verbose: true` -> `Boolean`
@@ -1316,6 +1503,18 @@ Return values:
1316
1503
  - For simple bodies, Docscribe looks at the last expression or explicit `return`.
1317
1504
  - Unions with `nil` become optional types (e.g. `String` or `nil` -> `String?`).
1318
1505
  - For control flow (`if`/`case`), it unifies branches conservatively.
1506
+ - Blocks resolve to generics where possible: `map`/`then` over known elements give `Array<String>` instead of
1507
+ bare `Array`; `arr << x` and `x += 1` resolve through RBS (`self`-returns stay `self`); `&.`/`||`/`()` receivers
1508
+ are unwrapped before lookup; `each_with_index` chains infer `Enumerator`/`Hash` element types
1509
+ (`arr.each_with_index.to_h { |x, i| [k, v] }` infers `Hash<K, V>` from the pair literal;
1510
+ the second block parameter is always the `Integer` index).
1511
+ - Generic compatibility is structural, not textual: `Hash` matches `Hash<Symbol, Config>`, `Array` matches
1512
+ `Array<String>`, `String?` equals `String, nil` and `String|nil`, and `String` is accepted where `Object` is
1513
+ expected. YARD `[]` and RBS `<>` (plus `untyped`/`Object`) are normalized before comparison.
1514
+ - `void` understands Ruby idioms: initializers and `setup` may return `Hash`/`self`/`Boolean`, predicates
1515
+ (`valid?`) may return `Boolean`.
1516
+ - One crashing method never blanks the whole file: the error goes to stderr (`Docscribe: skipping method foo ...`)
1517
+ and the remaining methods are still processed.
1319
1518
 
1320
1519
  > [!TIP]
1321
1520
  > Docscribe resolves return types for core Ruby methods (`Integer#positive?`, `String#upcase`, etc.)
@@ -1340,6 +1539,9 @@ Docscribe detects exceptions and rescue branches:
1340
1539
 
1341
1540
  - Conditional return types for rescue branches:
1342
1541
  - Docscribe adds `@return [Type] if ExceptionA, ExceptionB` for each rescue clause
1542
+ - Conditional tags never overwrite the main `@return` type, so `check` and `update_types` agree with each other
1543
+ (no ping-pong between runs). Rescue bodies referencing constants resolve to the constant's value type when
1544
+ the constant is visible from the method's scope.
1343
1545
 
1344
1546
  ## Visibility semantics
1345
1547
 
@@ -1562,7 +1764,9 @@ plugins:
1562
1764
  - ./docscribe_plugins
1563
1765
  ```
1564
1766
 
1565
- Each entry is passed to `require`. The path is expanded relative to the current working directory.
1767
+ Each entry is passed to `require`. A relative path is expanded from the directory holding
1768
+ `docscribe.yml` (not from the current working directory), so the plugin resolves the same way
1769
+ no matter where you invoke `docscribe` from.
1566
1770
 
1567
1771
  Duck typing is also supported — any object responding to `#call` is treated as a `TagPlugin`, any object responding to
1568
1772
  `#collect` is treated as a `CollectorPlugin`:
@@ -1685,7 +1889,7 @@ docscribe --exclude-file '/^spec\//' lib
1685
1889
 
1686
1890
  > [!NOTE]
1687
1891
  > `/regex/` passed to `--include`/`--exclude` is treated as a **method-id** pattern. Use `--include-file` /
1688
- `--exclude-file` for file regex filters.
1892
+ > `--exclude-file` for file regex filters.
1689
1893
 
1690
1894
  Enable attribute-style documentation generation with:
1691
1895
 
@@ -1883,12 +2087,14 @@ The generated file contains:
1883
2087
  ### Full configuration reference
1884
2088
 
1885
2089
  <details>
1886
- <summary>Click to expand — 43 config keys</summary>
2090
+ <summary>Click to expand — 44 config keys</summary>
1887
2091
 
1888
2092
  | Key | Type | Default | Description |
1889
2093
  |-------------------------------------------|------------|----------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|
1890
2094
  | `keep_descriptions` | `bool` | `false` | Preserve existing doc text in aggressive mode |
1891
2095
  | `skip_anonymous_block_params` | `bool` | `false` | Skip `@param [Proc] block` for anonymous `&` params |
2096
+ | `validate_types` | `bool` | `true` | Validate YARD types against inferred/RBS types and report mismatches |
2097
+ | `warn_invalid_yard` | `bool` | `true` | Report syntactically broken YARD types (e.g. `[Sym bol]`) |
1892
2098
  | `emit.header` | `bool` | `false` | Generate method header line (`+#foo+ -> ...`) |
1893
2099
  | `emit.include_default_message` | `bool` | `true` | Insert default message (`Method documentation.`) |
1894
2100
  | `emit.include_param_documentation` | `bool` | `true` | Insert param description text (`Param documentation.`) |
@@ -1998,6 +2204,7 @@ yard doc -o docs
1998
2204
  - Safe mode only merges into existing **doc-like** comment blocks. Ordinary comments that are not recognized as
1999
2205
  documentation are preserved and treated conservatively.
2000
2206
  - Type inference is heuristic. Complex flows and meta-programming will fall back to `Object` or best-effort types.
2207
+ - A method that crashes documentation generation is skipped with a stderr warning instead of failing the whole file.
2001
2208
  - Aggressive mode (`-A`) replaces existing doc blocks and should be reviewed carefully.
2002
2209
 
2003
2210
  ## Roadmap