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
@@ -3,6 +3,10 @@
3
3
  require 'docscribe/plugin'
4
4
  require 'docscribe/infer'
5
5
  require 'docscribe/inline_rewriter/source_helpers'
6
+ require 'docscribe/types/yard/validator'
7
+ require 'docscribe/types/yard/repair'
8
+ require 'docscribe/validator/type_mismatch_validator'
9
+ require 'docscribe/validator/generic_compatibility'
6
10
 
7
11
  module Docscribe
8
12
  module InlineRewriter
@@ -63,9 +67,9 @@ module Docscribe
63
67
  # Build
64
68
  #
65
69
  # @note module_function: defines #build (visibility: private)
66
- # @param [Object] insertion the collected method insertion object
70
+ # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion object
67
71
  # @param [Docscribe::Config] config Docscribe configuration object
68
- # @param [Object] opts additional keyword options forwarded to doc_setup
72
+ # @param [Hash<Symbol, Object>] opts additional keyword options forwarded to doc_setup
69
73
  # @raise [StandardError]
70
74
  # @return [String, nil]
71
75
  # @return [nil] if StandardError
@@ -82,10 +86,10 @@ module Docscribe
82
86
  # Build merge additions
83
87
  #
84
88
  # @note module_function: defines #build_merge_additions (visibility: private)
85
- # @param [Object] insertion the collected method insertion object
89
+ # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion object
86
90
  # @param [Array<String>] existing_lines existing doc comment lines being merged
87
91
  # @param [Docscribe::Config] config Docscribe configuration object
88
- # @param [Object] options additional keyword options forwarded to downstream methods
92
+ # @param [Hash<Symbol, Object>] options additional keyword options forwarded to downstream methods
89
93
  # @raise [StandardError]
90
94
  # @return [String, nil]
91
95
  # @return [nil] if StandardError
@@ -105,12 +109,12 @@ module Docscribe
105
109
  # Build missing merge result
106
110
  #
107
111
  # @note module_function: defines #build_missing_merge_result (visibility: private)
108
- # @param [Object] insertion the collected method insertion object
112
+ # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion object
109
113
  # @param [Array<String>] existing_lines existing doc comment lines being merged
110
114
  # @param [Docscribe::Config] config Docscribe configuration object
111
- # @param [Object] options additional keyword options forwarded to downstream methods
115
+ # @param [Hash<Symbol, Object>] options additional keyword options forwarded to downstream methods
112
116
  # @raise [StandardError]
113
- # @return [Hash<Symbol, Object>]
117
+ # @return [Docscribe::InlineRewriter::DocBuilder::missingMergeResult]
114
118
  # @return [Hash] if StandardError
115
119
  def build_missing_merge_result(insertion, existing_lines:, config:, **options)
116
120
  setup = doc_setup(insertion, config: config, **options)
@@ -127,10 +131,10 @@ module Docscribe
127
131
  # Doc setup
128
132
  #
129
133
  # @note module_function: defines #doc_setup (visibility: private)
130
- # @param [Object] insertion the collected method insertion object
134
+ # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion object
131
135
  # @param [Docscribe::Config] config Docscribe configuration object
132
- # @param [Object] opts additional options
133
- # @return [Hash<Symbol, Object>, nil]
136
+ # @param [Hash<Symbol, Object>] opts additional options
137
+ # @return [Docscribe::InlineRewriter::DocBuilder::setup, nil]
134
138
  def doc_setup(insertion, config:, **opts)
135
139
  node = insertion.node
136
140
  name = SourceHelpers.node_name(node)
@@ -143,10 +147,10 @@ module Docscribe
143
147
  # Build unsafe
144
148
  #
145
149
  # @note module_function: defines #build_unsafe (visibility: private)
146
- # @param [Object] insertion the collected method insertion object
150
+ # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion object
147
151
  # @param [Docscribe::Config] config Docscribe configuration object
148
- # @param [Hash<Symbol, Object>] setup method setup hash with name, normal_type, scope, visibility
149
- # @param [Object] opts additional options including infer_default, fallback_type, treat_options_keyword_as_hash
152
+ # @param [Docscribe::InlineRewriter::DocBuilder::setup] setup method setup hash with name, normal_type, scope, visibility
153
+ # @param [Hash<Symbol, Object>] opts additional options including infer_default, fallback_type, treat_options_keyword_as_hash
150
154
  # @return [String]
151
155
  def build_unsafe(insertion, config:, setup:, **opts)
152
156
  _, pl, rt = build_param_and_raise_info(setup, config, opts)
@@ -160,7 +164,7 @@ module Docscribe
160
164
  # Build param and raise info
161
165
  #
162
166
  # @note module_function: defines #build_param_and_raise_info (visibility: private)
163
- # @param [Hash<Symbol, Object>] setup method setup hash with name, normal_type, scope, visibility
167
+ # @param [Docscribe::InlineRewriter::DocBuilder::setup] setup method setup hash with name, normal_type, scope, visibility
164
168
  # @param [Docscribe::Config] config Docscribe configuration object
165
169
  # @param [Hash<Symbol, Object>] opts additional options including
166
170
  # @return [(Hash<String, String>, nil, Array<String>, nil, Array<String>)]
@@ -179,12 +183,12 @@ module Docscribe
179
183
  # Resolve doc setup
180
184
  #
181
185
  # @note module_function: defines #resolve_doc_setup! (visibility: private)
182
- # @param [Hash<Symbol, Object>] setup method setup hash with name, normal_type, scope, visibility
186
+ # @param [Docscribe::InlineRewriter::DocBuilder::setup] setup method setup hash with name, normal_type, scope, visibility
183
187
  # @param [Parser::AST::Node] node AST node whose source text to extract
184
188
  # @param [Symbol] name the method name string
185
189
  # @param [Docscribe::Config] config Docscribe configuration object
186
190
  # @param [Hash<Symbol, Object>] opts additional options including
187
- # @return [Hash<Symbol, Object>]
191
+ # @return [Docscribe::InlineRewriter::DocBuilder::setup]
188
192
  def resolve_doc_setup!(setup, node, name, config, opts)
189
193
  external_sig = resolve_external_sig(setup[:container], setup[:scope], name, opts[:signature_provider], node)
