docscribe 1.6.2 → 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.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 3c7164ab1529448e4446137381b717690e22d57ced3cf9042be38ab00ff5f470
4
- data.tar.gz: 7dc01723974b29fe8a6179220d04ffe3c9141e471c3ec1fbed309b9e5a780a5e
3
+ metadata.gz: 58018ff6ce9cc837ebe99189ccf04770567d4ca922f9a970c6157e81df7e0374
4
+ data.tar.gz: 8356662fe2fbd4fc3e6e9c94ff5c77c10700f8afa9159aaecf0feebcf29e8a2d
5
5
  SHA512:
6
- metadata.gz: cee99e8d318b327bc64786555c0347cc995e6a23d5fb42863c13efda6e6467bdc5032bd37f1a7b518ca3f4c41c5967034f278664f0b9ee1110d712f01011f000
7
- data.tar.gz: 59ab6f4b18a349fc9e40c3b39f85dd331c76f606bb9162ff410b11e40338f9a3e3d05e8ab002e345c6ef3be47a1ee524cc9d12649ce7d0a7deb149c376c6edd5
6
+ metadata.gz: a26b97d57f0440c84ebc0a3148ab654790ffc47559dd304a595bb30c7aceb4c9ebf220e90060cf84506f95919257d50fff164dadaea000be971be5e3e65fc71c
7
+ data.tar.gz: 2976adfbd46d61f7488a80c65d23b7519de358742f55fcd96a3d913f35f85f9836d2e020d9b8c7d9087a0238df468d30625196a1b3d1d0a234b599f93a7e21df
data/README.md CHANGED
@@ -168,27 +168,320 @@ Requires Ruby 2.7+.
168
168
  ## Architecture
169
169
 
170
170
  Docscribe is organized into several subsystems. The CLI layer receives user input and orchestrates configuration
171
- loading, then delegates to the core engine which parses source code, collects methods (using an AST walker), builds YARD
172
- doc lines — combining heuristic type inference, external RBS/Sorbet signatures, and plugin output — and finally rewrites
173
- 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.
174
174
 
175
175
  In server mode, a persistent daemon (`docscribe server`) keeps the runtime loaded and caches parsed results across
176
176
  invocations via an LRU cache, enabling near-instant repeated checks for IDE plugins. A thin client (`docscribe-client`)
177
177
  provides minimal-overhead socket communication without loading the full gem.
178
178
 
