docscribe 1.6.1 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +258 -51
  3. data/exe/docscribe-client +26 -7
  4. data/lib/docscribe/cli/config_builder.rb +69 -8
  5. data/lib/docscribe/cli/config_dump.rb +88 -7
  6. data/lib/docscribe/cli/coverage.rb +5 -5
  7. data/lib/docscribe/cli/formatters/json.rb +74 -29
  8. data/lib/docscribe/cli/formatters/sarif.rb +20 -3
  9. data/lib/docscribe/cli/options.rb +36 -2
  10. data/lib/docscribe/cli/rbs_gen.rb +4 -4
  11. data/lib/docscribe/cli/run.rb +297 -52
  12. data/lib/docscribe/cli/update_types.rb +61 -17
  13. data/lib/docscribe/cli.rb +19 -13
  14. data/lib/docscribe/config/defaults.rb +2 -0
  15. data/lib/docscribe/config/plugin.rb +4 -4
  16. data/lib/docscribe/config/rbs.rb +30 -12
  17. data/lib/docscribe/config/sorbet.rb +3 -1
  18. data/lib/docscribe/config/template.rb +6 -0
  19. data/lib/docscribe/config/utils.rb +15 -0
  20. data/lib/docscribe/config/validation.rb +34 -0
  21. data/lib/docscribe/config.rb +35 -1
  22. data/lib/docscribe/infer/behavior.rb +13 -13
  23. data/lib/docscribe/infer/params.rb +2 -2
  24. data/lib/docscribe/infer/raises.rb +5 -6
  25. data/lib/docscribe/infer/returns.rb +1642 -151
  26. data/lib/docscribe/infer.rb +7 -7
  27. data/lib/docscribe/inline_rewriter/doc_builder.rb +551 -102
  28. data/lib/docscribe/inline_rewriter.rb +367 -98
  29. data/lib/docscribe/plugin/registry.rb +1 -0
  30. data/lib/docscribe/server/base.rb +73 -21
  31. data/lib/docscribe/server/client.rb +20 -11
  32. data/lib/docscribe/server/daemon.rb +209 -23
  33. data/lib/docscribe/server/protocol.rb +4 -4
  34. data/lib/docscribe/types/primitive.rb +160 -0
  35. data/lib/docscribe/types/rbs/provider.rb +5 -2
  36. data/lib/docscribe/types/sorbet/base_provider.rb +33 -1
  37. data/lib/docscribe/types/yard/formatter.rb +35 -6
  38. data/lib/docscribe/types/yard/parser.rb +32 -22
  39. data/lib/docscribe/types/yard/repair.rb +142 -0
  40. data/lib/docscribe/types/yard/validator.rb +131 -0
  41. data/lib/docscribe/validator/generic_compatibility.rb +698 -0
  42. data/lib/docscribe/validator/type_mismatch_validator.rb +287 -0
  43. data/lib/docscribe/version.rb +1 -1
  44. metadata +9 -3
@@ -28,7 +28,10 @@ module Docscribe
28
28
  no_boilerplate: false,
29
29
  progress: false,
30
30
  parallel: false,
31
- server: false
31
+ jobs: nil, #: Integer? when --jobs is passed
32
+ server: false,
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
32
35
  }.freeze
33
36
 
34
37
  module_function
@@ -39,7 +42,7 @@ module Docscribe
39
42
  docscribe generate <type> <name> [options]
40
43
  docscribe sigs [options] [files...]
41
44
  docscribe rbs [options] [files...]
42
- docscribe update_types [directory]
45
+ docscribe update_types [directory|file]
43
46
  docscribe check_for_comments [paths...]
44
47
 
45
48
  Default behavior:
@@ -63,6 +66,7 @@ module Docscribe
63
66
  --sorbet Use Sorbet signatures from inline sigs / RBI files when available
64
67
  --rbi-dir DIR Add a Sorbet RBI directory (repeatable). Implies --sorbet.
