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.
- checksums.yaml +4 -4
- data/README.md +258 -51
- data/exe/docscribe-client +26 -7
- data/lib/docscribe/cli/config_builder.rb +69 -8
- data/lib/docscribe/cli/config_dump.rb +88 -7
- data/lib/docscribe/cli/coverage.rb +5 -5
- data/lib/docscribe/cli/formatters/json.rb +74 -29
- data/lib/docscribe/cli/formatters/sarif.rb +20 -3
- data/lib/docscribe/cli/options.rb +36 -2
- data/lib/docscribe/cli/rbs_gen.rb +4 -4
- data/lib/docscribe/cli/run.rb +297 -52
- data/lib/docscribe/cli/update_types.rb +61 -17
- data/lib/docscribe/cli.rb +19 -13
- data/lib/docscribe/config/defaults.rb +2 -0
- data/lib/docscribe/config/plugin.rb +4 -4
- data/lib/docscribe/config/rbs.rb +30 -12
- data/lib/docscribe/config/sorbet.rb +3 -1
- data/lib/docscribe/config/template.rb +6 -0
- data/lib/docscribe/config/utils.rb +15 -0
- data/lib/docscribe/config/validation.rb +34 -0
- data/lib/docscribe/config.rb +35 -1
- data/lib/docscribe/infer/behavior.rb +13 -13
- data/lib/docscribe/infer/params.rb +2 -2
- data/lib/docscribe/infer/raises.rb +5 -6
- data/lib/docscribe/infer/returns.rb +1642 -151
- data/lib/docscribe/infer.rb +7 -7
- data/lib/docscribe/inline_rewriter/doc_builder.rb +551 -102
- data/lib/docscribe/inline_rewriter.rb +367 -98
- data/lib/docscribe/plugin/registry.rb +1 -0
- data/lib/docscribe/server/base.rb +73 -21
- data/lib/docscribe/server/client.rb +20 -11
- data/lib/docscribe/server/daemon.rb +209 -23
- data/lib/docscribe/server/protocol.rb +4 -4
- data/lib/docscribe/types/primitive.rb +160 -0
- data/lib/docscribe/types/rbs/provider.rb +5 -2
- data/lib/docscribe/types/sorbet/base_provider.rb +33 -1
- data/lib/docscribe/types/yard/formatter.rb +35 -6
- data/lib/docscribe/types/yard/parser.rb +32 -22
- data/lib/docscribe/types/yard/repair.rb +142 -0
- data/lib/docscribe/types/yard/validator.rb +131 -0
- data/lib/docscribe/validator/generic_compatibility.rb +698 -0
- data/lib/docscribe/validator/type_mismatch_validator.rb +287 -0
- data/lib/docscribe/version.rb +1 -1
- 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 [
|
|
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 [
|
|
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 [
|
|
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 [
|
|
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 [
|
|
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 [
|
|
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 [
|
|
150
|
+
# @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion object
|
|
147
151
|
# @param [Docscribe::Config] config Docscribe configuration object
|
|
148
|
-
# @param [
|
|
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 [
|
|
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 [
|
|
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 [
|
|
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 [
|
|
209
|
+
# @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion object
|
|
206
210
|
# @param [Symbol] name the method name string
|
|
207
|
-
# @return [
|
|
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 [
|
|
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 [
|
|
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 [
|
|
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 [
|
|
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 [
|
|
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 [
|
|
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 [
|
|
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 [
|
|
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 [
|
|
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 [
|
|
516
|
-
# @param [
|
|
517
|
-
# @param [
|
|
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 [
|
|
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 [
|
|
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 [
|
|
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 [
|
|
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
|
-
|
|
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 [
|
|
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 [
|
|
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 [
|
|
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 [
|
|
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 [
|
|
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
|
-
|
|
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 [
|
|
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 [
|
|
887
|
+
# @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion object
|
|
848
888
|
# @param [String] name the method name string
|
|
849
|
-
# @param [
|
|
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 [
|
|
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 [
|
|
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
|
|
1023
|
-
lines
|
|
1024
|
-
|
|
1025
|
-
|
|
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
|
|
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 [
|
|
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 [
|
|
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 [
|
|
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 [
|
|
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 [
|
|
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<
|
|
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 [
|
|
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 [
|
|
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 [
|
|
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<
|
|
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,
|
|
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 [
|
|
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 [
|
|
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 [
|
|
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 [
|
|
2434
|
+
# @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion object
|
|
1986
2435
|
# @param [String] normal_type resolved return type
|
|
1987
|
-
# @return [
|
|
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 [
|
|
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 [
|
|
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<
|
|
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)
|