179
- <img src="assets/diagrams/architecture.svg" alt="Docscribe architecture">
179
+ ```mermaid
180
+ flowchart TB
181
+ subgraph CLI["CLI Layer"]
182
+ Exe["exe/docscribe\nEntry point"]
183
+ Run["CLI::Run\nMain execution\n· expand paths\n· iterate files\n· report results"]
184
+ Options["CLI::Options\nARGV parsing\n(mode, strategy,\nfilters, flags)"]
185
+ CLIDispatch["CLI.dispatch_subcommand"]
186
+ InitCmd["CLI::Init\ndocscribe init\nGenerate config"]
187
+ GenCmd["CLI::Generate\ndocscribe generate\nScaffold plugins"]
188
+ SigsCmd["CLI::Sigs\ndocscribe sigs\nCheck RBS coverage"]
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)"]
196
+ SarifFormatter["CLI::Formatters::Sarif\nSARIF 2.1 JSON\nCode Scanning"]
197
+ ConfigBuilder["CLI::ConfigBuilder\nApply CLI overrides\nto config"]
198
+ end
199
+
200
+ subgraph Config["Configuration"]
201
+ ConfigClass["Config\nCentral config object\n· raw hash\n· query methods"]
202
+ Defaults["config/defaults.rb\nDEFAULT hash"]
203
+ Loader["config/loader.rb\nYAML loading\n+ deep merge"]
204
+ Emit["config/emit.rb\nEmission toggles\n(header, tags, etc.)"]
205
+ Filtering["config/filtering.rb\nFile/method\ninclude/exclude"]
206
+ RBSConfig["config/rbs.rb\nRBS provider\nfactory"]
207
+ SorbetConfig["config/sorbet.rb\nSorbet provider\nchain factory"]
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"]
212
+ end
213
+
214
+ subgraph Parsing["Parsing"]
215
+ ParsingModule["Parsing\nBackend selection\n(:parser / :prism)"]
216
+ ParserGem["Parser gem\n(whitequark/parser)"]
217
+ Prism["Prism translator\n(Ruby 3.4+)"]
218
+ end
219
+
220
+ subgraph Core["Core Engine"]
221
+ InlineRewriter["InlineRewriter\n· parse -> collect\n· deduplicate -> dispatch\n· rewrite"]
222
+ Collector["Collector\n< Parser::AST::Processor\nAST walker\n· find methods/attrs\n· track visibility\n· track containers"]
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"]
226
+ DocBlock["DocBlock\nSafe strategy:\nparse -> merge -> sort\nexisting doc blocks"]
227
+ SourceHelpers["SourceHelpers\nPosition/range\nutilities"]
228
+ end
229
+
230
+ subgraph Infer["Inference Engine"]
231
+ InferModule["Infer\nEntry point"]
232
+ InferBehavior["Infer::Behavior"]
233
+ InferConsts["Infer::Constants"]
234
+ Params["Infer::Params\nParameter type\nfrom name + default"]
235
+ Returns["Infer::Returns\nReturn type\nfrom method body"]
236
+ Raises["Infer::Raises\n@raise tags\nfrom raise/rescue"]
237
+ Literals["Infer::Literals\nAST literal ->\ntype string"]
238
+ Names["Infer::Names\n:const node ->\nFQN string"]
239
+ ASTWalk["Infer::ASTWalk\nRecursive DFS\nAST traversal"]
240
+ end
241
+
242
+ subgraph Plugins["Plugin System"]
243
+ PluginModule["Plugin\nTag/Collector\ndispatch"]
244
+ Registry["Plugin::Registry\nGlobal registry\n· register -> route\n· tag_entries\n· collector_entries"]
245
+ TagPlugin["Base::TagPlugin\nOverride #call(context)\n-> Array<Tag>"]
246
+ CollectorPlugin["Base::CollectorPlugin\nOverride #collect(ast, buffer)\n-> Array<Hash>"]
247
+ TagValue["Plugin::Tag\nStruct (name, text, types)"]
248
+ Context["Plugin::Context\nMethod snapshot struct\nnode/container/scope/\nvisibility/method/params/return/source"]
249
+ end
250
+
251
+ subgraph Types["External Type System"]
252
+ ProviderChain["ProviderChain\nComposite:\nquery in order\nfirst match wins"]
253
+ RBSProvider["RBS::Provider\n.rbs files\n-> RBS lib"]
254
+ RBSFormatter["RBS::TypeFormatter\nRBS type ->\nYARD type string"]
255
+ RBSCollection["RBS::CollectionLoader\nrbs_collection\n.lock.yaml"]
256
+ SorbetBase["Sorbet::BaseProvider\nRBS::Prototype::RBI\nbridge"]
257
+ SorbetSource["Sorbet::SourceProvider\nInline sig{}\ndeclarations"]
258
+ SorbetRBI["Sorbet::RBIProvider\n.rbi files\ndirectories"]
259
+ OverloadSel["OverloadSelector"]
260
+ end
261
+
262
+ subgraph YardTypes["YARD Type Parser"]
263
+ YParser["Yard::Parser\nParse YARD type\nstrings -> AST"]
264
+ YFormatter["Yard::Formatter\nYARD AST ->\nRBS string"]
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"]
267
+ end
268
+
269
+ subgraph Server["Server / Daemon"]
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=="]
273
+ end
180
274
 
181
- Source: [assets/diagrams/architecture.mmd](assets/diagrams/architecture.mmd) — regenerate with `bash assets/diagrams/render.sh`.
275
+ Exe --> Run
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
287
+ ThinClient --> ServerDaemon
288
+ ServerDaemon --> ConfigClass
289
+ ServerDaemon --> Cache
290
+ ServerDaemon --> InlineRewriter
291
+ Options --> Run
292
+ Run --> JsonFormatter
293
+ Run --> SarifFormatter
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
303
+ ConfigBuilder --> ConfigClass
304
+ ConfigClass --> Defaults
305
+ ConfigClass --> Loader
306
+ ConfigClass --> Emit
307
+ ConfigClass --> Filtering
308
+ ConfigClass --> RBSConfig
309
+ ConfigClass --> SorbetConfig
310
+ ConfigClass --> PluginConfig
311
+ ConfigClass --> ValidateCfg
312
+ ConfigClass --> SortingCfg
313
+ ConfigClass --> TemplateCfg
314
+ Run --> InlineRewriter
315
+ InlineRewriter --> ParsingModule
316
+ ParsingModule --> ParserGem
317
+ ParsingModule --> Prism
318
+ InlineRewriter --> Collector
319
+ Collector --> PluginModule
320
+ PluginModule --> Registry
321
+ Registry --> CollectorPlugin
322
+ InlineRewriter --> DocBuilder
323
+ DocBuilder --> InferModule
324
+ DocBuilder --> ValidSvc
325
+ InferModule --> InferBehavior
326
+ InferModule --> InferConsts
327
+ InferModule --> Params
328
+ InferModule --> Returns
329
+ InferModule --> Raises
330
+ Params --> Literals
331
+ Returns --> Literals
332
+ Raises --> ASTWalk
333
+ Raises --> Names
334
+ DocBuilder --> ProviderChain
335
+ ProviderChain --> OverloadSel
336
+ ProviderChain --> SorbetSource
337
+ ProviderChain --> SorbetRBI
338
+ ProviderChain --> RBSProvider
339
+ SorbetSource --> SorbetBase
340
+ SorbetRBI --> SorbetBase
341
+ RBSProvider --> RBSFormatter
342
+ RBSProvider --> RBSCollection
343
+ DocBuilder --> PluginModule
344
+ PluginModule --> Registry
345
+ Registry --> TagPlugin
346
+ TagPlugin --> TagValue
347
+ TagPlugin --> Context
348
+ InlineRewriter --> DocBlock
349
+ InlineRewriter --> SourceHelpers
350
+ RbsGenCmd --> ParsingModule
351
+ RbsGenCmd --> YParser
352
+ YParser --> YTypes
353
+ YParser --> YFormatter
354
+ DocBuilder --> YRepair
355
+ YRepair --> YParser
356
+ ```
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.
182
359
 