65
68
  --rbs-collection Auto-discover RBS collection from rbs_collection.lock.yaml. Implies --rbs.
69
+ --validate-types Validate YARD types against inferred/RBS types and report mismatches
66
70
 
67
71
  Filtering:
68
72
  --include PATTERN Include PATTERN (method id or file path; glob or /regex/)
@@ -202,6 +206,8 @@ module Docscribe
202
206
  define_sorbet_option(opts, options)
203
207
  define_rbi_dir_option(opts, options)
204
208
  define_rbs_collection_option(opts, options)
209
+ define_validate_types_option(opts, options)
210
+ define_warn_invalid_yard_option(opts, options)
205
211
  end
206
212
 
207
213
  # Define rbs option
@@ -267,6 +273,30 @@ module Docscribe
267
273
  end
268
274
  end
269
275
 
276
+ # Define validate types option
277
+ #
278
+ # @note module_function: defines #define_validate_types_option (visibility: private)
279
+ # @param [OptionParser] opts the option parser to configure
280
+ # @param [Hash<Symbol, Object>] options mutable parsed options hash
281
+ # @return [void]
282
+ def define_validate_types_option(opts, options)
283
+ opts.on('--[no-]validate-types', 'Validate YARD types against inferred/RBS types and report mismatches') do |value|
284
+ options[:validate_types] = value
285
+ end
286
+ end
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
+
270
300
  # Define filter options
271
301
  #
272
302
  # @note module_function: defines #define_filter_options (visibility: private)
@@ -381,6 +411,10 @@ module Docscribe
381
411
  opts.on('--parallel', 'Process files in parallel (default: sequential)') do
382
412
  options[:parallel] = true
383
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
384
418
  end
385
419
 
386
420
  # Define explain option
@@ -29,7 +29,7 @@ module Docscribe
29
29
  # @!attribute [rw] options
30
30
  # @return [Array<Docscribe::CLI::RbsGen::ParamTag>]
31
31
  # @param [Array<Docscribe::CLI::RbsGen::ParamTag>] value
32
- YardTags = Struct.new(:params, :return_type, :options, keyword_init: true)
32
+ YardTags = Struct.new(:params, :return_type, :options, keyword_init: true) #: Class[YardTags]
33
33
  # @!attribute [rw] name
34
34
  # @return [String]
35
35
  # @param [String] value
@@ -37,7 +37,7 @@ module Docscribe
37
37
  # @!attribute [rw] type
38
38
  # @return [String]
39
39
  # @param [String] value
40
- ParamTag = Struct.new(:name, :type, keyword_init: true)
40
+ ParamTag = Struct.new(:name, :type, keyword_init: true) #: Class[ParamTag]
41
41
  # @!attribute [rw] name
42
42
  # @return [Symbol]
43
43
  # @param [Symbol] value
@@ -61,7 +61,7 @@ module Docscribe
61
61
  # @!attribute [rw] yard_tags
62
62
  # @return [Docscribe::CLI::RbsGen::YardTags?]
63
63
  # @param [Docscribe::CLI::RbsGen::YardTags?] value
64
- MethodDef = Struct.new(:name, :scope, :container, :file, :line, :yard_tags, keyword_init: true)
64
+ MethodDef = Struct.new(:name, :scope, :container, :file, :line, :yard_tags, keyword_init: true) #: Class[MethodDef]
65
65
  # @!attribute [rw] containers
66
66
  # @return [Array<String>]
67
67
  # @param [Array<String>] value
@@ -86,7 +86,7 @@ module Docscribe
86
86
  # @return [Boolean]
87
87
  # @param [Boolean] value
88
88
  WalkContext = Struct.new(:containers, :method_defs, :path, :comment_map, :src_lines, :inside_sclass,
89
- keyword_init: true)
89
+ keyword_init: true) #: Class[WalkContext]
90
90
 
91
91
  class << self
92
92
  # @param [Array<String>] argv
@@ -42,8 +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 warn_invalid_yard
45
46
  ].freeze
