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 +4 -4
- data/README.md +347 -23
- data/lib/docscribe/cli/config_builder.rb +34 -8
- data/lib/docscribe/cli/config_dump.rb +88 -7
- data/lib/docscribe/cli/options.rb +20 -1
- data/lib/docscribe/cli/run.rb +193 -31
- data/lib/docscribe/config/defaults.rb +2 -1
- data/lib/docscribe/config/plugin.rb +4 -4
- data/lib/docscribe/config/rbs.rb +10 -13
- data/lib/docscribe/config/sorbet.rb +3 -1
- data/lib/docscribe/config/template.rb +4 -1
- data/lib/docscribe/config/utils.rb +15 -0
- data/lib/docscribe/config/validation.rb +18 -3
- data/lib/docscribe/config.rb +34 -1
- data/lib/docscribe/infer/returns.rb +46 -16
- data/lib/docscribe/inline_rewriter/doc_builder.rb +69 -3
- data/lib/docscribe/inline_rewriter.rb +104 -1
- data/lib/docscribe/server/base.rb +37 -16
- data/lib/docscribe/server/daemon.rb +10 -1
- data/lib/docscribe/types/rbs/provider.rb +5 -2
- data/lib/docscribe/types/sorbet/base_provider.rb +1 -1
- data/lib/docscribe/types/yard/parser.rb +9 -4
- data/lib/docscribe/types/yard/repair.rb +142 -0
- data/lib/docscribe/version.rb +1 -1
- metadata +4 -3
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 58018ff6ce9cc837ebe99189ccf04770567d4ca922f9a970c6157e81df7e0374
|
|
4
|
+
data.tar.gz: 8356662fe2fbd4fc3e6e9c94ff5c77c10700f8afa9159aaecf0feebcf29e8a2d
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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
|
|
172
|
-
doc lines
|
|
173
|
-
the source via a strategy
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
- `
|
|
256
|
-
|
|
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
|
-
|
|
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
|
-
#
|
|
517
|
-
docscribe init --
|
|
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`.
|
|
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 —
|
|
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` | `
|
|
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
|