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
|
@@ -1,18 +1,21 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
|
+
require 'json'
|
|
3
4
|
require 'optparse'
|
|
4
5
|
require 'yaml'
|
|
5
6
|
require 'docscribe/config'
|
|
6
7
|
require 'docscribe/cli/config_builder'
|
|
8
|
+
require 'docscribe/cli/options'
|
|
7
9
|
|
|
8
10
|
module Docscribe
|
|
9
11
|
module CLI
|
|
10
|
-
# Print the fully resolved configuration as YAML
|
|
12
|
+
# Print the fully resolved configuration as YAML, JSON or text,
|
|
13
|
+
# optionally limited to the keys that differ from the built-in defaults.
|
|
11
14
|
module ConfigDump
|
|
12
15
|
BANNER = <<~TEXT
|
|
13
16
|
Usage: docscribe config [options]
|
|
14
17
|
|
|
15
|
-
Print the fully resolved configuration
|
|
18
|
+
Print the fully resolved configuration.
|
|
16
19
|
|
|
17
20
|
Options:
|
|
18
21
|
TEXT
|
|
@@ -24,10 +27,9 @@ module Docscribe
|
|
|
24
27
|
opts = parse_options(argv)
|
|
25
28
|
return 0 if opts[:help]
|
|
26
29
|
|
|
27
|
-
conf =
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
puts conf.to_h.to_yaml
|
|
30
|
+
conf = build_config(argv, opts)
|
|
31
|
+
data = opts[:only_changed] ? changed_from_defaults(conf.raw) : conf.raw
|
|
32
|
+
puts render(data, conf, opts)
|
|
31
33
|
0
|
|
32
34
|
end
|
|
33
35
|
|
|
@@ -37,7 +39,7 @@ module Docscribe
|
|
|
37
39
|
# @param [Array<String>] argv
|
|
38
40
|
# @return [Hash<Symbol, Object>]
|
|
39
41
|
def parse_options(argv)
|
|
40
|
-
opts = { config: nil }
|
|
42
|
+
opts = { config: nil, only_changed: false, format: 'yaml' }
|
|
41
43
|
build_parser(opts).parse!(argv)
|
|
42
44
|
opts
|
|
43
45
|
end
|
|
@@ -49,6 +51,8 @@ module Docscribe
|
|
|
49
51
|
OptionParser.new do |o|
|
|
50
52
|
o.banner = BANNER
|
|
51
53
|
o.on('--config PATH', 'Path to config file') { |v| opts[:config] = v }
|
|
54
|
+
o.on('--only-changed', 'Show only keys that differ from defaults') { opts[:only_changed] = true }
|
|
55
|
+
o.on('--format FORMAT', %w[yaml json text], 'Output format: yaml, json, text') { |v| opts[:format] = v }
|
|
52
56
|
o.on('-h', '--help', 'Show help') do
|
|
53
57
|
opts[:help] = true
|
|
54
58
|
puts o
|
|
@@ -56,6 +60,15 @@ module Docscribe
|
|
|
56
60
|
end
|
|
57
61
|
end
|
|
58
62
|
|
|
63
|
+
# @private
|
|
64
|
+
# @param [Array<String>] argv
|
|
65
|
+
# @param [Hash<Symbol, Object>] opts
|
|
66
|
+
# @return [Docscribe::Config]
|
|
67
|
+
def build_config(argv, opts)
|
|
68
|
+
conf = Docscribe::Config.load(opts[:config])
|
|
69
|
+
Docscribe::CLI::ConfigBuilder.build(conf, parse_cli_overrides(argv))
|
|
70
|
+
end
|
|
71
|
+
|
|
59
72
|
# @private
|
|
60
73
|
# @param [Array<String>] argv
|
|
61
74
|
# @return [Hash<Symbol, Object>]
|
|
@@ -64,6 +77,74 @@ module Docscribe
|
|
|
64
77
|
opts.slice(:rbs, :rbs_collection, :sorbet, :sig_dirs, :rbi_dirs, :include, :exclude, :include_file,
|
|
65
78
|
:exclude_file)
|
|
66
79
|
end
|
|
80
|
+
|
|
81
|
+
# Keep only the nested keys whose effective value differs from the
|
|
82
|
+
# built-in default.
|
|
83
|
+
#
|
|
84
|
+
# @private
|
|
85
|
+
# @param [Hash<String, Object>] effective merged config
|
|
86
|
+
# @return [Hash<String, Object>]
|
|
87
|
+
def changed_from_defaults(effective)
|
|
88
|
+
diff_against(Docscribe::Config::DEFAULT, effective)
|
|
89
|
+
end
|
|
90
|
+
|
|
91
|
+
# Recursive comparison; a single overridden leaf keeps its parent
|
|
92
|
+
# sections while untouched siblings are dropped.
|
|
93
|
+
#
|
|
94
|
+
# @private
|
|
95
|
+
# @param [Hash<String, Object>] defaults
|
|
96
|
+
# @param [Hash<String, Object>] effective
|
|
97
|
+
# @return [Hash<String, Object>]
|
|
98
|
+
def diff_against(defaults, effective)
|
|
99
|
+
effective.each_with_object({}) do |(key, value), acc|
|
|
100
|
+
default = defaults[key]
|
|
101
|
+
if value.is_a?(Hash) && default.is_a?(Hash)
|
|
102
|
+
nested = diff_against(default, value)
|
|
103
|
+
acc[key] = nested unless nested.empty?
|
|
104
|
+
elsif value != default
|
|
105
|
+
acc[key] = value
|
|
106
|
+
end
|
|
107
|
+
end
|
|
108
|
+
end
|
|
109
|
+
|
|
110
|
+
# @private
|
|
111
|
+
# @param [Hash<String, Object>] data
|
|
112
|
+
# @param [Docscribe::Config] conf
|
|
113
|
+
# @param [Hash<Symbol, Object>] opts
|
|
114
|
+
# @return [String]
|
|
115
|
+
def render(data, conf, opts)
|
|
116
|
+
case opts[:format]
|
|
117
|
+
when 'json' then JSON.pretty_generate(data)
|
|
118
|
+
when 'text' then render_text(data, conf)
|
|
119
|
+
else data.to_yaml
|
|
120
|
+
end
|
|
121
|
+
end
|
|
122
|
+
|
|
123
|
+
# @private
|
|
124
|
+
# @param [Hash<String, Object>] data
|
|
125
|
+
# @param [Docscribe::Config] _conf unused, kept for format symmetry
|
|
126
|
+
# @return [String]
|
|
127
|
+
def render_text(data, _conf)
|
|
128
|
+
flat = flatten(data, '')
|
|
129
|
+
return "(no changes from defaults)\n" if flat.empty?
|
|
130
|
+
|
|
131
|
+
flat.map { |key, value| "#{key}=#{value}" }.join("\n")
|
|
132
|
+
end
|
|
133
|
+
|
|
134
|
+
# @private
|
|
135
|
+
# @param [Hash<String, Object>] data
|
|
136
|
+
# @param [String] prefix dotted path of the current level
|
|
137
|
+
# @return [Hash<String, Object>]
|
|
138
|
+
def flatten(data, prefix)
|
|
139
|
+
data.each_with_object({}) do |(key, value), acc|
|
|
140
|
+
path = prefix.empty? ? key.to_s : "#{prefix}.#{key}"
|
|
141
|
+
if value.is_a?(Hash)
|
|
142
|
+
acc.merge!(flatten(value, path))
|
|
143
|
+
else
|
|
144
|
+
acc[path] = value
|
|
145
|
+
end
|
|
146
|
+
end
|
|
147
|
+
end
|
|
67
148
|
end
|
|
68
149
|
end
|
|
69
150
|
end
|
|
@@ -28,8 +28,10 @@ module Docscribe
|
|
|
28
28
|
no_boilerplate: false,
|
|
29
29
|
progress: false,
|
|
30
30
|
parallel: false,
|
|
31
|
+
jobs: nil, #: Integer? when --jobs is passed
|
|
31
32
|
server: false,
|
|
32
|
-
validate_types: nil #: true or false when --[no-]validate-types is passed, nil otherwise
|
|
33
|
+
validate_types: nil, #: true or false when --[no-]validate-types is passed, nil otherwise
|
|
34
|
+
warn_invalid_yard: nil #: true or false when --[no-]warn-invalid-yard is passed, nil otherwise
|
|
33
35
|
}.freeze
|
|
34
36
|
|
|
35
37
|
module_function
|
|
@@ -205,6 +207,7 @@ module Docscribe
|
|
|
205
207
|
define_rbi_dir_option(opts, options)
|
|
206
208
|
define_rbs_collection_option(opts, options)
|
|
207
209
|
define_validate_types_option(opts, options)
|
|
210
|
+
define_warn_invalid_yard_option(opts, options)
|
|
208
211
|
end
|
|
209
212
|
|
|
210
213
|
# Define rbs option
|
|
@@ -282,6 +285,18 @@ module Docscribe
|
|
|
282
285
|
end
|
|
283
286
|
end
|
|
284
287
|
|
|
288
|
+
# Define warn invalid yard option
|
|
289
|
+
#
|
|
290
|
+
# @note module_function: defines #define_warn_invalid_yard_option (visibility: private)
|
|
291
|
+
# @param [OptionParser] opts the option parser to configure
|
|
292
|
+
# @param [Hash<Symbol, Object>] options mutable parsed options hash
|
|
293
|
+
# @return [void]
|
|
294
|
+
def define_warn_invalid_yard_option(opts, options)
|
|
295
|
+
opts.on('--[no-]warn-invalid-yard', 'Report syntactically broken YARD types (default: on)') do |value|
|
|
296
|
+
options[:warn_invalid_yard] = value
|
|
297
|
+
end
|
|
298
|
+
end
|
|
299
|
+
|
|
285
300
|
# Define filter options
|
|
286
301
|
#
|
|
287
302
|
# @note module_function: defines #define_filter_options (visibility: private)
|
|
@@ -396,6 +411,10 @@ module Docscribe
|
|
|
396
411
|
opts.on('--parallel', 'Process files in parallel (default: sequential)') do
|
|
397
412
|
options[:parallel] = true
|
|
398
413
|
end
|
|
414
|
+
opts.on('--jobs N', Integer, 'Parallel worker count (implies --parallel)') do |n|
|
|
415
|
+
options[:jobs] = n
|
|
416
|
+
options[:parallel] = true
|
|
417
|
+
end
|
|
399
418
|
end
|
|
400
419
|
|
|
401
420
|
# Define explain option
|
data/lib/docscribe/cli/run.rb
CHANGED
|
@@ -42,9 +42,12 @@ module Docscribe
|
|
|
42
42
|
include exclude include_file exclude_file
|
|
43
43
|
rbs rbs_collection sig_dirs
|
|
44
44
|
sorbet rbi_dirs
|
|
45
|
-
validate_types
|
|
45
|
+
validate_types warn_invalid_yard
|
|
46
46
|
].freeze
|
|
47
47
|
|
|
48
|
+
# [no-] flags where an explicit false must override a `true` from config.
|
|
49
|
+
NEGATABLE_KEYS = %i[validate_types warn_invalid_yard].freeze
|
|
50
|
+
|
|
48
51
|
# Run Docscribe for files or STDIN using the selected mode and strategy.
|
|
49
52
|
#
|
|
50
53
|
# Modes:
|
|
@@ -345,6 +348,10 @@ module Docscribe
|
|
|
345
348
|
# Directories are expanded recursively to `**/*.rb`.
|
|
346
349
|
# If no arguments are provided, the current directory is used.
|
|
347
350
|
#
|
|
351
|
+
# Deduplication uses the canonical path, so overlapping arguments
|
|
352
|
+
# that spell one file differently (absolute vs relative, `./`-prefixed,
|
|
353
|
+
# symlinked) are processed once. The first spelling wins.
|
|
354
|
+
#
|
|
348
355
|
# @param [Array<String>] args file and/or directory arguments
|
|
349
356
|
# @return [Array<String>] unique sorted Ruby file paths
|
|
350
357
|
def expand_paths(args)
|
|
@@ -355,7 +362,34 @@ module Docscribe
|
|
|
355
362
|
append_expanded_path(files, path)
|
|
356
363
|
end
|
|
357
364
|
|
|
358
|
-
files.
|
|
365
|
+
dedupe_paths(files).sort
|
|
366
|
+
end
|
|
367
|
+
|
|
368
|
+
# Drop later spellings of a file already collected.
|
|
369
|
+
#
|
|
370
|
+
# @param [Array<String>] files expanded paths, possibly overlapping
|
|
371
|
+
# @return [Array<String>] paths with one entry per canonical file
|
|
372
|
+
def dedupe_paths(files)
|
|
373
|
+
seen = {} #: Hash[String, true]
|
|
374
|
+
files.each_with_object([]) do |path, acc| #: Array[String]
|
|
375
|
+
key = canonical_path(path)
|
|
376
|
+
next if seen[key]
|
|
377
|
+
|
|
378
|
+
seen[key] = true
|
|
379
|
+
acc << path
|
|
380
|
+
end
|
|
381
|
+
end
|
|
382
|
+
|
|
383
|
+
# Canonical identity for a path, resolving symlinks and relative segments.
|
|
384
|
+
#
|
|
385
|
+
# @param [String] path file path
|
|
386
|
+
# @raise [SystemCallError] when the file is gone (caught here)
|
|
387
|
+
# @raise [ArgumentError] when the path is malformed (caught here)
|
|
388
|
+
# @return [String]
|
|
389
|
+
def canonical_path(path)
|
|
390
|
+
File.realpath(path)
|
|
391
|
+
rescue SystemCallError, ArgumentError
|
|
392
|
+
File.expand_path(path)
|
|
359
393
|
end
|
|
360
394
|
|
|
361
395
|
# Append a file or recursively expand a directory into the files array.
|
|
@@ -405,7 +439,7 @@ module Docscribe
|
|
|
405
439
|
run_exit_code(options, state)
|
|
406
440
|
end
|
|
407
441
|
|
|
408
|
-
# Process files in parallel using
|
|
442
|
+
# Process files in parallel using forked workers.
|
|
409
443
|
#
|
|
410
444
|
# @param [Docscribe::CLI::Formatters::opts] options parsed CLI options
|
|
411
445
|
# @param [Docscribe::Config] conf effective config
|
|
@@ -420,53 +454,147 @@ module Docscribe
|
|
|
420
454
|
run_exit_code(options, state)
|
|
421
455
|
end
|
|
422
456
|
|
|
457
|
+
# Split the work across forked children and merge their states.
|
|
458
|
+
#
|
|
459
|
+
# Children inherit the warmed process (gems, config, RBS env) through
|
|
460
|
+
# copy-on-write, so each fork skips the cold-start cost that made the
|
|
461
|
+
# earlier thread implementation slower than a sequential run.
|
|
462
|
+
#
|
|
423
463
|
# @param [Docscribe::CLI::Formatters::opts] options
|
|
424
464
|
# @param [Docscribe::Config] conf
|
|
425
465
|
# @param [Array<String>] paths
|
|
426
466
|
# @param [Docscribe::CLI::Formatters::state] state
|
|
467
|
+
# @raise [StandardError]
|
|
427
468
|
# @return [void]
|
|
428
469
|
def run_parallel_workers(options, conf, paths, state)
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
470
|
+
return if paths.empty?
|
|
471
|
+
return run_files_sequential(options, conf, paths, state) unless fork_supported?
|
|
472
|
+
|
|
473
|
+
jobs = parallel_job_count(options)
|
|
474
|
+
warm_rewrite_env(options, conf, paths)
|
|
475
|
+
slices = split_paths(paths, jobs).reject(&:empty?)
|
|
476
|
+
return if slices.empty?
|
|
477
|
+
|
|
478
|
+
children = slices.map { |slice| start_forked_slice(slice, options, conf) }
|
|
479
|
+
merge_forked_slices(children, state)
|
|
435
480
|
end
|
|
436
481
|
|
|
437
|
-
#
|
|
438
|
-
#
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
482
|
+
# Whether forked workers can run here.
|
|
483
|
+
#
|
|
484
|
+
# Without fork (Windows, some locked-down containers) spawning workers
|
|
485
|
+
# would raise NotImplementedError, so parallel mode silently degrades to
|
|
486
|
+
# the sequential path. Threads are not used as a fallback: on CPU-bound
|
|
487
|
+
# rewriting they are measurably slower than a plain sequential run.
|
|
488
|
+
#
|
|
489
|
+
# @return [Boolean]
|
|
490
|
+
def fork_supported?
|
|
491
|
+
Process.respond_to?(:fork)
|
|
492
|
+
end
|
|
493
|
+
|
|
494
|
+
# Run the same file list sequentially, reusing the shared state.
|
|
495
|
+
#
|
|
496
|
+
# @param [Docscribe::CLI::Formatters::opts] options
|
|
497
|
+
# @param [Docscribe::Config] conf
|
|
498
|
+
# @param [Array<String>] paths
|
|
499
|
+
# @param [Docscribe::CLI::Formatters::state] state
|
|
500
|
+
# @return [void]
|
|
501
|
+
def run_files_sequential(options, conf, paths, state)
|
|
502
|
+
paths.each do |path|
|
|
503
|
+
process_one_file(path, options: options, conf: conf, pwd: Pathname.pwd, state: state)
|
|
445
504
|
end
|
|
446
505
|
end
|
|
447
506
|
|
|
507
|
+
# Fork one child per slice and return its pipe and pid.
|
|
508
|
+
#
|
|
509
|
+
# All children are started before any is collected, so the slices
|
|
510
|
+
# actually overlap instead of running one after another.
|
|
511
|
+
#
|
|
512
|
+
# @param [Array<String>] slice paths handled by this child
|
|
513
|
+
# @param [Docscribe::CLI::Formatters::opts] options
|
|
514
|
+
# @param [Docscribe::Config] conf
|
|
515
|
+
# @raise [StandardError] when the fork itself fails
|
|
516
|
+
# @return [(Integer, IO)] pid and reader pipe for the child
|
|
517
|
+
def start_forked_slice(slice, options, conf)
|
|
518
|
+
reader, writer = IO.pipe
|
|
519
|
+
pid = fork { run_forked_slice(slice, options, conf, writer) }
|
|
520
|
+
writer.close
|
|
521
|
+
[pid, reader]
|
|
522
|
+
end
|
|
523
|
+
|
|
524
|
+
# Collect every child's marshalled state and merge it into the parent.
|
|
525
|
+
#
|
|
526
|
+
# @param [Array<(Integer, IO)>] children pid and reader pairs
|
|
527
|
+
# @param [Docscribe::CLI::Formatters::state] state shared parent state
|
|
528
|
+
# @return [void]
|
|
529
|
+
def merge_forked_slices(children, state)
|
|
530
|
+
mutex = Mutex.new
|
|
531
|
+
children.each do |(pid, reader)|
|
|
532
|
+
payload = reader.read
|
|
533
|
+
reader.close
|
|
534
|
+
Process.wait(pid)
|
|
535
|
+
local_state = Marshal.load(payload) if payload && !payload.empty? # rubocop:disable Security/MarshalLoad
|
|
536
|
+
merge_state(state, local_state, mutex) if local_state
|
|
537
|
+
end
|
|
538
|
+
end
|
|
539
|
+
|
|
540
|
+
# Warm the shared rewrite environment once before forking.
|
|
541
|
+
#
|
|
542
|
+
# Doing the first rewrite here means every child inherits the built
|
|
543
|
+
# RBS provider instead of racing to construct its own.
|
|
544
|
+
#
|
|
545
|
+
# @param [Docscribe::CLI::Formatters::opts] options
|
|
546
|
+
# @param [Docscribe::Config] conf
|
|
448
547
|
# @param [Array<String>] paths
|
|
449
|
-
# @
|
|
450
|
-
# @return [
|
|
451
|
-
def
|
|
452
|
-
path =
|
|
453
|
-
|
|
454
|
-
|
|
548
|
+
# @raise [StandardError] when the warm-up rewrite fails (ignored here)
|
|
549
|
+
# @return [void]
|
|
550
|
+
def warm_rewrite_env(options, conf, paths)
|
|
551
|
+
path = paths.first
|
|
552
|
+
return unless path
|
|
553
|
+
|
|
554
|
+
warm_state = initial_run_state
|
|
555
|
+
process_one_file(path, options: options, conf: conf, pwd: Pathname.pwd, state: warm_state)
|
|
556
|
+
rescue StandardError
|
|
557
|
+
nil
|
|
455
558
|
end
|
|
456
559
|
|
|
457
|
-
#
|
|
458
|
-
#
|
|
560
|
+
# Child-process body: process a slice and ship its state back.
|
|
561
|
+
#
|
|
562
|
+
# @param [Array<String>] slice
|
|
563
|
+
# @param [Docscribe::CLI::Formatters::opts] options
|
|
564
|
+
# @param [Docscribe::Config] conf
|
|
565
|
+
# @param [IO] writer pipe back to the parent
|
|
459
566
|
# @raise [StandardError]
|
|
460
567
|
# @return [void]
|
|
461
|
-
|
|
462
|
-
def run_and_merge(path, pool)
|
|
568
|
+
def run_forked_slice(slice, options, conf, writer)
|
|
463
569
|
local_state = initial_run_state
|
|
464
|
-
|
|
465
|
-
|
|
570
|
+
slice.each do |path|
|
|
571
|
+
process_one_file(path, options: options, conf: conf, pwd: Pathname.pwd, state: local_state)
|
|
572
|
+
end
|
|
573
|
+
writer.write(Marshal.dump(local_state))
|
|
466
574
|
rescue StandardError => e
|
|
467
|
-
|
|
575
|
+
writer.write(Marshal.dump(error_only_state(slice, e)))
|
|
576
|
+
ensure
|
|
577
|
+
writer.close
|
|
578
|
+
exit!(0)
|
|
468
579
|
end
|
|
469
580
|
|
|
581
|
+
# Build a state carrying just the error for a failed slice.
|
|
582
|
+
#
|
|
583
|
+
# @param [Array<String>] slice
|
|
584
|
+
# @param [StandardError] exception
|
|
585
|
+
# @return [Docscribe::CLI::Formatters::state]
|
|
586
|
+
def error_only_state(slice, exception)
|
|
587
|
+
local_state = initial_run_state
|
|
588
|
+
local_state[:had_errors] = true
|
|
589
|
+
slice.each do |path|
|
|
590
|
+
local_state[:error_paths] << path
|
|
591
|
+
local_state[:error_messages][path] = "#{exception.class}: #{exception.message}"
|
|
592
|
+
end
|
|
593
|
+
local_state
|
|
594
|
+
end
|
|
595
|
+
|
|
596
|
+
# Record a worker failure on the shared state.
|
|
597
|
+
#
|
|
470
598
|
# @param [StandardError] exception
|
|
471
599
|
# @param [String] path
|
|
472
600
|
# @param [Docscribe::CLI::Formatters::state] state
|
|
@@ -481,6 +609,38 @@ module Docscribe
|
|
|
481
609
|
$stderr.print('E')
|
|
482
610
|
end
|
|
483
611
|
|
|
612
|
+
# Resolve the worker count: --jobs, then DOCSCRIBE_THREADS, then CPU count.
|
|
613
|
+
#
|
|
614
|
+
# @param [Docscribe::CLI::Formatters::opts] options
|
|
615
|
+
# @return [Integer] positive worker count
|
|
616
|
+
def parallel_job_count(options)
|
|
617
|
+
requested = options[:jobs] || ENV.fetch('DOCSCRIBE_THREADS', nil)&.to_i
|
|
618
|
+
jobs = requested || default_job_count
|
|
619
|
+
jobs.positive? ? jobs : 1
|
|
620
|
+
end
|
|
621
|
+
|
|
622
|
+
# @raise [StandardError] when processor detection is unavailable
|
|
623
|
+
# @return [Integer] default worker count based on available CPUs
|
|
624
|
+
def default_job_count
|
|
625
|
+
require 'etc'
|
|
626
|
+
Etc.nprocessors
|
|
627
|
+
rescue StandardError
|
|
628
|
+
PARALLEL_DEFAULT_THREADS
|
|
629
|
+
end
|
|
630
|
+
|
|
631
|
+
# Split paths into contiguous slices of roughly equal size.
|
|
632
|
+
#
|
|
633
|
+
# @param [Array<String>] paths
|
|
634
|
+
# @param [Integer] jobs
|
|
635
|
+
# @return [Array<Array<String>>]
|
|
636
|
+
def split_paths(paths, jobs)
|
|
637
|
+
return [paths] if jobs <= 1
|
|
638
|
+
|
|
639
|
+
size = (paths.size.to_f / jobs).ceil
|
|
640
|
+
size = 1 if size < 1
|
|
641
|
+
paths.each_slice(size).to_a
|
|
642
|
+
end
|
|
643
|
+
|
|
484
644
|
# Merge a thread-local state into the shared state under mutex protection.
|
|
485
645
|
#
|
|
486
646
|
# @param [Docscribe::CLI::Formatters::state] target shared state to merge into
|
|
@@ -541,7 +701,9 @@ module Docscribe
|
|
|
541
701
|
overrides = options.slice(*CLI_OVERRIDE_KEYS)
|
|
542
702
|
acc = {} #: Hash[String, untyped]
|
|
543
703
|
overrides.each do |k, v|
|
|
544
|
-
next if v.nil?
|
|
704
|
+
next if v.nil?
|
|
705
|
+
# Negations matter for [no-] flags: false must beat a `true` in yml.
|
|
706
|
+
next if v == false && !NEGATABLE_KEYS.include?(k)
|
|
545
707
|
next if v.is_a?(Array) && v.empty?
|
|
546
708
|
|
|
547
709
|
acc[k.to_s] = v
|
|
@@ -5,9 +5,9 @@ module Docscribe
|
|
|
5
5
|
class Config
|
|
6
6
|
# Load and register plugins declared under `plugins.require` in config.
|
|
7
7
|
#
|
|
8
|
-
# Each entry is expanded relative to the
|
|
9
|
-
# passed to `require`. Registration is expected to
|
|
10
|
-
# required file via {Docscribe::Plugin::Registry.register}.
|
|
8
|
+
# Each entry is expanded relative to {#config_root} (the directory holding
|
|
9
|
+
# `docscribe.yml`) and passed to `require`. Registration is expected to
|
|
10
|
+
# happen inside the required file via {Docscribe::Plugin::Registry.register}.
|
|
11
11
|
#
|
|
12
12
|
# Loading failures are non-fatal: a warning is printed and the run
|
|
13
13
|
# continues without the plugin.
|
|
@@ -21,7 +21,7 @@ module Docscribe
|
|
|
21
21
|
require 'docscribe/plugin'
|
|
22
22
|
|
|
23
23
|
paths.each do |path|
|
|
24
|
-
require
|
|
24
|
+
require resolve_path(path)
|
|
25
25
|
rescue LoadError => e
|
|
26
26
|
warn "Docscribe: could not load plugin #{path.inspect}: #{e.message}"
|
|
27
27
|
end
|
data/lib/docscribe/config/rbs.rb
CHANGED
|
@@ -66,12 +66,10 @@ module Docscribe
|
|
|
66
66
|
# @return [nil] if LoadError
|
|
67
67
|
def build_rbs_provider
|
|
68
68
|
require 'docscribe/types/rbs/provider'
|
|
69
|
-
Docscribe::Types::RBS::Provider.new(
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
collapse_object_generics: rbs_collapse_object_generics?
|
|
74
|
-
)
|
|
69
|
+
Docscribe::Types::RBS::Provider.new(sig_dirs: rbs_sig_dirs, collection_dirs: rbs_collection_dirs,
|
|
70
|
+
collapse_generics: rbs_collapse_generics?,
|
|
71
|
+
collapse_object_generics: rbs_collapse_object_generics?,
|
|
72
|
+
config_root: config_root)
|
|
75
73
|
rescue LoadError
|
|
76
74
|
warn 'Docscribe: --rbs requires the `rbs` gem. Add `gem "rbs"` to your Gemfile and run `bundle install`.'
|
|
77
75
|
nil
|
|
@@ -85,20 +83,19 @@ module Docscribe
|
|
|
85
83
|
# @return [nil] if LoadError
|
|
86
84
|
def build_core_rbs_provider
|
|
87
85
|
require 'docscribe/types/rbs/provider'
|
|
88
|
-
Docscribe::Types::RBS::Provider.new(
|
|
89
|
-
sig_dirs: [],
|
|
90
|
-
collapse_generics: false
|
|
91
|
-
)
|
|
86
|
+
Docscribe::Types::RBS::Provider.new(sig_dirs: [], collapse_generics: false, config_root: config_root)
|
|
92
87
|
rescue LoadError
|
|
93
88
|
nil
|
|
94
89
|
end
|
|
95
90
|
|
|
96
91
|
# Signature directories used by the RBS provider.
|
|
97
92
|
#
|
|
93
|
+
# Relative entries resolve against {#config_root}, not `Dir.pwd`.
|
|
94
|
+
#
|
|
98
95
|
# @private
|
|
99
96
|
# @return [Array<String>]
|
|
100
97
|
def rbs_sig_dirs
|
|
101
|
-
Array(raw.dig('rbs', 'sig_dirs') || DEFAULT.dig('rbs', 'sig_dirs')).map(
|
|
98
|
+
Array(raw.dig('rbs', 'sig_dirs') || DEFAULT.dig('rbs', 'sig_dirs')).map { |dir| resolve_path(dir.to_s) } # steep:ignore
|
|
102
99
|
end
|
|
103
100
|
|
|
104
101
|
# RBS collection directories (auto-discovered from rbs_collection.lock.yaml).
|
|
@@ -114,7 +111,7 @@ module Docscribe
|
|
|
114
111
|
# @private
|
|
115
112
|
# @return [Array<String>]
|
|
116
113
|
def rbs_collection_dirs
|
|
117
|
-
explicit = Array(raw.dig('rbs', 'collection_dirs')).map(
|
|
114
|
+
explicit = Array(raw.dig('rbs', 'collection_dirs')).map { |dir| resolve_path(dir.to_s) } # steep:ignore
|
|
118
115
|
return explicit unless explicit.empty?
|
|
119
116
|
return [] unless raw.dig('rbs', 'collection')
|
|
120
117
|
|
|
@@ -129,7 +126,7 @@ module Docscribe
|
|
|
129
126
|
# @return [nil] if LoadError
|
|
130
127
|
def discovered_collection_dir
|
|
131
128
|
require 'docscribe/types/rbs/collection_loader'
|
|
132
|
-
Docscribe::Types::RBS::CollectionLoader.resolve
|
|
129
|
+
Docscribe::Types::RBS::CollectionLoader.resolve(root: config_root)
|
|
133
130
|
rescue LoadError
|
|
134
131
|
nil
|
|
135
132
|
end
|
|
@@ -92,9 +92,11 @@ module Docscribe
|
|
|
92
92
|
|
|
93
93
|
# RBI directories searched by the Sorbet provider.
|
|
94
94
|
#
|
|
95
|
+
# Relative entries resolve against {#config_root}, not `Dir.pwd`.
|
|
96
|
+
#
|
|
95
97
|
# @return [Array<String>]
|
|
96
98
|
def sorbet_rbi_dirs
|
|
97
|
-
Array(raw.dig('sorbet', 'rbi_dirs') || DEFAULT.dig('sorbet', 'rbi_dirs')).map(
|
|
99
|
+
Array(raw.dig('sorbet', 'rbi_dirs') || DEFAULT.dig('sorbet', 'rbi_dirs')).map { |dir| resolve_path(dir.to_s) } # steep:ignore
|
|
98
100
|
end
|
|
99
101
|
|
|
100
102
|
# Whether generic Sorbet/RBI container types should be simplified.
|
|
@@ -107,7 +107,10 @@ module Docscribe
|
|
|
107
107
|
skip_anonymous_block_params: false
|
|
108
108
|
|
|
109
109
|
# Validate YARD types against inferred/RBS types
|
|
110
|
-
validate_types:
|
|
110
|
+
validate_types: true
|
|
111
|
+
|
|
112
|
+
# Report syntactically broken YARD types (e.g. [Sym bol])
|
|
113
|
+
warn_invalid_yard: true
|
|
111
114
|
|
|
112
115
|
plugins:
|
|
113
116
|
# Load custom plugins
|
|
@@ -82,6 +82,21 @@ module Docscribe
|
|
|
82
82
|
end
|
|
83
83
|
end
|
|
84
84
|
|
|
85
|
+
# Recursively convert hash keys to strings.
|
|
86
|
+
#
|
|
87
|
+
# `Config.new` receives overrides as Ruby keyword arguments (symbol keys)
|
|
88
|
+
# while the defaults and every reader use string keys, so mixed hashes would
|
|
89
|
+
# silently keep the default value instead of the override.
|
|
90
|
+
#
|
|
91
|
+
# @private
|
|
92
|
+
# @param [Hash<Object, Object>] hash the hash to normalize
|
|
93
|
+
# @return [Hash<String, Object>]
|
|
94
|
+
def stringify_keys(hash)
|
|
95
|
+
hash.each_with_object({}) do |(key, value), out|
|
|
96
|
+
out[key.to_s] = value.is_a?(Hash) ? stringify_keys(value) : value
|
|
97
|
+
end
|
|
98
|
+
end
|
|
99
|
+
|
|
85
100
|
# Deep-merge two hashes, preferring values from the second hash.
|
|
86
101
|
#
|
|
87
102
|
# Nested hashes are merged recursively; non-hash values are replaced.
|
|
@@ -5,15 +5,30 @@ module Docscribe
|
|
|
5
5
|
class Config
|
|
6
6
|
# Whether to validate YARD types against inferred / external types.
|
|
7
7
|
#
|
|
8
|
-
# When enabled, `
|
|
9
|
-
# in `docscribe.yml`) compares each `@param`/`@return` type written in YARD
|
|
8
|
+
# When enabled, each `@param`/`@return` type written in YARD is compared
|
|
10
9
|
# against the type inferred from the method body or provided via RBS/Sorbet.
|
|
11
10
|
# Mismatches are reported as `updated_param` / `updated_return` and, in
|
|
12
11
|
# check mode, cause exit 1.
|
|
13
12
|
#
|
|
13
|
+
# Enabled by default; pass `--no-validate-types` or set
|
|
14
|
+
# `validate_types: false` in `docscribe.yml` to silence it.
|
|
15
|
+
#
|
|
14
16
|
# @return [Boolean]
|
|
15
17
|
def validate_types?
|
|
16
|
-
fetch_bool(%w[validate_types],
|
|
18
|
+
fetch_bool(%w[validate_types], true)
|
|
19
|
+
end
|
|
20
|
+
|
|
21
|
+
# Whether to report syntactically broken YARD types.
|
|
22
|
+
#
|
|
23
|
+
# Independent of {#validate_types?}: syntax validity is a property of the
|
|
24
|
+
# YARD type string itself, not a comparison against inferred or external
|
|
25
|
+
# types. Enabled by default so a broken `[Sym bol]` is still surfaced (and
|
|
26
|
+
# safely fixed) on plain runs; set `warn_invalid_yard: false` or pass
|
|
27
|
+
# `--no-warn-invalid-yard` to silence it.
|
|
28
|
+
#
|
|
29
|
+
# @return [Boolean]
|
|
30
|
+
def warn_invalid_yard?
|
|
31
|
+
fetch_bool(%w[warn_invalid_yard], true)
|
|
17
32
|
end
|
|
18
33
|
end
|
|
19
34
|
end
|