46
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
+
47
51
  # Run Docscribe for files or STDIN using the selected mode and strategy.
48
52
  #
49
53
  # Modes:
@@ -145,7 +149,7 @@ module Docscribe
145
149
  #
146
150
  # @param [Docscribe::CLI::Formatters::opts] options parsed CLI options
147
151
  # @param [Docscribe::Config] conf effective config
148
- # @return [Hash<Symbol, Object>] rewrite result with :output key
152
+ # @return [Docscribe::CLI::Run::rewrite_result] rewrite result with :output key
149
153
  def stdin_rewrite_result(options, conf)
150
154
  Docscribe::InlineRewriter.rewrite_with_report(
151
155
  $stdin.read,
@@ -243,7 +247,7 @@ module Docscribe
243
247
  # @param [Hash<String, Object>] result server result with :changed and :changes keys
244
248
  # @param [Array<Docscribe::CLI::Formatters::change>] file_changes change records
245
249
  # @param [String] path file path
246
- # @param [Object] ctx context hash with :display_path, :options, :state keys
250
+ # @param [Docscribe::CLI::Run::run_ctx] ctx context hash with :display_path, :options, :state keys
247
251
  # @return [void]
248
252
  def dispatch_server_result(result, file_changes, path, **ctx)
249
253
  if ctx[:options][:mode] == :check
@@ -326,14 +330,17 @@ module Docscribe
326
330
  #
327
331
  # @param [Hash<String, Object>] change change record from server
328
332
  # @return [Docscribe::CLI::Formatters::change]
329
- def symbolize_change(change)
330
- {
333
+ def symbolize_change(change) # steep:ignore
334
+ hash = {
331
335
  type: change['type'].to_sym,
332
336
  file: change['file'],
333
337
  line: change['line'],
334
338
  method: change['method'],
335
- message: change['message']
339
+ message: change['message'],
340
+ source: change['source']
336
341
  }
342
+ hash[:param] = change['param'] if change['param']
343
+ hash.compact
337
344
  end
338
345
 
339
346
  # Expand CLI path arguments into a sorted list of Ruby files.
@@ -341,6 +348,10 @@ module Docscribe
341
348
  # Directories are expanded recursively to `**/*.rb`.
342
349
  # If no arguments are provided, the current directory is used.
343
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
+ #
344
355
  # @param [Array<String>] args file and/or directory arguments
345
356
  # @return [Array<String>] unique sorted Ruby file paths
346
357
  def expand_paths(args)
@@ -351,7 +362,34 @@ module Docscribe
351
362
  append_expanded_path(files, path)
352
363
  end
353
364
 
354
- 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)
355
393
  end
356
394
 
357
395
  # Append a file or recursively expand a directory into the files array.
@@ -401,7 +439,7 @@ module Docscribe
401
439
  run_exit_code(options, state)
402
440
  end
403
441
 
404
- # Process files in parallel using a Thread pool.
442
+ # Process files in parallel using forked workers.
405
443
  #
406
444
  # @param [Docscribe::CLI::Formatters::opts] options parsed CLI options
407
445
  # @param [Docscribe::Config] conf effective config
@@ -416,53 +454,147 @@ module Docscribe
416
454
  run_exit_code(options, state)
417
455
  end
418
456
 
419
- # @param [Object] options
420
- # @param [Object] conf
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
+ #
463
+ # @param [Docscribe::CLI::Formatters::opts] options
464
+ # @param [Docscribe::Config] conf
421
465
  # @param [Array<String>] paths
422
466
  # @param [Docscribe::CLI::Formatters::state] state
467
+ # @raise [StandardError]
423
468
  # @return [void]
424
469
  def run_parallel_workers(options, conf, paths, state)
425
- pool = {
426
- paths: paths, state: state, options: options, conf: conf,
427
- pwd: Pathname.pwd, mutex: Mutex.new, error_mutex: Mutex.new
428
- }
429
- thread_count = [ENV.fetch('DOCSCRIBE_THREADS', PARALLEL_DEFAULT_THREADS).to_i, 1].max
430
- 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)
431
480
  end