183
360
  ### Data flow
184
361
 
185
- <img src="assets/diagrams/dataflow.svg" alt="Docscribe data flow">
362
+ ```mermaid
363
+ flowchart LR
364
+ subgraph Entry["Entry Points"]
365
+ Direct["docscribe lib\n(no --server)"]
366
+ Parallel["docscribe --parallel\n/ --jobs N"]
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"]
379
+ end
380
+
381
+ subgraph Daemon["Server Daemon (Unix Socket)"]
382
+ Socket["Daemon#listen_loop\nJSON-RPC 2.0 dispatch"]
383
+ CacheCheck{"File cached &\nmtime fresh?"}
384
+ CacheStorage["LRUCache\n(1000 entries)"]
385
+ ApplyOverrides["apply_cli_overrides\n(reset on nil)"]
386
+ end
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
398
+ ViaServer --> Socket
399
+ Socket --> ApplyOverrides
400
+ ApplyOverrides --> CacheCheck
401
+ CacheCheck -->|Hit| Socket
402
+ CacheCheck -->|Miss| Parse
403
+ Direct --> Parse
404
+ Entry --> UpdateTypesFlow
405
+ UpdateTypesFlow --> Parse
406
+ Parse["Parsing.parse_buffer\nParser gem / Prism"]
407
+ Parse --> AST["AST"]
408
+ AST -.-> CommentScan["comment scan\n(buffer text)"]
409
+ AST --> Collect["Collector.process\n· Find methods\n· Track visibility\n· Find attr_*"]
410
+ AST --> CollectPlugins["CollectorPlugin#collect\n· Custom AST walks\n· Non-standard constructs"]
411
+ Collect --> Insertions["Insertion list\n(sorted by position)\n(sort_by pos at dispatch)"]
412
+ CollectPlugins --> Insertions
413
+ Insertions --> Dedup["Deduplicate\n(override by position)"]
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)"]
418
+ Build --> SigQuery["ProviderChain\nquery external types"]
419
+ Build --> TagPlugins["TagPlugin#call\n(add extra @tags)"]
420
+ Infer --> ResultDoc["Generated YARD doc block"]
421
+ SigQuery --> ResultDoc
422
+ TagPlugins --> ResultDoc
423
+ ResultDoc --> Strategy{"Strategy?"}
424
+ Strategy -->|Safe| Merge["DocBlock.merge\npreserve + append + sort"]
425
+ Strategy -->|Aggressive| Replace["Replace entirely"]
426
+ Merge --> Rewritten["TreeRewriter#process\n(Parser::Source)\n-> rewritten source"]
427
+ Replace --> Rewritten
428
+ Rewritten --> Result["Result / response"]
429
+ Rewritten --> CacheStorage
430
+ CacheStorage --> Socket
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"]
434
+ Result -->|Server mode| Socket
435
+ ```
186
436
 
