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.
@@ -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 as YAML.
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 = Docscribe::Config.load(opts[:config])
28
- conf = Docscribe::CLI::ConfigBuilder.build(conf, parse_cli_overrides(argv))
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
@@ -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.uniq.sort
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 a Thread pool.
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
- pool = {
430
- paths: paths, state: state, options: options, conf: conf,
431
- pwd: Pathname.pwd, mutex: Mutex.new, error_mutex: Mutex.new
432
- }
433
- thread_count = [ENV.fetch('DOCSCRIBE_THREADS', PARALLEL_DEFAULT_THREADS).to_i, 1].max
434
- thread_count.times.map { parallel_worker(pool) }.each(&:join)
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
- # @param [Docscribe::CLI::Run::pool] pool
438
- # @return [Thread]
439
- def parallel_worker(pool)
440
- Thread.new do
441
- loop do
442
- path = fetch_work(pool[:paths], pool[:mutex]) or break
443
- run_and_merge(path, pool)
444
- end
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
- # @param [Thread::Mutex] mutex
450
- # @return [String?]
451
- def fetch_work(paths, mutex)
452
- path = nil
453
- mutex.synchronize { path = paths.shift }
454
- path
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
- # @param [String] path
458
- # @param [Docscribe::CLI::Run::pool] pool
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
- # @return [Object] if StandardError
462
- def run_and_merge(path, pool)
568
+ def run_forked_slice(slice, options, conf, writer)
463
569
  local_state = initial_run_state
464
- process_one_file(path, options: pool[:options], conf: pool[:conf], pwd: pool[:pwd], state: local_state)
465
- merge_state(pool[:state], local_state, pool[:error_mutex])
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
- handle_worker_error(e, path, pool[:state], pool[:error_mutex])
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? || v == false
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
@@ -75,7 +75,8 @@ module Docscribe
75
75
  },
76
76
  'keep_descriptions' => false,
77
77
  'skip_anonymous_block_params' => false,
78
- 'validate_types' => false,
78
+ 'validate_types' => true,
79
+ 'warn_invalid_yard' => true,
79
80
  'plugins' => {
80
81
  'require' => [] #: Array[String]
81
82
  }
@@ -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 current working directory and
9
- # passed to `require`. Registration is expected to happen inside the
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 File.expand_path(path)
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
@@ -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
- sig_dirs: rbs_sig_dirs,
71
- collection_dirs: rbs_collection_dirs,
72
- collapse_generics: rbs_collapse_generics?,
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(&:to_s) # steep:ignore
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(&:to_s) # steep:ignore
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(&:to_s) # steep:ignore
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: false
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, `docscribe lib --validate-types` (or `validate_types: true`
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], false)
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