432
481
 
433
- # @param [Hash<Symbol, Object>] pool
434
- # @return [Thread]
435
- def parallel_worker(pool)
436
- Thread.new do
437
- loop do
438
- path = fetch_work(pool[:paths], pool[:mutex]) or break
439
- run_and_merge(path, pool)
440
- 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)
504
+ end
505
+ end
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
441
537
  end
442
538
  end
443
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
444
547
  # @param [Array<String>] paths
445
- # @param [Thread::Mutex] mutex
446
- # @return [String?]
447
- def fetch_work(paths, mutex)
448
- path = nil
449
- mutex.synchronize { path = paths.shift }
450
- 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
451
558
  end
452
559
 
453
- # @param [String] path
454
- # @param [Hash<Symbol, Object>] 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
455
566
  # @raise [StandardError]
456
567
  # @return [void]
457
- # @return [Object] if StandardError
458
- def run_and_merge(path, pool)
568
+ def run_forked_slice(slice, options, conf, writer)
459
569
  local_state = initial_run_state
460
- process_one_file(path, options: pool[:options], conf: pool[:conf], pwd: pool[:pwd], state: local_state)
461
- 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))
462
574
  rescue StandardError => e
463
- 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)
579
+ end
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
464
594
  end
465
595
 
596
+ # Record a worker failure on the shared state.
597
+ #
466
598
  # @param [StandardError] exception
467
599
  # @param [String] path
468
600
  # @param [Docscribe::CLI::Formatters::state] state
@@ -477,6 +609,38 @@ module Docscribe
477
609
  $stderr.print('E')
478
610
  end
479
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
+
480
644
  # Merge a thread-local state into the shared state under mutex protection.
481
645
  #
482
646
  # @param [Docscribe::CLI::Formatters::state] target shared state to merge into
@@ -537,7 +701,9 @@ module Docscribe
537
701
  overrides = options.slice(*CLI_OVERRIDE_KEYS)
538
702
  acc = {} #: Hash[String, untyped]
539
703
  overrides.each do |k, v|
540
- 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)
541
707
  next if v.is_a?(Array) && v.empty?
542
708
 
543
709
  acc[k.to_s] = v
@@ -605,7 +771,7 @@ module Docscribe
605
771
  return unless result
606
772
 
607
773
  dispatch_file_result(path, src: src, out: result[:output], file_changes: result[:changes] || [],
608
- display_path: display_path, options: options, state: state)
774
+ display_path: display_path, options: options, state: state, conf: conf)
609
775
  end
610
776
 
611
777
  # Print progress indicator to stderr when --progress is active.
@@ -629,7 +795,7 @@ module Docscribe
629
795
  # @param [String] src original source code
630
796
  # @param [String] out rewritten source code
631
797
  # @param [Array<Docscribe::CLI::Formatters::change>] file_changes structured change records
632
- # @param [Object] ctx context hash with :options, :state, :display_path, :conf
798
+ # @param [Docscribe::CLI::Run::run_ctx] ctx context hash with :options, :state, :display_path, :conf
633
799
  # @return [void]
634
800
  def dispatch_file_result(path, src:, out:, file_changes:, **ctx)
635
801
  if ctx[:options][:mode] == :check
@@ -687,9 +853,9 @@ module Docscribe
687
853
  # @private
688
854
  # @param [String] path file path
689
855
  # @param [String] src source code
690
- # @param [Hash<Symbol, Object>] ctx context hash with :conf, :display_path, :options, :state keys
856
+ # @param [Docscribe::CLI::Run::run_ctx] ctx context hash with :conf, :display_path, :options, :state keys
691
857
  # @raise [StandardError]
692
- # @return [Hash<Symbol, Object>, nil]
858
+ # @return [Docscribe::CLI::Run::rewrite_result, nil]
693
859
  # @return [nil] if StandardError