187
437
  Source: [assets/diagrams/dataflow.mmd](assets/diagrams/dataflow.mmd) — regenerate with `bash assets/diagrams/render.sh`.
188
438
 
189
439
  ### IDE plugin and gem interaction
190
440
 
191
- <img src="assets/diagrams/plugin-gem.svg" alt="RubyMine plugin and gem interaction">
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
+ ```
192
485
 
193
486
  Source: [assets/diagrams/plugin-gem.mmd](assets/diagrams/plugin-gem.mmd) — regenerate with `bash assets/diagrams/render.sh`.
194
487
 
@@ -252,8 +545,19 @@ If you pass no files and don't use `--stdin`, Docscribe processes the current di
252
545
  - `--progress`
253
546
  Show progress (`[N/total] path/to/file.rb`) on stderr as each file is processed.
254
547
 
255
- - `DOCSCRIBE_THREADS` (env var)
256
- 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.
257
561
 
258
562
  - `--quiet` (`-q`)
259
563
  Only show status, no details (suppresses change reasons).
@@ -297,6 +601,13 @@ If you pass no files and don't use `--stdin`, Docscribe processes the current di
297
601
  Validate YARD types against inferred/RBS types and report mismatches.
298
602
  `--no-validate-types` overrides `validate_types: true` from the config file.
299
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
+
300
611
  - `--include PATTERN`
301
612
  Include PATTERN (method id or file path; glob or `/regex/`).
302
613
 
@@ -445,16 +756,18 @@ end
445
756
 
446
757
  ```shell
447
758
  docscribe rbs lib
448
- # Generated sig/user.rbs
759
+ # Generated sig/lib/user.rbs
449
760
  ```
450
761
 
451
762
  ```ruby.rbs
452
- # sig/user.rbs
763
+ # sig/lib/user.rbs
453
764
  class User
454
- def initialize: (String name, Integer age) -> User
765
+ def initialize: (String name, Integer age) -> User
455
766
  end
456
767
  ```
457
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
+
458
771
  ### `docscribe update_types` — two-pass type-aware documentation update
459
772
 
460
773
  > [!NOTE]
@@ -513,17 +826,22 @@ about your project and writes a tailored configuration.
513
826
  # Create docscribe.yml interactively
514
827
  docscribe init
515
828
 
516
- # Create with default settings (non-interactive)
517
- 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
518
834
  ```
519
835
 
520
836
  **Flags:**
521
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.
522
841
  - `--pre-commit` — generate and install a Git pre-commit hook that checks documentation on staged `.rb` files using
523
842
  `docscribe --verbose`. The hook exits with a warning if staged files lack documentation.
524
843
  - `--pre-commit --uninstall` — remove the pre-commit hook.
525
844
  - `--pre-commit --dry-run` — preview the hook script without installing.
526
- - `--default` — skip interactive prompts, write default config.
527
845
  - `-h`, `--help` — show help.
528
846
 
529
847
  ### `docscribe config` — view resolved configuration
@@ -764,7 +1082,8 @@ In write modes:
764
1082
 
765
1083
  > [!IMPORTANT]
766
1084
  > The `M` marker only appears when `--rbs` or `--sorbet` is enabled, since type mismatches are detected by
767
- > 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`.
768
1087
 
769
1088
  With `--verbose`, Docscribe prints per-file statuses instead; type mismatches show as `MT` with the specific difference.
770
1089
 
@@ -904,7 +1223,8 @@ class Demo
904
1223
  end
905
1224
  ```