190
194
  returns_spec = compute_returns_spec(node, config, opts[:param_types], opts[:core_rbs_provider],
@@ -202,9 +206,9 @@ module Docscribe
202
206
  # Extract base setup
203
207
  #
204
208
  # @note module_function: defines #extract_base_setup (visibility: private)
205
- # @param [Object] insertion the collected method insertion object
209
+ # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion object
206
210
  # @param [Symbol] name the method name string
207
- # @return [Hash<Symbol, Object>]
211
+ # @return [Docscribe::InlineRewriter::DocBuilder::setup]
208
212
  def extract_base_setup(insertion, name)
209
213
  n = insertion.node
210
214
  { node: n, name: name, indent: SourceHelpers.line_indent(n), scope: insertion.scope,
@@ -247,10 +251,10 @@ module Docscribe
247
251
  # @param [Parser::AST::Node] node AST node whose source text to extract
248
252
  # @param [Docscribe::Config] config Docscribe configuration object
249
253
  # @param [Hash<String, String>, nil] param_types hash accumulating parameter name-to-type mappings
250
- # @param [Object] core_rbs_provider RBS type provider
254
+ # @param [Docscribe::Types::RBS::Provider, nil] core_rbs_provider RBS type provider
251
255
  # @param [Docscribe::Types::ProviderChain?] signature_provider
252
256
  # @param [String?] container
253
- # @return [Hash<Symbol, Object>]
257
+ # @return [Docscribe::InlineRewriter::DocBuilder::returnsSpec]
254
258
  def compute_returns_spec(node, config, param_types, core_rbs_provider, # rubocop:disable Metrics/ParameterLists
255
259
  signature_provider: nil, container: nil)
256
260
  Docscribe::Infer.returns_spec_from_node(
@@ -264,7 +268,7 @@ module Docscribe
264
268
  #
265
269
  # @note module_function: defines #parse_existing_doc_tags (visibility: private)
266
270
  # @param [Array<String>] lines existing doc comment lines
267
- # @return [Hash<Symbol, Object>] parsed tag info
271
+ # @return [Docscribe::InlineRewriter::DocBuilder::parseInfo] parsed tag info
268
272
  def parse_existing_doc_tags(lines)
269
273
  init = init_parse_info
270
274
  tags_started = false
@@ -343,7 +347,7 @@ module Docscribe
343
347
  #
344
348
  # @note module_function: defines #parse_existing_tag_line (visibility: private)
345
349
  # @param [String] line the doc comment line
346
- # @param [Hash<Symbol, Object>] info mutable parse info accumulator
350
+ # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info mutable parse info accumulator
347
351
  # @param [Boolean] tags_started whether @tags have been seen
348
352
  # @return [Boolean] updated tags_started
349
353
  def parse_existing_tag_line(line, info, tags_started)
@@ -363,7 +367,7 @@ module Docscribe
363
367
  #
364
368
  # @note module_function: defines #start_note_tag (visibility: private)
365
369
  # @param [String] line doc comment line
366
- # @param [Hash<Symbol, Object>] info parse info hash
370
+ # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info parse info hash
367
371
  # @return [void]
368
372
  def start_note_tag(line, info)
369
373
  return if line.match?(/^\s*#\s*@note\s+module_function:/)
@@ -377,7 +381,7 @@ module Docscribe
377
381
  #
378
382
  # @note module_function: defines #append_note_continuation (visibility: private)
379
383
  # @param [String] line doc comment line
380
- # @param [Hash<Symbol, Object>] info parse info hash
384
+ # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info parse info hash
381
385
  # @return [Object]
382
386
  def append_note_continuation(line, info)
383
387
  return unless info[:last_tag] == :note && info[:note_lines].any?
@@ -388,7 +392,7 @@ module Docscribe
388
392
  # Init parse info
389
393
  #
390
394
  # @note module_function: defines #init_parse_info (visibility: private)
391
- # @return [Hash<Symbol, Object>]
395
+ # @return [Docscribe::InlineRewriter::DocBuilder::parseInfo]
392
396
  def init_parse_info
393
397
  {
394
398
  param_names: {}, param_types: {}, param_descriptions: {},
@@ -405,7 +409,7 @@ module Docscribe
405
409
  #
406
410
  # @note module_function: defines #merge_dest_lines (visibility: private)
407
411
  # @param [Array<String>] existing_lines existing doc comment lines to merge into
408
- # @param [Object] ctx merge context hash (setup, insertion, config, info, param_types)
412
+ # @param [Hash<Symbol, Object>] ctx merge context hash (setup, insertion, config, info, param_types)
409
413
  # @return [String, nil]
410
414
  def merge_dest_lines(existing_lines, **ctx)
411
415
  merge_lines_with_context(existing_lines, **ctx)
@@ -415,7 +419,7 @@ module Docscribe
415
419
  #
416
420
  # @note module_function: defines #merge_lines_with_context (visibility: private)
417
421
  # @param [Array<String>] existing_lines existing doc comment lines being merged
418
- # @param [Object] ctx merge context (setup, insertion, config, info, param_types)
422
+ # @param [Hash<Symbol, Object>] ctx merge context (setup, insertion, config, info, param_types)
419
423
  # @return [String]
420
424
  def merge_lines_with_context(existing_lines, **ctx)
421
425
  s = ctx[:setup]
@@ -445,7 +449,7 @@ module Docscribe
445
449
  #
446
450
  # @note module_function: defines #merge_all_tag_lines (visibility: private)
447
451
  # @param [Array<String>] base_ary initial line array
448
- # @param [Object] ctx context hash with setup, config, info, insertion, param_types
452
+ # @param [Hash<Symbol, Object>] ctx context hash with setup, config, info, insertion, param_types
449
453
  # @return [Array<String>]
450
454
  def merge_all_tag_lines(base_ary, **ctx)
451
455
  line_ary = base_ary.dup
@@ -497,9 +501,9 @@ module Docscribe
497
501
  # @note module_function: defines #merge_return_line (visibility: private)
498
502
  # @param [Array<String>] line_ary output line array
499
503
  # @param [String] indent indentation string for doc comment lines
500
- # @param [Hash<Symbol, Object>] setup method setup hash with node, name, types, scope
504
+ # @param [Docscribe::InlineRewriter::DocBuilder::setup] setup method setup hash with node, name, types, scope
501
505
  # @param [Docscribe::Config] config Docscribe configuration object
502
- # @param [Hash<Symbol, Object>] info parse info hash to update with visibility flags
506
+ # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info parse info hash to update with visibility flags
503
507
  # @return [void]
504
508
  def merge_return_line(line_ary, indent, setup, config, info)
505
509
  emit_ret = config.emit_return_tag?(setup[:scope], setup[:visibility])
@@ -512,12 +516,12 @@ module Docscribe
512
516
  # Collect all missing
513
517
  #
514
518
  # @note module_function: defines #collect_all_missing (visibility: private)
515
- # @param [Hash<Symbol, Object>] setup resolved setup hash with node, name, indent, types
516
- # @param [Hash<Symbol, Object>] info parsed existing doc tag information
517
- # @param [Object] insertion the collected method insertion object
519
+ # @param [Docscribe::InlineRewriter::DocBuilder::setup] setup resolved setup hash with node, name, indent, types
520
+ # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info parsed existing doc tag information
521
+ # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion object
518
522
  # @param [Docscribe::Config] config Docscribe configuration object
519
523
  # @param [Hash<Symbol, Object>] options additional options hash forwarded to missing collector
520
- # @return [Hash<Symbol, Object>]
524
+ # @return [Docscribe::InlineRewriter::DocBuilder::missingMergeResult]
521
525
  def collect_all_missing(setup, info, insertion, config, options)
522
526
  s = setup
523
527
  ctx = { node: s[:node], indent: s[:indent], config: config, external_sig: s[:external_sig],
@@ -531,7 +535,7 @@ module Docscribe
531
535
  #
532
536
  # @note module_function: defines #collect_missing_all (visibility: private)
533
537
  # @param [Hash<Symbol, Object>] ctx merged context hash with info and indent
534
- # @return [Hash<Symbol, Object>]
538
+ # @return [Docscribe::InlineRewriter::DocBuilder::missingMergeResult]
535
539
  def collect_missing_all(ctx)
536
540
  lines = [] #: Array[String]
537
541
  reasons = [] #: Array[Hash[Symbol, untyped]]
@@ -549,7 +553,7 @@ module Docscribe
549
553
  #
550
554
  # @note module_function: defines #extract_all_comment_tags (visibility: private)
551
555
  # @param [String] line single comment line
552
- # @param [Hash<Symbol, Object>] info parse info hash
556
+ # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info parse info hash
553
557
  # @return [void]
554
558
  def extract_all_comment_tags(line, info)
555
559
  extract_param_info(line, info[:param_names], info[:param_types], info[:param_descriptions])
@@ -585,7 +589,7 @@ module Docscribe
585
589
  #
586
590
  # @note module_function: defines #extract_return_info (visibility: private)
587
591
  # @param [String] line a single doc comment line to parse
588
- # @param [Hash<Symbol, Object>] info parse info hash to update with return data
592
+ # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info parse info hash to update with return data
589
593
  # @return [void]
590
594
  def extract_return_info(line, info)
591
595
  return unless line.match?(/^\s*#\s*@return\b/)
@@ -595,10 +599,26 @@ module Docscribe
595
599
  return unless (m = content.match(/@return\s+/))
596
600
 
597
601
  return_type, return_desc = parse_return_rest(m.post_match)
598
- info[:return_type] = return_type if return_type
602
+ return unless return_type
603
+ # Rescue-conditional `@return [X] if Error` tags describe rescue
604
+ # branches (see rescue_conditional_returns) and must not overwrite
605
+ # the main return type — otherwise check demands the conditional
606
+ # type while update_types regenerates it, ping-ponging forever.
607
+ return if conditional_return_desc?(return_desc)
608
+
609
+ info[:return_type] = return_type
599
610
  info[:return_description] = return_desc if return_desc
600
611
  end
601
612
 
613
+ # Whether a return description marks a rescue-conditional tag.
614
+ #
615
+ # @note module_function: defines #conditional_return_desc? (visibility: private)
616
+ # @param [String, nil] desc description after the type brackets
617
+ # @return [Boolean] true for "if Error" suffixes
618
+ def conditional_return_desc?(desc)
619
+ desc.to_s.start_with?('if ')
620
+ end
621
+
602
622
  # Parse return type from rest string
603
623
  #
604
624
  # @note module_function: defines #parse_return_rest (visibility: private)
@@ -618,7 +638,7 @@ module Docscribe
618
638
  #
619
639
  # @note module_function: defines #track_last_tag (visibility: private)
620
640
  # @param [String] content
621
- # @param [Hash<Symbol, Object>] info parse info hash
641
+ # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info parse info hash
622
642
  # @return [void]
623
643
  def track_last_tag(content, info)
624
644
  tag = content.match(/@(\w+)/)&.[](1)&.to_sym
@@ -633,7 +653,7 @@ module Docscribe
633
653
  #
634
654
  # @note module_function: defines #append_tag_continuation (visibility: private)
635
655
  # @param [String] content tag continuation text
636
- # @param [Hash<Symbol, Object>] info parse info hash
656
+ # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info parse info hash
637
657
  # @return [void]
638
658
  def append_tag_continuation(content, info)
639
659
  text = content.strip
@@ -647,7 +667,7 @@ module Docscribe
647
667
  #
648
668
  # @note module_function: defines #append_to_return_description (visibility: private)
649
669
  # @param [String] text text to append
650
- # @param [Hash<Symbol, Object>] info parse info hash
670
+ # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info parse info hash
651
671
  # @return [void]
652
672
  def append_to_return_description(text, info)
653
673
  if info[:return_description]
@@ -661,7 +681,7 @@ module Docscribe
661
681
  #
662
682
  # @note module_function: defines #append_to_param_description (visibility: private)
663
683
  # @param [String] text text to append
664
- # @param [Hash<Symbol, Object>] info parse info hash
684
+ # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info parse info hash
665
685
  # @return [void]
666
686
  def append_to_param_description(text, info)
667
687
  pname = info[:last_param]
@@ -678,7 +698,7 @@ module Docscribe
678
698
  #
679
699
  # @note module_function: defines #extract_visibility_info (visibility: private)
680
700
  # @param [String] line a single doc comment line to parse
681
- # @param [Hash<Symbol, Object>] info parse info hash to update with visibility flags
701
+ # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info parse info hash to update with visibility flags
682
702
  # @return [void]
683
703
  def extract_visibility_info(line, info)
684
704
  info[:has_private] ||= line.match?(/^\s*#\s*@private\b/)
@@ -718,17 +738,37 @@ module Docscribe
718
738
  def extract_raise_types_from_line(line)
719
739
  return [] unless line.match?(/^\s*#\s*@raise\b/)
720
740
 
721
- if (m = line.match(/^\s*#\s*@raise\s*\[([^\]]+)\]/))
722
- parse_raise_bracket_list(m[1]) # steep:ignore ArgumentTypeMismatch
723
- elsif (m = line.match(/^\s*#\s*@raise\s+([A-Z]\w*(?:::[A-Z]\w*)*)/))
724
- [m[1]]
725
- else
726
- []
727
- end
741
+ bracketed_raise_types(line) || bare_raise_type(line) || []
728
742
  rescue StandardError
729
743
  []
730
744
  end
731
745
 
746
+ # Bracketed raise types from line
747
+ #
748
+ # @note module_function: defines #bracketed_raise_types (visibility: private)
749
+ # @param [String] line a `@raise` doc line
750
+ # @return [Array<String>, nil]
751
+ def bracketed_raise_types(line)
752
+ m = line.match(/^\s*#\s*@raise\s*\[([^\]]+)\]/)
753
+ return nil unless m
754
+
755
+ captured = m[1]
756
+ captured ? parse_raise_bracket_list(captured) : []
757
+ end
758
+
759
+ # Bare raise type from line
760
+ #
761
+ # @note module_function: defines #bare_raise_type (visibility: private)
762
+ # @param [String] line a `@raise` doc line
763
+ # @return [String, nil]
764
+ def bare_raise_type(line)
765
+ m = line.match(/^\s*#\s*@raise\s+([A-Z]\w*(?:::[A-Z]\w*)*)/)
766
+ return nil unless m
767
+
768
+ captured = m[1]
769
+ captured ? [captured] : []
770
+ end
771
+
732
772
  # Parse raise bracket list
733
773
  #
734
774
  # @note module_function: defines #parse_raise_bracket_list (visibility: private)
@@ -826,7 +866,7 @@ module Docscribe
826
866
  # @param [String] indent indentation string for the doc line
827
867
  # @param [Symbol] visibility method visibility symbol
828
868
  # @param [Docscribe::Config] config Docscribe configuration object
829
- # @param [Hash<Symbol, Object>] info parse info hash to update with visibility flags
869
+ # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info parse info hash to update with visibility flags
830
870
  # @return [Array<String>]
831
871
  def merge_visibility_tag_lines(indent, visibility, config, info)
832
872
  return [] unless config.emit_visibility_tags?
@@ -844,9 +884,9 @@ module Docscribe
844
884
  #
845
885
  # @note module_function: defines #merge_module_function_note_lines (visibility: private)
846
886
  # @param [String] indent indentation string for the doc line
847
- # @param [Object] insertion the collected method insertion object
887
+ # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion object
848
888
  # @param [String] name the method name string
849
- # @param [Hash<Symbol, Object>] info parse info hash to update with visibility flags
889
+ # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info parse info hash to update with visibility flags
850
890
  # @return [Array<String>]
851
891
  def merge_module_function_note_lines(indent, insertion, name, info)
852
892
  return [] unless insertion.respond_to?(:module_function) && insertion.module_function && !info[:has_module_function_note]
@@ -861,7 +901,7 @@ module Docscribe
861
901
  # @param [Parser::AST::Node] node AST node whose source text to extract
862
902
  # @param [String] indent indentation string for the doc line
863
903
  # @param [Docscribe::Config] config Docscribe configuration object
864
- # @param [Object] opts additional options including external_sig, param_types, info
904
+ # @param [Hash<Symbol, Object>] opts additional options including external_sig, param_types, info
865
905
  # @return [Array<String>]
866
906
  def merge_param_lines(node, indent, config:, **opts)
867
907
  return [] unless config.emit_param_tags?
@@ -885,7 +925,7 @@ module Docscribe
885
925
  # @param [Parser::AST::Node] node AST node whose source text to extract
886
926
  # @param [String] indent indentation string for the doc line
887
927
  # @param [Docscribe::Config] config Docscribe configuration object
888
- # @param [Hash<Symbol, Object>] info parse info hash to update with visibility flags
928
+ # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info parse info hash to update with visibility flags
889
929
  # @return [Array<String>]
890
930
  def merge_raise_tag_lines(node, indent, config, info)
891
931
  return [] unless config.emit_raise_tags?
@@ -902,7 +942,7 @@ module Docscribe
902
942
  # @param [String] indent indentation string for the doc line
903
943
  # @param [String] normal_type resolved return type
904
944
  # @param [Docscribe::Config] config Docscribe configuration object
905
- # @param [Object] opts additional options including scope, visibility, info
945
+ # @param [Hash<Symbol, Object>] opts additional options including scope, visibility, info
906
946
  # @return [String, nil]
907
947
  def merge_return_tag_line(indent, normal_type, config:, **opts)
908
948
  return unless config.emit_return_tag?(opts[:scope], opts[:visibility])
@@ -917,7 +957,7 @@ module Docscribe
917
957
  # @param [String] indent indentation string for the doc line
918
958
  # @param [Array<(Array<String>, String)>] rescue_specs rescue type specs
919
959
  # @param [Docscribe::Config] config Docscribe configuration object
920
- # @param [Hash<Symbol, Object>] info parse info hash to update with visibility flags
960
+ # @param [Docscribe::InlineRewriter::DocBuilder::parseInfo] info parse info hash to update with visibility flags
921
961
  # @return [Array<String>]
922
962
  def merge_rescue_return_lines(indent, rescue_specs, config, info)
923
963
  return [] unless config.emit_rescue_conditional_returns?
@@ -933,7 +973,7 @@ module Docscribe
933
973
  # @note module_function: defines #collect_missing_visibility! (visibility: private)
934
974
  # @param [Array<String>] lines array of output doc lines being accumulated
935
975
  # @param [Array<Hash<Symbol, Object>>] reasons array of reason hashes for --explain output
936
- # @param [Object] ctx merged context hash with info and indent
976
+ # @param [Hash<Symbol, Object>] ctx merged context hash with info and indent
937
977
  # @return [void]
938
978
  def collect_missing_visibility!(lines, reasons, **ctx)
939
979
  return unless ctx[:config].emit_visibility_tags?
@@ -975,7 +1015,7 @@ module Docscribe
975
1015
  # @note module_function: defines #collect_missing_module_function_note! (visibility: private)
976
1016
  # @param [Array<String>] lines array of output doc lines being accumulated
977
1017
  # @param [Array<Hash<Symbol, Object>>] reasons array of reason hashes for --explain output
978
- # @param [Object] ctx merged context hash with info and indent
1018
+ # @param [Hash<Symbol, Object>] ctx merged context hash with info and indent
979
1019
  # @return [void]
980
1020
  def collect_missing_module_function_note!(lines, reasons, **ctx)
981
1021
  insertion = ctx[:insertion]
@@ -994,7 +1034,7 @@ module Docscribe
994
1034
  # @note module_function: defines #collect_missing_params! (visibility: private)
995
1035
  # @param [Array<String>] lines array of output doc lines being accumulated
996
1036
  # @param [Array<Hash<Symbol, Object>>] reasons array of reason hashes for --explain output
997
- # @param [Object] ctx merged context hash with info and indent
1037
+ # @param [Hash<Symbol, Object>] ctx merged context hash with info and indent
998
1038
  # @return [void]
999
1039
  def collect_missing_params!(lines, reasons, **ctx)
1000
1040
  return unless ctx[:config].emit_param_tags?
@@ -1019,14 +1059,156 @@ module Docscribe
1019
1059
  pname = extract_param_name_from_param_line(param_line)
1020
1060
  return unless pname
1021
1061
 
1022
- if !ctx[:info][:param_names].include?(pname)
1023
- lines << "#{param_line}\n"
1024
- reasons << { type: :missing_param, message: "missing @param #{pname}", extra: { param: pname } }
1025
- elsif ctx[:external_sig] && ctx[:info][:param_types][pname]
1062
+ if missing_param?(pname, ctx)
1063
+ handle_missing_param(pname, param_line, lines, reasons)
1064
+ elsif existing_param_type?(pname, ctx)
1065
+ handle_existing_param(pname, param_line, lines, reasons, ctx)
1066
+ end
1067
+ end
1068
+
1069
+ # @note module_function: defines #missing_param? (visibility: private)
1070
+ # @param [String] pname
1071
+ # @param [Hash<Symbol, Object>] ctx
1072
+ # @return [Boolean]
1073
+ def missing_param?(pname, ctx)
1074
+ !ctx[:info][:param_names].include?(pname)
1075
+ end
1076
+
1077
+ # @note module_function: defines #existing_param_type? (visibility: private)
1078
+ # @param [String] pname
1079
+ # @param [Hash<Symbol, Object>] ctx
1080
+ # @return [Boolean]
1081
+ def existing_param_type?(pname, ctx)
1082
+ !!ctx[:info][:param_types][pname]
1083
+ end
1084
+
1085
+ # @note module_function: defines #handle_missing_param (visibility: private)
1086
+ # @param [String] pname
1087
+ # @param [String] param_line
1088
+ # @param [Array<String>] lines
1089
+ # @param [Array<Hash<Symbol, Object>>] reasons
1090
+ # @return [void]
1091
+ def handle_missing_param(pname, param_line, lines, reasons)
1092
+ lines << "#{param_line}\n"
1093
+ reasons << { type: :missing_param, message: "missing @param #{pname}", extra: { param: pname } }
1094
+ end
1095
+
1096
+ # @note module_function: defines #handle_existing_param (visibility: private)
1097
+ # @param [String] pname
1098
+ # @param [String] param_line
1099
+ # @param [Array<String>] lines
1100
+ # @param [Array<Hash<Symbol, Object>>] reasons
1101
+ # @param [Hash<Symbol, Object>] ctx
1102
+ # @return [void]
1103
+ def handle_existing_param(pname, param_line, lines, reasons, ctx)
1104
+ yard_type = ctx[:info][:param_types][pname]
1105
+ if warn_invalid_yard_check?(ctx) && invalid_yard_type?(yard_type)
1106
+ handle_invalid_param(pname, param_line, yard_type, lines, reasons)
1107
+ elsif param_needs_update?(ctx)
1026
1108
  collect_updated_param(param_line, pname, lines, reasons, ctx)
1027
1109
  end
1028
1110
  end
1029
1111
 
1112
+ # Emit an `@param` line, repairing the type when a safe repair exists.
1113
+ #
1114
+ # A broken type such as `[Sym bol]` is rewritten to `[Symbol]` instead
1115
+ # of being passed through untouched, so the doc is fixed rather than
1116
+ # merely reported. When no repair can be proven, the original line is
1117
+ # kept and the offense is reported for a human to resolve.
1118
+ #
1119
+ # @note module_function: defines #handle_invalid_param (visibility: private)
1120
+ # @param [String] pname
1121
+ # @param [String] param_line
1122
+ # @param [String] yard_type
1123
+ # @param [Array<String>] lines
1124
+ # @param [Array<Hash<Symbol, Object>>] reasons
1125
+ # @return [void]
1126
+ def handle_invalid_param(pname, param_line, yard_type, lines, reasons) # rubocop:disable Metrics/MethodLength
1127
+ repaired = Docscribe::Types::Yard::Repair.repair(yard_type)
1128
+
1129
+ if repaired
1130
+ lines << "#{replace_param_type(param_line, repaired)}\n"
1131
+ reasons << {
1132
+ type: :invalid_type,
1133
+ message: "invalid YARD type [#{yard_type}] for @param #{pname} (repaired to [#{repaired}])",
1134
+ source: 'syntax',
1135
+ extra: { param: pname, repaired_type: repaired }
1136
+ }
1137
+ return
1138
+ end
1139
+
1140
+ lines << "#{param_line}\n"
1141
+ reasons << {
1142
+ type: :invalid_type,
1143
+ message: "invalid YARD type [#{yard_type}] for @param #{pname}",
1144
+ source: 'syntax',
1145
+ extra: { param: pname }
1146
+ }
1147
+ end
1148
+
1149
+ # Replace the bracketed type in an `@param` line.
1150
+ #
1151
+ # `param_line` reaches here already rebuilt from the AST, so it no
1152
+ # longer carries the original broken type text; the replacement is done
1153
+ # on whatever bracket content is present.
1154
+ #
1155
+ # @note module_function: defines #replace_param_type (visibility: private)
1156
+ # @param [String] param_line
1157
+ # @param [String] new_type
1158
+ # @return [String]
1159
+ def replace_param_type(param_line, new_type)
1160
+ param_line.sub(/\[.*?\]/, "[#{new_type}]")
1161
+ end
1162
+
1163
+ # @note module_function: defines #param_needs_update? (visibility: private)
1164
+ # @param [Hash<Symbol, Object>] ctx
1165
+ # @return [Boolean]
1166
+ def param_needs_update?(ctx)
1167
+ should_validate_param?(ctx) || !!ctx[:external_sig]
1168
+ end
1169
+
1170
+ # Whether a YARD type string has invalid syntax.
1171
+ #
1172
+ # Called from both param (above) and return (below) validation, so no
1173
+ # waterfall placement satisfies the ordering cop — exempt.
1174
+ #
1175
+ # A blank type means "no type given" and is not an error here, but for
1176
+ # `@param [<literal>] name` the bracket content is the whole type, and a
1177
+ # bare literal (empty, `:sym`, `42`, `,`) carries no type information.
1178
+ #
1179
+ # @note module_function: defines #invalid_yard_type? (visibility: private)
1180
+ # @param [String?] type_str
1181
+ # @return [Boolean]
1182
+ def invalid_yard_type?(type_str) # rubocop:disable SortedMethodsByCall/Waterfall
1183
+ return false if type_str.nil?
1184
+ return true if literal_only_yard_type?(type_str)
1185
+ return true if type_str.match?(/\d/)
1186
+ return true if type_str.match?(/[^\x00-\x7F]/)
1187
+
1188
+ !Types::Yard::Validator.valid?(type_str)
1189
+ end
1190
+
1191
+ # Whether a YARD type string is a bare literal instead of a type name.
1192
+ #
1193
+ # @note module_function: defines #literal_only_yard_type? (visibility: private)
1194
+ # @param [String] type_str
1195
+ # @return [Boolean]
1196
+ def literal_only_yard_type?(type_str)
1197
+ stripped = type_str.strip
1198
+ return true if stripped.empty?
1199
+
1200
+ stripped.start_with?(':') || stripped.match?(/\A\d+\z/) || !stripped.match?(/\w/)
1201
+ end
1202
+
1203
+ # Whether param validation should run via inferred/external types.
1204
+ #
1205
+ # @note module_function: defines #should_validate_param? (visibility: private)
1206
+ # @param [Hash<Symbol, Object>] ctx
1207
+ # @return [Boolean]
1208
+ def should_validate_param?(ctx)
1209
+ ctx[:config].respond_to?(:validate_types?) && ctx[:config].validate_types?
1210
+ end
1211
+
1030
1212
  # Collect updated param
1031
1213
  #
1032
1214
  # @note module_function: defines #collect_updated_param (visibility: private)
@@ -1038,12 +1220,48 @@ module Docscribe
1038
1220
  # @return [void]
1039
1221
  def collect_updated_param(param_line, pname, lines, reasons, ctx)
1040
1222
  new_type = extract_param_type_from_param_line(param_line)
1041
- return unless new_type && ctx[:info][:param_types][pname] != new_type
1223
+ return unless param_type_changed?(pname, new_type, ctx)
1224
+ return if fallback_skipped?(new_type, ctx)
1225
+
1226
+ append_param_update(param_line, pname, new_type, lines, reasons, ctx)
1227
+ end
1228
+
1229
+ # @note module_function: defines #param_type_changed? (visibility: private)
1230
+ # @param [String] pname
1231
+ # @param [String, nil] new_type
1232
+ # @param [Hash<Symbol, Object>] ctx
1233
+ # @return [Boolean]
1234
+ def param_type_changed?(pname, new_type, ctx)
1235
+ yard = ctx[:info][:param_types][pname]
1236
+ return false unless new_type && yard
1237
+ return false if normalize_type(yard) == normalize_type(new_type)
1238
+ return false if generic_compatible?(yard, new_type)
1239
+
1240
+ yard != new_type
1241
+ end
1042
1242
 
1243
+ # @note module_function: defines #fallback_skipped? (visibility: private)
1244
+ # @param [String, nil] new_type
1245
+ # @param [Hash<Symbol, Object>] ctx
1246
+ # @return [Boolean]
1247
+ def fallback_skipped?(new_type, ctx)
1248
+ ctx[:config].respond_to?(:validate_types?) && ctx[:config].validate_types? && (new_type == ctx[:config].fallback_type)
1249
+ end
1250
+
1251
+ # @note module_function: defines #append_param_update (visibility: private)
1252
+ # @param [String] param_line
1253
+ # @param [String] pname
1254
+ # @param [String, nil] new_type
1255
+ # @param [Array<String>] lines
1256
+ # @param [Array<Hash<Symbol, Object>>] reasons
1257
+ # @param [Hash<Symbol, Object>] ctx
1258
+ # @return [void]
1259
+ def append_param_update(param_line, pname, new_type, lines, reasons, ctx) # rubocop:disable Metrics/ParameterLists
1043
1260
  lines << "#{param_line}\n" unless ctx[:strategy] == :safe
1044
1261
  reasons << {
1045
1262
  type: :updated_param,
1046
1263
  message: "updated @param #{pname} from #{ctx[:info][:param_types][pname]} to #{new_type}",
1264
+ source: ctx[:external_sig] ? 'rbs' : 'infer',
1047
1265
  extra: { param: pname }
1048
1266
  }
1049
1267
  end
@@ -1071,7 +1289,7 @@ module Docscribe
1071
1289
  # @param [String] indent indentation string for the doc line
1072
1290
  # @param [Docscribe::Config] config Docscribe configuration object
1073
1291
  # @param [Docscribe::Types::MethodSignature, nil] external_sig external method signature for type overrides
1074
- # @param [Object] kwargs additional keyword args including insertion, params_lines, raise_types, override_tags
1292
+ # @param [Hash<Symbol, Object>] kwargs additional keyword args including insertion, params_lines, raise_types, override_tags
1075
1293
  # @return [Array<String>, nil]
1076
1294
  def build_all_param_lines(args, indent, config, external_sig: nil, **kwargs)
1077
1295
  param_lines = [] #: Array[String]
@@ -1101,9 +1319,9 @@ module Docscribe
1101
1319
  # Build doc lines
1102
1320
  #
1103
1321
  # @note module_function: defines #build_doc_lines (visibility: private)
1104
- # @param [Hash<Symbol, Object>] setup method setup hash with indent, name, types, scope
1322
+ # @param [Docscribe::InlineRewriter::DocBuilder::setup] setup method setup hash with indent, name, types, scope
1105
1323
  # @param [Docscribe::Config] config Docscribe configuration object
1106
- # @param [Object] kwargs additional keyword args including insertion, params_lines, raise_types, override_tags
1324
+ # @param [Hash<Symbol, Object>] kwargs additional keyword args including insertion, params_lines, raise_types, override_tags
1107
1325
  # @return [Array<String>]
1108
1326
  def build_doc_lines(setup, config:, **kwargs)
1109
1327
  i = setup[:indent]
@@ -1118,8 +1336,8 @@ module Docscribe
1118
1336
  #
1119
1337
  # @note module_function: defines #assemble_doc_lines (visibility: private)
1120
1338
  # @param [String] indent indent
1121
- # @param [Hash<Symbol, Object>] setup setup
1122
- # @param [Object] ctx context hash with config, insertion, params_lines, raise_types, override_tags
1339
+ # @param [Docscribe::InlineRewriter::DocBuilder::setup] setup setup
1340
+ # @param [Hash<Symbol, Object>] ctx context hash with config, insertion, params_lines, raise_types, override_tags
1123
1341
  # @return [Array<String>]
1124
1342
  def assemble_doc_lines(indent, setup, **ctx)
1125
1343
  line_ary = build_header_lines(
@@ -1138,7 +1356,7 @@ module Docscribe
1138
1356
  # @note module_function: defines #append_assemble_body_lines (visibility: private)
1139
1357
  # @param [Array<String>] line_ary output line array
1140
1358
  # @param [String] indent indentation string for doc comment lines
1141
- # @param [Hash<Symbol, Object>] setup method setup hash with name, types, scope
1359
+ # @param [Docscribe::InlineRewriter::DocBuilder::setup] setup method setup hash with name, types, scope
1142
1360
  # @param [Hash<Symbol, Object>] ctx merged context hash with info and indent
1143
1361
  # @return [void]
1144
1362
  def append_assemble_body_lines(line_ary, indent, setup, ctx)
@@ -1149,7 +1367,7 @@ module Docscribe
1149
1367
  #
1150
1368
  # @note module_function: defines #build_all_body_tags (visibility: private)
1151
1369
  # @param [String] indent indentation string for doc comment lines
1152
- # @param [Hash<Symbol, Object>] setup method setup hash with name, types, scope
1370
+ # @param [Docscribe::InlineRewriter::DocBuilder::setup] setup method setup hash with name, types, scope
1153
1371
  # @param [Hash<Symbol, Object>] ctx merged context hash with info and indent
1154
1372
  # @return [Array<String>]
1155
1373
  def build_all_body_tags(indent, setup, ctx)
@@ -1162,9 +1380,9 @@ module Docscribe
1162
1380
  #
1163
1381
  # @note module_function: defines #core_body_tags (visibility: private)
1164
1382
  # @param [String] indent indentation string for doc comment lines
1165
- # @param [Hash<Symbol, Object>] setup method setup hash with name, types, scope
1383
+ # @param [Docscribe::InlineRewriter::DocBuilder::setup] setup method setup hash with name, types, scope
1166
1384
  # @param [Hash<Symbol, Object>] ctx merged context hash with info and indent
1167
- # @return [Array<Object>]
1385
+ # @return [Array<String>]
1168
1386
  def core_body_tags(indent, setup, ctx)
1169
1387
  config, insertion = ctx.values_at(:config, :insertion)
1170
1388
  [
@@ -1198,7 +1416,7 @@ module Docscribe
1198
1416
  #
1199
1417
  # @note module_function: defines #build_return_line_if_needed (visibility: private)
1200
1418
  # @param [String] indent indentation string for doc comment lines
1201
- # @param [Hash<Symbol, Object>] setup method setup hash with name, normal_type, scope, visibility
1419
+ # @param [Docscribe::InlineRewriter::DocBuilder::setup] setup method setup hash with name, normal_type, scope, visibility
1202
1420
  # @param [Docscribe::Config] config Docscribe configuration object
1203
1421
  # @param [Hash<Symbol, Object>] ctx merged context hash with info and indent
1204
1422
  # @return [Array<String>]
@@ -1232,7 +1450,7 @@ module Docscribe
1232
1450
  # @param [String] indent indentation string for doc comment lines
1233
1451
  # @param [Docscribe::Types::MethodSignature, nil] external_sig external method signature for type overrides
1234
1452
  # @param [Hash<String, String>, nil] param_types_override map of parameter name to override type
1235
- # @param [Object] opts additional options for param formatting (fallback_type, param_tag_style, etc.)
1453
+ # @param [Hash<Symbol, Object>] opts additional options for param formatting (fallback_type, param_tag_style, etc.)
1236
1454
  # @return [Array<String>]
1237
1455
  def build_param_line(arg_node, indent, external_sig, param_types_override, **opts)
1238
1456
  method_name = :"build_#{arg_node.type}_line"
@@ -1253,7 +1471,7 @@ module Docscribe
1253
1471
  # @note module_function: defines #build_header_lines (visibility: private)
1254
1472
  # @param [String] indent indentation string for the doc line
1255
1473
  # @param [Docscribe::Config] config Docscribe configuration object
1256
- # @param [Object] opts additional options including container, method_symbol, name, normal_type
1474
+ # @param [Hash<Symbol, Object>] opts additional options including container, method_symbol, name, normal_type
1257
1475
  # @return [Array<String>]
1258
1476
  def build_header_lines(indent, config:, **opts)
1259
1477
  if config.emit_header?
@@ -1309,7 +1527,7 @@ module Docscribe
1309
1527
  #
1310
1528
  # @note module_function: defines #build_module_function_note_lines (visibility: private)
1311
1529
  # @param [String] indent indentation string for the doc line
1312
- # @param [Object] insertion the collected method insertion object
1530
+ # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion object
1313
1531
  # @param [String] name the method name string
1314
1532
  # @return [Array<String>]
1315
1533
  def build_module_function_note_lines(indent, insertion, name)
@@ -1371,10 +1589,10 @@ module Docscribe
1371
1589
  # Build plugin tag lines
1372
1590
  #
1373
1591
  # @note module_function: defines #build_plugin_tag_lines (visibility: private)
1374
- # @param [Object] insertion the collected method insertion object
1592
+ # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion object
1375
1593
  # @param [String] indent indentation string for the doc line
1376
1594
  # @param [String] normal_type resolved return type
1377
- # @param [Array<Object>, nil] override_tags plugin tag overrides
1595
+ # @param [Array<Docscribe::Plugin::Tag>, nil] override_tags plugin tag overrides
1378
1596
  # @return [Array<String>]
1379
1597
  def build_plugin_tag_lines(insertion, indent, normal_type, override_tags)
1380
1598
  plugin_tags = Docscribe::Plugin.run_tag_plugins(build_plugin_context(insertion, normal_type: normal_type))
@@ -1389,7 +1607,7 @@ module Docscribe
1389
1607
  # @param [String] indent indentation string for doc comment lines
1390
1608
  # @param [Docscribe::Types::MethodSignature, nil] external_sig external method signature for type overrides
1391
1609
  # @param [Hash<String, String>, nil] param_types_override map of parameter name to override type
1392
- # @param [Object] opts additional options for param formatting
1610
+ # @param [Hash<Symbol, Object>] opts additional options for param formatting
1393
1611
  # @return [String]
1394
1612
  def build_arg_line(arg_node, indent, external_sig, param_types_override, **opts)
1395
1613
  pname = arg_node.children.first.to_s
@@ -1407,7 +1625,7 @@ module Docscribe
1407
1625
  # @param [String] indent indentation string for doc comment lines
1408
1626
  # @param [Docscribe::Types::MethodSignature, nil] external_sig external method signature for type overrides
1409
1627
  # @param [Hash<String, String>, nil] param_types_override map of parameter name to override type
1410
- # @param [Object] opts additional options for param formatting
1628
+ # @param [Hash<Symbol, Object>] opts additional options for param formatting
1411
1629
  # @return [Array<String>]
1412
1630
  def build_optarg_lines(arg_node, indent, external_sig, param_types_override, **opts)
1413
1631
  pname, default = *arg_node
@@ -1463,7 +1681,7 @@ module Docscribe
1463
1681
  # @param [String] indent indentation string for doc comment lines
1464
1682
  # @param [Docscribe::Types::MethodSignature, nil] external_sig external method signature for type overrides
1465
1683
  # @param [Hash<String, String>, nil] param_types_override map of parameter name to override type
1466
- # @param [Object] opts additional options for param formatting
1684
+ # @param [Hash<Symbol, Object>] opts additional options for param formatting
1467
1685
  # @return [String]
1468
1686
  def build_kwarg_line(arg_node, indent, external_sig, param_types_override, **opts)
1469
1687
  pname = arg_node.children.first.to_s
@@ -1481,7 +1699,7 @@ module Docscribe
1481
1699
  # @param [String] indent indentation string for doc comment lines
1482
1700
  # @param [Docscribe::Types::MethodSignature, nil] external_sig external method signature for type overrides
1483
1701
  # @param [Hash<String, String>, nil] param_types_override map of parameter name to override type
1484
- # @param [Object] opts additional options for param formatting
1702
+ # @param [Hash<Symbol, Object>] opts additional options for param formatting
1485
1703
  # @return [String]
1486
1704
  def build_kwoptarg_line(arg_node, indent, external_sig, param_types_override, **opts)
1487
1705
  pname, default = *arg_node
@@ -1502,7 +1720,7 @@ module Docscribe
1502
1720
  # @param [String] indent indentation string for doc comment lines
1503
1721
  # @param [Docscribe::Types::MethodSignature, nil] external_sig external method signature for type overrides
1504
1722
  # @param [Hash<String, String>, nil] param_types_override map of parameter name to override type
1505
- # @param [Object] opts additional options for param formatting
1723
+ # @param [Hash<Symbol, Object>] opts additional options for param formatting
1506
1724
  # @return [String]
1507
1725
  def build_restarg_line(arg_node, indent, external_sig, param_types_override, **opts)
1508
1726
  pname = (arg_node.children.first || 'args').to_s
@@ -1523,7 +1741,7 @@ module Docscribe
1523
1741
  # @param [String] indent indentation string for doc comment lines
1524
1742
  # @param [Docscribe::Types::MethodSignature, nil] external_sig external method signature for type overrides
1525
1743
  # @param [Hash<String, String>, nil] param_types_override map of parameter name to override type
1526
- # @param [Object] opts additional options for param formatting
1744
+ # @param [Hash<Symbol, Object>] opts additional options for param formatting
1527
1745
  # @return [String]
1528
1746
  def build_kwrestarg_line(arg_node, indent, external_sig, param_types_override, **opts)
1529
1747
  pname = (arg_node.children.first || 'kwargs').to_s
@@ -1540,7 +1758,7 @@ module Docscribe
1540
1758
  # @param [String] indent indentation string for doc comment lines
1541
1759
  # @param [Docscribe::Types::MethodSignature, nil] external_sig external method signature for type overrides
1542
1760
  # @param [Hash<String, String>, nil] param_types_override map of parameter name to override type
1543
- # @param [Object] opts additional options for param formatting
1761
+ # @param [Hash<Symbol, Object>] opts additional options for param formatting
1544
1762
  # @return [String]
1545
1763
  def build_blockarg_line(arg_node, indent, external_sig, param_types_override, **opts)
1546
1764
  pname = (arg_node.children.first || 'block').to_s
@@ -1558,7 +1776,7 @@ module Docscribe
1558
1776
  # @param [Hash<String, String>, nil] param_types_override map of parameter name to override type
1559
1777
  # @param [String] pname the parameter name string
1560
1778
  # @param [String] infer_name parameter name string or transformed version for inference
1561
- # @param [Object] opts additional options including infer_default, fallback_type, treat_options_keyword_as_hash
1779
+ # @param [Hash<Symbol, Object>] opts additional options including infer_default, fallback_type, treat_options_keyword_as_hash
1562
1780
  # @return [String]
1563
1781
  def lookup_param_type(external_sig, param_types_override, pname, infer_name, **opts)
1564
1782
  external_sig&.param_types&.[](pname) ||
@@ -1705,7 +1923,7 @@ module Docscribe
1705
1923
  #
1706
1924
  # @note module_function: defines #override_param_type_for (visibility: private)
1707
1925
  # @param [String] pname the parameter name to look up
1708
- # @param [Hash<Object, Object>, nil] override_map hash map of parameter name to override type
1926
+ # @param [Hash<Object, String>, nil] override_map hash map of parameter name to override type
1709
1927
  # @return [String, nil]
1710
1928
  def override_param_type_for(pname, override_map)
1711
1929
  return nil unless override_map
@@ -1823,7 +2041,7 @@ module Docscribe
1823
2041
  # @note module_function: defines #collect_missing_raises! (visibility: private)
1824
2042
  # @param [Array<String>] lines array of output doc lines being accumulated
1825
2043
  # @param [Array<Hash<Symbol, Object>>] reasons array of reason hashes for --explain output
1826
- # @param [Object] ctx merged context hash with info and indent
2044
+ # @param [Hash<Symbol, Object>] ctx merged context hash with info and indent
1827
2045
  # @return [void]
1828
2046
  def collect_missing_raises!(lines, reasons, **ctx)
1829
2047
  return unless ctx[:config].emit_raise_tags?
@@ -1843,18 +2061,248 @@ module Docscribe
1843
2061
  # @note module_function: defines #collect_missing_return! (visibility: private)
1844
2062
  # @param [Array<String>] lines array of output doc lines being accumulated
1845
2063
  # @param [Array<Hash<Symbol, Object>>] reasons array of reason hashes for --explain output
1846
- # @param [Object] ctx merged context hash with info and indent
2064
+ # @param [Hash<Symbol, Object>] ctx merged context hash with info and indent
1847
2065
  # @return [void]
1848
2066
  def collect_missing_return!(lines, reasons, **ctx)
1849
2067
  return unless ctx[:config].emit_return_tag?(ctx[:scope], ctx[:visibility])
1850
2068
 
1851
2069
  if !ctx[:info][:has_return]
1852
2070
  record_missing_return(lines, reasons, ctx)
2071
+ elsif invalid_yard_return?(ctx)
2072
+ record_invalid_return(lines, reasons, ctx)
1853
2073
  elsif return_type_changed?(ctx)
1854
2074
  record_updated_return(lines, reasons, ctx)
2075
+ elsif should_validate_return?(ctx) && mismatched_return?(ctx) # rubocop:disable Lint/DuplicateBranch
2076
+ record_updated_return(lines, reasons, ctx)
1855
2077
  end
1856
2078
  end
1857
2079
 
2080
+ # Whether YARD return type has invalid syntax.
2081
+ #
2082
+ # @note module_function: defines #invalid_yard_return? (visibility: private)
2083
+ # @param [Hash<Symbol, Object>] ctx
2084
+ # @return [Boolean]
2085
+ def invalid_yard_return?(ctx)
2086
+ yard = ctx[:info][:return_type]
2087
+ return false unless yard
2088
+ return false unless warn_invalid_yard_check?(ctx)
2089
+
2090
+ invalid_yard_type?(yard)
2091
+ end
2092
+
2093
+ # Whether syntactically broken YARD types should be reported.
2094
+ #
2095
+ # Gated by `warn_invalid_yard` (default true), not by `validate_types`:
2096
+ # syntax validity does not depend on inferred or external types. Both the
2097
+ # param branch and the return branch consult this first.
2098
+ #
2099
+ # @note module_function: defines #warn_invalid_yard_check? (visibility: private)
2100
+ # @param [Hash<Symbol, Object>] ctx
2101
+ # @return [Boolean]
2102
+ def warn_invalid_yard_check?(ctx)
2103
+ ctx[:config].respond_to?(:warn_invalid_yard?) && ctx[:config].warn_invalid_yard?
2104
+ end
2105
+
2106
+ # Record invalid return type.
2107
+ #
2108
+ # @note module_function: defines #record_invalid_return (visibility: private)
2109
+ # @param [Array<String>] lines
2110
+ # @param [Array<Hash<Symbol, Object>>] reasons
2111
+ # @param [Hash<Symbol, Object>] ctx
2112
+ # @return [void]
2113
+ def record_invalid_return(lines, reasons, ctx)
2114
+ yard = ctx[:info][:return_type]
2115
+ lines << "#{ctx[:indent]}# @return [#{ctx[:normal_type]}]\n"
2116
+ reasons << {
2117
+ type: :invalid_type,
2118
+ message: "invalid YARD type [#{yard}] for @return, expected [#{ctx[:normal_type]}]",
2119
+ source: 'syntax'
2120
+ }
2121
+ end
2122
+
2123
+ # Whether return validation should run via inferred types.
2124
+ #
2125
+ # @note module_function: defines #should_validate_return? (visibility: private)
2126
+ # @param [Hash<Symbol, Object>] ctx
2127
+ # @return [Boolean]
2128
+ def should_validate_return?(ctx)
2129
+ ctx[:config].respond_to?(:validate_types?) && ctx[:config].validate_types?
2130
+ end
2131
+
2132
+ # Whether YARD return mismatches expected inferred/external type.
2133
+ #
2134
+ # Silences when expected is fallback (uncertain).
2135
+ #
2136
+ # @note module_function: defines #mismatched_return? (visibility: private)
2137
+ # @param [Hash<Symbol, Object>] ctx
2138
+ # @return [Boolean]
2139
+ def mismatched_return?(ctx)
2140
+ yard, expected, fallback = mismatched_return_types(ctx)
2141
+ return false unless yard && expected
2142
+ return false if expected_suppressed?(expected, fallback)
2143
+
2144
+ method_name = extract_method_name(ctx)
2145
+ return false if yard_compatible?(yard, expected, fallback, method_name: method_name)
2146
+ return false if types_normalized_equal?(yard, expected)
2147
+
2148
+ true
2149
+ end
2150
+
2151
+ # Extract method name for void compatibility dynamic check.
2152
+ #
2153
+ # @note module_function: defines #extract_method_name (visibility: private)
2154
+ # @param [Hash<Symbol, Object>] ctx context hash with insertion or node
2155
+ # @raise [StandardError]
2156
+ # @return [Symbol, nil]
2157
+ # @return [nil] if StandardError
2158
+ def extract_method_name(ctx)
2159
+ insertion = ctx[:insertion]
2160
+ node = insertion&.node || ctx[:node]
2161
+ return nil unless node
2162
+
2163
+ SourceHelpers.node_name(node)
2164
+ rescue StandardError
2165
+ nil
2166
+ end
2167
+
2168
+ # Extract yard/expected/fallback triple for return mismatch check.
2169
+ #
2170
+ # @note module_function: defines #mismatched_return_types (visibility: private)
2171
+ # @param [Hash<Symbol, Object>] ctx
2172
+ # @return [(String?, String?, String)]
2173
+ def mismatched_return_types(ctx)
2174
+ [ctx[:info][:return_type], ctx[:normal_type], ctx[:config].fallback_type]
2175
+ end
2176
+
2177
+ # Whether expected type is suppressed as fallback.
2178
+ #
2179
+ # @note module_function: defines #expected_suppressed? (visibility: private)
2180
+ # @param [String?] expected
2181
+ # @param [String] fallback
2182
+ # @return [Boolean]
2183
+ def expected_suppressed?(expected, fallback)
2184
+ expected == fallback || fallback_union?(expected, fallback)
2185
+ end
2186
+
2187
+ # Whether yard type is compatible with expected via void/union/generic.
2188
+ #
2189
+ # @note module_function: defines #yard_compatible? (visibility: private)
2190
+ # @param [String?] yard
2191
+ # @param [String?] expected
2192
+ # @param [String] fallback
2193
+ # @param [String, Symbol, nil] method_name method name for void compatibility
2194
+ # @return [Boolean]
2195
+ def yard_compatible?(yard, expected, fallback, method_name: nil)
2196
+ void_compatible?(yard, expected, fallback, method_name: method_name) ||
2197
+ yard_in_expected_union?(yard, expected) ||
2198
+ generic_compatible?(yard, expected, method_name: method_name)
2199
+ end
2200
+
2201
+ # Whether types are equal after normalization (including optional "?").
2202
+ #
2203
+ # @note module_function: defines #types_normalized_equal? (visibility: private)
2204
+ # @param [String?] yard
2205
+ # @param [String?] expected
2206
+ # @return [Boolean]
2207
+ def types_normalized_equal?(yard, expected)
2208
+ normalized_equal?(yard, expected) || optional_normalized_equal?(yard, expected)
2209
+ end
2210
+
2211
+ # Whether normalized types are equal.
2212
+ #
2213
+ # @note module_function: defines #normalized_equal? (visibility: private)
2214
+ # @param [String?] yard
2215
+ # @param [String?] expected
2216
+ # @return [Boolean]
2217
+ def normalized_equal?(yard, expected)
2218
+ normalize_type(yard) == normalize_type(expected)
2219
+ end
2220
+
2221
+ # Whether optional-normalized types are equal.
2222
+ #
2223
+ # @note module_function: defines #optional_normalized_equal? (visibility: private)
2224
+ # @param [String?] yard
2225
+ # @param [String?] expected
2226
+ # @return [Boolean]
2227
+ def optional_normalized_equal?(yard, expected)
2228
+ normalize_type(yard).delete_suffix('?') == normalize_type(expected).delete_suffix('?')
2229
+ end
2230
+
2231
+ # Delegates to GenericCompatibility service (dynamic, map-dispatched, no hardcodes).
2232
+ #
2233
+ # @note module_function: defines #generic_compatible? (visibility: private)
2234
+ # @param [String] yard
2235
+ # @param [String] expected
2236
+ # @param [String, Symbol, nil] method_name method name for void compatibility threading
2237
+ # @return [Boolean]
2238
+ def generic_compatible?(yard, expected, method_name: nil)
2239
+ Docscribe::Validator::GenericCompatibility.compatible?(yard, expected, fallback_type: 'Object', method_name: method_name)
2240
+ end
2241
+
2242
+ # Whether yard type is included in expected union (e.g. Boolean in Object, Boolean).
2243
+ #
2244
+ # @note module_function: defines #yard_in_expected_union? (visibility: private)
2245
+ # @param [String] yard
2246
+ # @param [String] expected
2247
+ # @return [Boolean]
2248
+ def yard_in_expected_union?(yard, expected)
2249
+ normalized_yard = normalize_type(yard)
2250
+ expected.split(',').any? { |part| normalize_type(part) == normalized_yard }
2251
+ end
2252
+
2253
+ # Whether void YARD type is compatible with fallback union or initialize/setup dynamic.
2254
+ #
2255
+ # @note module_function: defines #void_compatible? (visibility: private)
2256
+ # @param [String, nil] yard
2257
+ # @param [String, nil] expected
2258
+ # @param [String] fallback
2259
+ # @param [String, Symbol, nil] method_name method name for dynamic check
2260
+ # @return [Boolean]
2261
+ def void_compatible?(yard, expected, fallback, method_name: nil) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/MethodLength, Metrics/AbcSize
2262
+ return false unless normalize_type(yard) == 'void'
2263
+
2264
+ return true if fallback_union?(expected, fallback) ||
2265
+ %w[nil void].include?(normalize_type(expected))
2266
+
2267
+ if method_name.to_s =~ /initialize|setup/
2268
+ norm = normalize_type(expected).delete_suffix('?').strip
2269
+ return true if norm == 'Hash' || norm.start_with?('Hash<') || norm.start_with?('Hash[')
2270
+ return true if %w[self Boolean].include?(norm)
2271
+ end
2272
+
2273
+ if method_name.to_s.end_with?('?')
2274
+ norm = normalize_type(expected).delete_suffix('?').strip
2275
+ return true if norm == 'Boolean'
2276
+ end
2277
+
2278
+ false
2279
+ end
2280
+
2281
+ # Whether a type string is a union of only fallback types (with optional `?`).
2282
+ #
2283
+ # @note module_function: defines #fallback_union? (visibility: private)
2284
+ # @param [String, nil] type_str
2285
+ # @param [String] fallback
2286
+ # @return [Boolean]
2287
+ def fallback_union?(type_str, fallback)
2288
+ return false if type_str.nil? || type_str.strip.empty?
2289
+
2290
+ fallback_norm = normalize_type(fallback)
2291
+ parts = type_str.to_s.split(',').map { |p| normalize_type(p.strip.delete_suffix('?').strip) }
2292
+ parts.all? { |p| p == fallback_norm || p.empty? }
2293
+ end
2294
+
2295
+ # Normalize type string for comparison (unify RBS/YARD syntax).
2296
+ #
2297
+ # @note module_function: defines #normalize_type (visibility: private)
2298
+ # @param [String, nil] type_str
2299
+ # @return [String]
2300
+ def normalize_type(type_str)
2301
+ s = type_str.to_s
2302
+ s = s.sub(/#.*\z/m, '').strip unless s.lstrip.start_with?('#')
2303
+ s.strip.squeeze(' ').gsub('[', '<').gsub(']', '>').gsub(/\buntyped\b/, 'Object').gsub(/\bFALLBACK_TYPE\b/, 'Object')
2304
+ end
2305
+
1858
2306
  # Record missing return
1859
2307
  #
1860
2308
  # @note module_function: defines #record_missing_return (visibility: private)
@@ -1877,7 +2325,8 @@ module Docscribe
1877
2325
  def record_updated_return(lines, reasons, ctx)
1878
2326
  lines << "#{ctx[:indent]}# @return [#{ctx[:normal_type]}]\n" unless ctx[:strategy] == :safe
1879
2327
  reasons << { type: :updated_return,
1880
- message: "updated @return from #{ctx[:info][:return_type]} to #{ctx[:normal_type]}" }
2328
+ message: "updated @return from #{ctx[:info][:return_type]} to #{ctx[:normal_type]}",
2329
+ source: ctx[:external_sig] ? 'rbs' : 'infer' }
1881
2330
  end
1882
2331
 
1883
2332
  # Return type changed
@@ -1894,7 +2343,7 @@ module Docscribe
1894
2343
  # @note module_function: defines #collect_missing_rescue_returns! (visibility: private)
1895
2344
  # @param [Array<String>] lines array of output doc lines being accumulated
1896
2345
  # @param [Array<Hash<Symbol, Object>>] reasons array of reason hashes for --explain output
1897
- # @param [Object] ctx merged context hash with info and indent
2346
+ # @param [Hash<Symbol, Object>] ctx merged context hash with info and indent
1898
2347
  # @return [void]
1899
2348
  def collect_missing_rescue_returns!(lines, reasons, **ctx)
1900
2349
  return unless ctx[:config].emit_rescue_conditional_returns?
@@ -1914,7 +2363,7 @@ module Docscribe
1914
2363
  # @note module_function: defines #collect_missing_plugin_tags! (visibility: private)
1915
2364
  # @param [Array<String>] lines array of output doc lines being accumulated
1916
2365
  # @param [Array<Hash<Symbol, Object>>] reasons array of reason hashes for --explain output
1917
- # @param [Object] ctx merged context hash with info and indent
2366
+ # @param [Hash<Symbol, Object>] ctx merged context hash with info and indent
1918
2367
  # @return [void]
1919
2368
  def collect_missing_plugin_tags!(lines, reasons, **ctx)
1920
2369
  plugin_tags = Docscribe::Plugin.run_tag_plugins(build_plugin_context(ctx[:insertion],
@@ -1927,7 +2376,7 @@ module Docscribe
1927
2376
  # Record plugin tag
1928
2377
  #
1929
2378
  # @note module_function: defines #record_plugin_tag (visibility: private)
1930
- # @param [Object] tag plugin tag object to render and record
2379
+ # @param [Docscribe::Plugin::Tag] tag plugin tag object to render and record
1931
2380
  # @param [Array<String>] lines array of output doc lines being accumulated
1932
2381
  # @param [Array<Hash<Symbol, Object>>] reasons array of reason hashes for --explain output
1933
2382
  # @param [Hash<Symbol, Object>] ctx merged context hash with info and indent
@@ -1944,7 +2393,7 @@ module Docscribe
1944
2393
  #
1945
2394
  # @note module_function: defines #debug_warn (visibility: private)
1946
2395
  # @param [StandardError] error the error that occurred
1947
- # @param [Object] insertion the method insertion being processed
2396
+ # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the method insertion being processed
1948
2397
  # @param [String] name the method name
1949
2398
  # @param [String] phase the processing phase
1950
2399
  # @return [void]
@@ -1958,7 +2407,7 @@ module Docscribe
1958
2407
  # Build debug location
1959
2408
  #
1960
2409
  # @note module_function: defines #build_debug_location (visibility: private)
1961
- # @param [Object] insertion the collected method insertion object
2410
+ # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion object
1962
2411
  # @param [String] name the method name string
1963
2412
  # @return [String]
1964
2413
  def build_debug_location(insertion, name)
@@ -1982,9 +2431,9 @@ module Docscribe
1982
2431
  # Build plugin context
1983
2432
  #
1984
2433
  # @note module_function: defines #build_plugin_context (visibility: private)
1985
- # @param [Object] insertion the collected method insertion object
2434
+ # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion object
1986
2435
  # @param [String] normal_type resolved return type
1987
- # @return [Object]
2436
+ # @return [Docscribe::Plugin::Context]
1988
2437
  def build_plugin_context(insertion, normal_type:)
1989
2438
  node = insertion.node
1990
2439
  source = safe_node_source(node)
@@ -1994,11 +2443,11 @@ module Docscribe
1994
2443
  # New plugin context
1995
2444
  #
1996
2445
  # @note module_function: defines #new_plugin_context (visibility: private)
1997
- # @param [Object] insertion the collected method insertion object
2446
+ # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion object
1998
2447
  # @param [Parser::AST::Node] node AST node whose source text to extract
1999
2448
  # @param [String] source method source text
2000
2449
  # @param [String] normal_type resolved return type
2001
- # @return [Object]
2450
+ # @return [Docscribe::Plugin::Context]
2002
2451
  def new_plugin_context(insertion, node, source, normal_type)
2003
2452
  Docscribe::Plugin::Context.new(
2004
2453
  node: node,
@@ -2028,7 +2477,7 @@ module Docscribe
2028
2477
  # Render plugin tags
2029
2478
  #
2030
2479
  # @note module_function: defines #render_plugin_tags (visibility: private)
2031
- # @param [Array<Object>] tags plugin tag objects
2480
+ # @param [Array<Docscribe::Plugin::Tag>] tags plugin tag objects
2032
2481
  # @param [String] indent indentation string for the doc line
2033
2482
  # @return [Array<String>]
2034
2483
  def render_plugin_tags(tags, indent)