694
860
  def rewrite_result_for_path(path, src:, ctx:)
695
861
  conf = ctx[:conf]
@@ -710,7 +876,7 @@ module Docscribe
710
876
  # @private
711
877
  # @param [String] path file path that caused the error
712
878
  # @param [StandardError] error the exception raised during rewriting
713
- # @param [Hash<Symbol, Object>] ctx context hash with :state, :options, :display_path
879
+ # @param [Docscribe::CLI::Run::run_ctx] ctx context hash with :state, :options, :display_path
714
880
  # @return [void]
715
881
  def record_rewrite_error(path, error, ctx)
716
882
  state = ctx[:state]
@@ -733,18 +899,97 @@ module Docscribe
733
899
  # @param [String] src original source code
734
900
  # @param [String] out rewritten source code
735
901
  # @param [Array<Docscribe::CLI::Formatters::change>] file_changes structured change records
736
- # @param [Object] ctx context hash with :display_path, :options, :state keys
902
+ # @param [Docscribe::CLI::Run::run_ctx] ctx context hash with :display_path, :options, :state keys
737
903
  # @return [void]
738
904
  def handle_check_result(path, src:, out:, file_changes:, **ctx)
739
905
  type_mismatches = type_mismatch_changes(file_changes)
740
- has_real_changes = file_changes.any? { |c| !%i[updated_param updated_return].include?(c[:type]) }
906
+ has_real_changes = real_changes?(file_changes)
907
+ return handle_validated_type_mismatch(path, file_changes, type_mismatches, ctx) if validated_mismatch?(ctx, type_mismatches, out, src, has_real_changes)
908
+ return handle_no_changes(path, type_mismatches, ctx) if no_real_changes?(out, src, has_real_changes)
741
909
 
742
- if out == src && !has_real_changes
743
- handle_check_no_changes(path, type_mismatches: type_mismatches, display_path: ctx[:display_path],
744
- options: ctx[:options], state: ctx[:state])
745
- return
746
- end
910
+ handle_failed_check(path, file_changes, ctx)
911
+ end
912
+
913
+ # @private
914
+ # @param [Array<Docscribe::CLI::Formatters::change>] file_changes
915
+ # @return [Boolean]
916
+ def real_changes?(file_changes)
917
+ file_changes.any? { |c| !%i[updated_param updated_return invalid_type].include?(c[:type]) }
918
+ end
919
+
920
+ # @private
921
+ # @param [Docscribe::CLI::Run::run_ctx] ctx
922
+ # @param [Array<Docscribe::CLI::Formatters::change>] type_mismatches
923
+ # @param [String] out
924
+ # @param [String] src
925
+ # @param [Boolean] has_real_changes
926
+ # @return [Boolean]
927
+ def validated_mismatch?(ctx, type_mismatches, out, src, has_real_changes)
928
+ validate_types_enabled?(ctx) && type_mismatches.any? && out == src && !has_real_changes
929
+ end
747
930
 