906
1225
 
907
- 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):
908
1228
 
909
1229
  ```ruby
910
1230
  class Demo
@@ -1021,7 +1341,8 @@ class Demo
1021
1341
  end
1022
1342
  ```
1023
1343
 
1024
- 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):
1025
1346
 
1026
1347
  ```ruby
1027
1348
  class Demo
@@ -1094,7 +1415,7 @@ class Demo
1094
1415
  end
1095
1416
  ```
1096
1417
 
1097
- Example output:
1418
+ Example output (with `emit.header: true`; off by default):
1098
1419
 
1099
1420
  ```ruby
1100
1421
  # demo.rb
@@ -1443,7 +1764,9 @@ plugins:
1443
1764
  - ./docscribe_plugins
1444
1765
  ```
1445
1766
 
1446
- 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.
1447
1770
 
1448
1771
  Duck typing is also supported — any object responding to `#call` is treated as a `TagPlugin`, any object responding to
1449
1772
  `#collect` is treated as a `CollectorPlugin`:
@@ -1566,7 +1889,7 @@ docscribe --exclude-file '/^spec\//' lib
1566
1889
 
1567
1890
  > [!NOTE]
1568
1891
  > `/regex/` passed to `--include`/`--exclude` is treated as a **method-id** pattern. Use `--include-file` /
1569
- `--exclude-file` for file regex filters.
1892
+ > `--exclude-file` for file regex filters.
1570
1893
 
1571
1894
  Enable attribute-style documentation generation with:
1572
1895
 
@@ -1764,13 +2087,14 @@ The generated file contains:
1764
2087
  ### Full configuration reference
1765
2088
 
1766
2089
  <details>
1767
- <summary>Click to expand — 43 config keys</summary>
2090
+ <summary>Click to expand — 44 config keys</summary>
1768
2091
 
1769
2092
  | Key | Type | Default | Description |
1770
2093
  |-------------------------------------------|------------|----------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|
1771
2094
  | `keep_descriptions` | `bool` | `false` | Preserve existing doc text in aggressive mode |
1772
2095
  | `skip_anonymous_block_params` | `bool` | `false` | Skip `@param [Proc] block` for anonymous `&` params |
1773
- | `validate_types` | `bool` | `false` | Validate YARD types against inferred/RBS types and report mismatches |
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]`) |
1774
2098
  | `emit.header` | `bool` | `false` | Generate method header line (`+#foo+ -> ...`) |
1775
2099
  | `emit.include_default_message` | `bool` | `true` | Insert default message (`Method documentation.`) |
1776
2100
  | `emit.include_param_documentation` | `bool` | `true` | Insert param description text (`Param documentation.`) |
@@ -26,7 +26,7 @@ module Docscribe
26
26
 
27
27
  raw = Marshal.load(Marshal.dump(base.raw))
28
28
  apply_filter_overrides(raw, options)
29
- apply_rbs_overrides(raw, options) if rbs_overrides?(options)
29
+ apply_rbs_overrides(raw, options, base) if rbs_overrides?(options)
30
30
  apply_sorbet_overrides(raw, options) if sorbet_overrides?(options)
31
31
  apply_output_overrides(raw, options)
32
32
  apply_validation_overrides(raw, options) if validation_overrides?(options)
@@ -130,15 +130,16 @@ module Docscribe
130
130
  # @note module_function: defines #apply_rbs_overrides (visibility: private)
131
131
  # @param [Hash<String, Object>] raw raw config hash
132
132
  # @param [Hash<Symbol, Object>] options parsed CLI options
133
+ # @param [Docscribe::Config] base base config whose root anchors collection lookup
133
134
  # @return [void]
134
- def apply_rbs_overrides(raw, options)
135
+ def apply_rbs_overrides(raw, options, base)
135
136
  raw['rbs'] ||= {}
136
137
  raw['rbs']['enabled'] = true
137
138
  raw['rbs']['sig_dirs'] = Array(raw['rbs']['sig_dirs']) + options[:sig_dirs] if options[:sig_dirs].any?
138
139
 
139
140
  return unless options[:rbs_collection]
140
141
 
141
- apply_rbs_collection(raw)
142
+ apply_rbs_collection(raw, base)
142
143
  end