931
+ # @private
932
+ # @param [Docscribe::CLI::Run::run_ctx] ctx
933
+ # @return [Boolean]
934
+ def validate_types_enabled?(ctx)
935
+ return true if ctx[:options][:validate_types] == true
936
+ return false if ctx[:options][:validate_types] == false
937
+
938
+ ctx[:conf].respond_to?(:validate_types?) && ctx[:conf].validate_types?
939
+ end
940
+
941
+ # @private
942
+ # @param [String] out
943
+ # @param [String] src
944
+ # @param [Boolean] has_real_changes
945
+ # @return [Boolean]
946
+ def no_real_changes?(out, src, has_real_changes)
947
+ out == src && !has_real_changes
948
+ end
949
+
950
+ # @private
951
+ # @param [String] path
952
+ # @param [Array<Docscribe::CLI::Formatters::change>] file_changes
953
+ # @param [Array<Docscribe::CLI::Formatters::change>] type_mismatches
954
+ # @param [Docscribe::CLI::Run::run_ctx] ctx
955
+ # @return [void]
956
+ def handle_validated_type_mismatch(path, file_changes, type_mismatches, ctx)
957
+ handle_failed_check(path, file_changes, ctx)
958
+ # Drop the records the tracker already holds: the same mismatch must
959
+ # not appear (and count) twice in JSON output.
960
+ stored = ctx[:state][:fail_changes][path] || []
961
+ ctx[:state][:fail_changes][path] = stored - type_mismatches
962
+ track_validated_mismatch(type_mismatches, ctx, path)
963
+ end
964
+
965
+ # @private
966
+ # @param [Array<Docscribe::CLI::Formatters::change>] type_mismatches
967
+ # @param [Docscribe::CLI::Run::run_ctx] ctx
968
+ # @param [String] path raw file path, used as the map key so fail and
969
+ # mismatch entries merge in JSON output
970
+ # @return [void]
971
+ def track_validated_mismatch(type_mismatches, ctx, path)
972
+ state = ctx[:state]
973
+ state[:type_mismatch_paths] << path unless state[:type_mismatch_paths].include?(path)
974
+ state[:type_mismatch_changes][path] = type_mismatches
975
+ end
976
+
977
+ # @private
978
+ # @param [String] path
979
+ # @param [Array<Docscribe::CLI::Formatters::change>] type_mismatches
980
+ # @param [Docscribe::CLI::Run::run_ctx] ctx
981
+ # @return [void]
982
+ def handle_no_changes(path, type_mismatches, ctx)
983
+ handle_check_no_changes(path, type_mismatches: type_mismatches, display_path: ctx[:display_path],
984
+ options: ctx[:options], state: ctx[:state])
985
+ end
986
+
987
+ # @private
988
+ # @param [String] path
989
+ # @param [Array<Docscribe::CLI::Formatters::change>] file_changes
990
+ # @param [Docscribe::CLI::Run::run_ctx] ctx
991
+ # @return [void]
992
+ def handle_failed_check(path, file_changes, ctx)
748
993
  handle_check_failed(path, file_changes: file_changes, display_path: ctx[:display_path],
749
994
  options: ctx[:options], state: ctx[:state])
750
995
  end
@@ -755,7 +1000,7 @@ module Docscribe
755
1000
  # @param [Array<Docscribe::CLI::Formatters::change>] file_changes structured change records
756
1001
  # @return [Array<Docscribe::CLI::Formatters::change>]
757
1002
  def type_mismatch_changes(file_changes)
758
- file_changes.select { |c| %i[updated_param updated_return].include?(c[:type]) }
1003
+ file_changes.select { |c| %i[updated_param updated_return invalid_type].include?(c[:type]) }
759
1004
  end
760
1005
 
761
1006
  # Handle check result when there are no real changes.
@@ -809,7 +1054,7 @@ module Docscribe
809
1054
  # @param [String] src original source code
810
1055
  # @param [String] out rewritten source code
811
1056
  # @param [Array<Docscribe::CLI::Formatters::change>] file_changes structured change records
812
- # @param [Object] ctx context hash with :display_path, :options, :state keys
1057
+ # @param [Docscribe::CLI::Run::run_ctx] ctx context hash with :display_path, :options, :state keys
813
1058
  # @raise [StandardError]
814
1059
  # @return [void]
815
1060
  # @return [Object] if StandardError
@@ -827,7 +1072,7 @@ module Docscribe
827
1072
  # @param [String] path file path
828
1073
  # @param [String] out rewritten source code
829
1074
  # @param [Array<Docscribe::CLI::Formatters::change>] file_changes structured change records
830
- # @param [Hash<Symbol, Object>] ctx context hash with :display_path, :options, :state keys
1075
+ # @param [Docscribe::CLI::Run::run_ctx] ctx context hash with :display_path, :options, :state keys
831
1076
  # @return [void]
832
1077
  def apply_correction(path, out, file_changes, ctx)
833
1078
  File.write(path, out)