143
144
 
144
145
  # Whether any Sorbet-related CLI options were provided.
@@ -153,12 +154,16 @@ module Docscribe
153
154
 
154
155
  # Resolve and apply the RBS collection path into the raw config hash.
155
156
  #
157
+ # The lock file is looked up in the config root so that `-C other/dir/docscribe.yml`
158
+ # finds the collection next to that config rather than under `Dir.pwd`.
159
+ #
156
160
  # @note module_function: defines #apply_rbs_collection (visibility: private)
157
161
  # @param [Hash<String, Object>] raw raw config hash
162
+ # @param [Docscribe::Config] base base config whose root anchors the lookup
158
163
  # @return [void]
159
- def apply_rbs_collection(raw)
164
+ def apply_rbs_collection(raw, base)
160
165
  require 'docscribe/types/rbs/collection_loader'
161
- collection_path = Docscribe::Types::RBS::CollectionLoader.resolve
166
+ collection_path = Docscribe::Types::RBS::CollectionLoader.resolve(root: base.config_root)
162
167
  if collection_path
163
168
  raw['rbs']['collection_dirs'] = Array(raw['rbs']['collection_dirs']) + [collection_path]
164
169
  else
@@ -216,7 +221,7 @@ module Docscribe
216
221
  # @param [Hash<Symbol, Object>] options parsed CLI options
217
222
  # @return [Boolean]
218
223
  def validation_overrides?(options)
219
- !options[:validate_types].nil?
224
+ !options[:validate_types].nil? || !options[:warn_invalid_yard].nil?
220
225
  end
221
226
 
222
227
  # Apply validation-related CLI overrides to the raw config.
@@ -226,11 +231,16 @@ module Docscribe
226
231
  # @param [Hash<Symbol, Object>] options parsed CLI options
227
232
  # @return [void]
228
233
  def apply_validation_overrides(raw, options)
229
- raw['validate_types'] = options[:validate_types]
234
+ raw['validate_types'] = options[:validate_types] unless options[:validate_types].nil?
235
+ raw['warn_invalid_yard'] = options[:warn_invalid_yard] unless options[:warn_invalid_yard].nil?
230
236
  end
231
237
 
232
238
  # Warn when rbs_collection.lock.yaml exists but --rbs-collection was not passed.
233
239
  #
240
+ # Fires on plain runs and on runs with unrelated overrides alike: the check
241
+ # lives outside the `needs_override?` branch. The lock file is looked up in the
242
+ # config root so the nudge appears regardless of the current directory.
243
+ #
234
244
  # The warning can be suppressed by setting `rbs.warn_missing_collection: false`
235
245
  # in the project's `docscribe.yml`.
236
246
  #
@@ -242,12 +252,28 @@ module Docscribe
242
252
  return if options[:rbs_collection]
243
253
  return if conf.raw.dig('rbs', 'collection')
244
254
  return unless conf.rbs_warn_missing_collection?
245
- return unless File.exist?('rbs_collection.lock.yaml')
255
+ return unless File.exist?(File.join(config_root_for_warning(conf), 'rbs_collection.lock.yaml'))
246
256
 
247
257
  warn 'Docscribe: rbs_collection.lock.yaml found but --rbs-collection not set. ' \
248
258
  'Pass --rbs-collection or set `rbs.collection: true` in docscribe.yml to enable RBS collection. ' \
249
259
  'Set `rbs.warn_missing_collection: false` to suppress this warning.'
250
260
  end
261
+
262
+ # Config root for the missing-collection nudge.
263
+ #
264
+ # A warning must never abort a run, so an unresolvable config directory
265
+ # (e.g. a config path pointing at a removed directory) falls back to the
266
+ # working directory.
267
+ #
268
+ # @note module_function: defines #config_root_for_warning (visibility: private)
269
+ # @param [Docscribe::Config] conf effective config
270
+ # @raise [Docscribe::Error] when the config directory is gone (caught here)
271
+ # @return [String]
272
+ def config_root_for_warning(conf)
273
+ conf.config_root
274
+ rescue Docscribe::Error
275
+ File.expand_path(Dir.pwd)
276
+ end
251
277
  end
252
278
  end
253
279
  end