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
|
@@ -40,7 +40,7 @@ module Docscribe
|
|
|
40
40
|
# @param [Symbol?] strategy :safe or :aggressive
|
|
41
41
|
# @param [Boolean?] rewrite compatibility alias for aggressive strategy
|
|
42
42
|
# @param [Boolean?] merge compatibility alias for safe strategy
|
|
43
|
-
# @param [
|
|
43
|
+
# @param [Hash] options additional keyword arguments forwarded to rewrite_with_report
|
|
44
44
|
# @return [String]
|
|
45
45
|
def insert_comments(code, strategy: nil, rewrite: nil, merge: nil, **options)
|
|
46
46
|
strategy = normalize_strategy(strategy: strategy, rewrite: rewrite, merge: merge)
|
|
@@ -54,8 +54,8 @@ module Docscribe
|
|
|
54
54
|
# @param [Symbol?] strategy :safe or :aggressive
|
|
55
55
|
# @param [Boolean?] rewrite compatibility alias for aggressive strategy
|
|
56
56
|
# @param [Boolean?] merge compatibility alias for safe strategy
|
|
57
|
-
# @param [
|
|
58
|
-
# @return [Hash<Symbol, String, Array<
|
|
57
|
+
# @param [Hash] options additional keyword arguments forwarded to downstream helpers
|
|
58
|
+
# @return [Hash<Symbol, String, Array<Docscribe::InlineRewriter::changeRecord>>]
|
|
59
59
|
def rewrite_with_report(code, strategy: nil, rewrite: nil, merge: nil, **options)
|
|
60
60
|
strategy = normalize_strategy(strategy: strategy, rewrite: rewrite, merge: merge)
|
|
61
61
|
validate_strategy!(strategy)
|
|
@@ -72,7 +72,7 @@ module Docscribe
|
|
|
72
72
|
#
|
|
73
73
|
# @param [Parser::Source::Buffer] buffer the source buffer being rewritten
|
|
74
74
|
# @param [Parser::AST::Node] ast the parsed AST of the source code
|
|
75
|
-
# @return [
|
|
75
|
+
# @return [Docscribe::InlineRewriter::pipeline]
|
|
76
76
|
def build_rewrite_pipeline(buffer, ast)
|
|
77
77
|
all = collect_insertions(buffer, ast)
|
|
78
78
|
method_overrides_by_pos = {} #: Hash[Integer, untyped]
|
|
@@ -87,26 +87,90 @@ module Docscribe
|
|
|
87
87
|
|
|
88
88
|
# Dispatch rewrite insertions
|
|
89
89
|
#
|
|
90
|
-
# @param [
|
|
90
|
+
# @param [Docscribe::InlineRewriter::pipeline] pipeline the pipeline hash with rewriter, insertions, and tracking state
|
|
91
91
|
# @param [Parser::Source::Buffer] buffer the source buffer being rewritten
|
|
92
|
-
# @param [
|
|
92
|
+
# @param [Hash] options additional kwargs (config, signature_provider, core_rbs_provider, strategy, file)
|
|
93
93
|
# @return [void]
|
|
94
94
|
def dispatch_rewrite_insertions(pipeline, buffer, **options)
|
|
95
95
|
pipeline[:all].sort_by { |(kind, ins)| plugin_insertion_pos(kind, ins) }
|
|
96
96
|
.reverse_each do |kind, ins|
|
|
97
|
-
|
|
98
|
-
send(method_name, ins, pipeline, buffer, **options) if respond_to?(method_name, true)
|
|
97
|
+
dispatch_single_insertion(kind, ins, pipeline, buffer, **options)
|
|
99
98
|
end
|
|
100
99
|
|
|
101
100
|
apply_merge_inserts!(rewriter: pipeline[:rewriter], buffer: buffer, merge_inserts: pipeline[:merge_inserts])
|
|
102
101
|
end
|
|
103
102
|
|
|
103
|
+
# Dispatch a single insertion, isolating per-method failures.
|
|
104
|
+
#
|
|
105
|
+
# A crash while documenting one method (e.g., unexpected AST shape)
|
|
106
|
+
# must not discard warnings for the rest of the file: the error is
|
|
107
|
+
# reported to stderr and the remaining insertions still apply.
|
|
108
|
+
#
|
|
109
|
+
# @param [Symbol] kind insertion kind (:method, :attr, :plugin)
|
|
110
|
+
# @param [Object] ins the insertion object
|
|
111
|
+
# @param [Docscribe::InlineRewriter::pipeline] pipeline the pipeline hash with rewriter, insertions, and tracking state
|
|
112
|
+
# @param [Parser::Source::Buffer] buffer the source buffer being rewritten
|
|
113
|
+
# @param [Hash] options additional kwargs (config, signature_provider, core_rbs_provider, strategy, file)
|
|
114
|
+
# @raise [StandardError]
|
|
115
|
+
# @return [void]
|
|
116
|
+
# @return [Object] if StandardError
|
|
117
|
+
def dispatch_single_insertion(kind, ins, pipeline, buffer, **options)
|
|
118
|
+
method_name = :"dispatch_#{kind}_insertion"
|
|
119
|
+
return unless respond_to?(method_name, true)
|
|
120
|
+
|
|
121
|
+
send(method_name, ins, pipeline, buffer, **options)
|
|
122
|
+
rescue StandardError => e
|
|
123
|
+
warn_insertion_error(kind, ins, options[:file], e)
|
|
124
|
+
end
|
|
125
|
+
|
|
126
|
+
# Report a skipped insertion to stderr without interrupting the rewrite.
|
|
127
|
+
#
|
|
128
|
+
# @param [Symbol] kind insertion kind (:method, :attr, :plugin)
|
|
129
|
+
# @param [Object] ins the insertion object
|
|
130
|
+
# @param [String, nil] file the file being rewritten
|
|
131
|
+
# @param [StandardError] error the rescued error
|
|
132
|
+
# @return [void]
|
|
133
|
+
def warn_insertion_error(kind, ins, file, error)
|
|
134
|
+
warn "Docscribe: skipping #{insertion_label(kind, ins)} in #{file}: #{error.class}: #{error.message}"
|
|
135
|
+
end
|
|
136
|
+
|
|
137
|
+
# Human-readable label for an insertion used in skip warnings.
|
|
138
|
+
#
|
|
139
|
+
# @param [Symbol] kind insertion kind (:method, :attr, :plugin)
|
|
140
|
+
# @param [Object] ins the insertion object
|
|
141
|
+
# @return [String] label like "method foo at line 12"
|
|
142
|
+
def insertion_label(kind, ins)
|
|
143
|
+
node = insertion_node(ins)
|
|
144
|
+
name = node ? SourceHelpers.node_name(node) : nil
|
|
145
|
+
line = node_line(node)
|
|
146
|
+
label = name ? "#{kind} #{name}" : kind.to_s
|
|
147
|
+
line ? "#{label} at line #{line}" : label
|
|
148
|
+
end
|
|
149
|
+
|
|
150
|
+
# Extract the AST node from an insertion when available.
|
|
151
|
+
#
|
|
152
|
+
# @param [Object] ins the insertion object
|
|
153
|
+
# @return [Parser::AST::Node, nil] the node or nil
|
|
154
|
+
def insertion_node(ins)
|
|
155
|
+
ins.respond_to?(:node) ? ins.node : nil
|
|
156
|
+
end
|
|
157
|
+
|
|
158
|
+
# Source line of a node expression when available.
|
|
159
|
+
#
|
|
160
|
+
# @param [Parser::AST::Node, nil] node an AST node
|
|
161
|
+
# @return [Integer, nil] 1-based line number or nil
|
|
162
|
+
def node_line(node)
|
|
163
|
+
loc = node&.loc
|
|
164
|
+
expr = loc&.expression
|
|
165
|
+
expr&.line
|
|
166
|
+
end
|
|
167
|
+
|
|
104
168
|
# Dispatch method insertion
|
|
105
169
|
#
|
|
106
170
|
# @param [Docscribe::InlineRewriter::Collector::Insertion] ins the attribute insertion object
|
|
107
|
-
# @param [
|
|
171
|
+
# @param [Docscribe::InlineRewriter::pipeline] pipeline the pipeline hash with rewriter, insertions, and tracking state
|
|
108
172
|
# @param [Parser::Source::Buffer] buffer the source buffer
|
|
109
|
-
# @param [
|
|
173
|
+
# @param [Hash] options the full keyword options hash
|
|
110
174
|
# @return [void]
|
|
111
175
|
def dispatch_method_insertion(ins, pipeline, buffer, **options)
|
|
112
176
|
pos = plugin_insertion_pos(:method, ins)
|
|
@@ -124,9 +188,9 @@ module Docscribe
|
|
|
124
188
|
# Dispatch attr insertion
|
|
125
189
|
#
|
|
126
190
|
# @param [Docscribe::InlineRewriter::Collector::AttrInsertion] ins the attribute insertion object
|
|
127
|
-
# @param [
|
|
191
|
+
# @param [Docscribe::InlineRewriter::pipeline] pipeline the pipeline hash with rewriter, insertions, and tracking state
|
|
128
192
|
# @param [Parser::Source::Buffer] buffer the source buffer
|
|
129
|
-
# @param [
|
|
193
|
+
# @param [Hash] options the full keyword options hash
|
|
130
194
|
# @return [void]
|
|
131
195
|
def dispatch_attr_insertion(ins, pipeline, buffer, **options)
|
|
132
196
|
apply_attr_insertion!(
|
|
@@ -138,10 +202,10 @@ module Docscribe
|
|
|
138
202
|
|
|
139
203
|
# Dispatch plugin insertion
|
|
140
204
|
#
|
|
141
|
-
# @param [
|
|
142
|
-
# @param [
|
|
205
|
+
# @param [Docscribe::InlineRewriter::pluginInsertion] ins the attribute insertion object
|
|
206
|
+
# @param [Docscribe::InlineRewriter::pipeline] pipeline the pipeline hash with rewriter, insertions, and tracking state
|
|
143
207
|
# @param [Parser::Source::Buffer] buffer the source buffer
|
|
144
|
-
# @param [
|
|
208
|
+
# @param [Hash] options the full keyword options hash
|
|
145
209
|
# @return [void]
|
|
146
210
|
def dispatch_plugin_insertion(ins, pipeline, buffer, **options)
|
|
147
211
|
apply_plugin_insertion!(
|
|
@@ -158,7 +222,7 @@ module Docscribe
|
|
|
158
222
|
# @param [String] code the Ruby source code string to parse and rewrite
|
|
159
223
|
# @param [Hash<Symbol, Object>] options hash containing :config, :file, and :core_rbs_provider
|
|
160
224
|
# @raise [Docscribe::ParseError]
|
|
161
|
-
# @return [Hash<Symbol, Docscribe::Config, String, Parser::Source::Buffer, Parser::AST::Node, Docscribe::Types::ProviderChain, nil,
|
|
225
|
+
# @return [Hash<Symbol, Docscribe::Config, String, Parser::Source::Buffer, Parser::AST::Node, Docscribe::Types::ProviderChain, nil, Docscribe::Types::RBS::Provider, nil>] rewrite environment with keys
|
|
162
226
|
# :config, :file, :buffer, :ast, :core_rbs_provider
|
|
163
227
|
def setup_rewrite_env(code, options)
|
|
164
228
|
config = options[:config] || Docscribe::Config.load
|
|
@@ -177,9 +241,9 @@ module Docscribe
|
|
|
177
241
|
#
|
|
178
242
|
# @private
|
|
179
243
|
# @param [Docscribe::Config] config the active Docscribe::Config
|
|
180
|
-
# @param [
|
|
244
|
+
# @param [Docscribe::Types::RBS::Provider, nil] core_rbs_provider optional externally-provided core RBS provider
|
|
181
245
|
# @raise [StandardError]
|
|
182
|
-
# @return [
|
|
246
|
+
# @return [Docscribe::Types::RBS::Provider, nil]
|
|
183
247
|
# @return [nil] if StandardError
|
|
184
248
|
def load_core_rbs_provider(config, core_rbs_provider)
|
|
185
249
|
core_rbs_provider || (config.respond_to?(:core_rbs_provider) ? config.core_rbs_provider : nil)
|
|
@@ -193,7 +257,7 @@ module Docscribe
|
|
|
193
257
|
# @private
|
|
194
258
|
# @param [Parser::Source::Buffer] buffer the source buffer to collect insertions from
|
|
195
259
|
# @param [Parser::AST::Node] ast the parsed AST to traverse for collection
|
|
196
|
-
# @return [Array<
|
|
260
|
+
# @return [Array<Docscribe::InlineRewriter::insertionPair>]
|
|
197
261
|
def collect_insertions(buffer, ast)
|
|
198
262
|
collector = Docscribe::InlineRewriter::Collector.new(buffer)
|
|
199
263
|
collector.process(ast)
|
|
@@ -208,10 +272,10 @@ module Docscribe
|
|
|
208
272
|
# Deduplicate insertions
|
|
209
273
|
#
|
|
210
274
|
# @private
|
|
211
|
-
# @param [Array<
|
|
212
|
-
# @param [Hash<Integer,
|
|
275
|
+
# @param [Array<Docscribe::InlineRewriter::insertionPair>] insertions insertions to deduplicate
|
|
276
|
+
# @param [Hash<Integer, Docscribe::InlineRewriter::methodOverride>?] method_overrides_by_pos method-level overrides keyed
|
|
213
277
|
# by insertion position
|
|
214
|
-
# @return [Array<
|
|
278
|
+
# @return [Array<Docscribe::InlineRewriter::insertionPair>]
|
|
215
279
|
def deduplicate_insertions(insertions, method_overrides_by_pos: nil)
|
|
216
280
|
group_by_position(insertions).each_with_object([]) do |(pos, items), result|
|
|
217
281
|
process_dedup_group(pos, items, result, method_overrides_by_pos)
|
|
@@ -222,9 +286,9 @@ module Docscribe
|
|
|
222
286
|
#
|
|
223
287
|
# @private
|
|
224
288
|
# @param [Integer] pos the source begin_pos for the group
|
|
225
|
-
# @param [Array<
|
|
226
|
-
# @param [Array<
|
|
227
|
-
# @param [Hash<Integer,
|
|
289
|
+
# @param [Array<Docscribe::InlineRewriter::insertionPair>] items grouped items to process
|
|
290
|
+
# @param [Array<Docscribe::InlineRewriter::insertionPair>] result accumulated result array
|
|
291
|
+
# @param [Hash<Integer, Docscribe::InlineRewriter::methodOverride>, nil] method_overrides_by_pos hash mapping position to method
|
|
228
292
|
# override data
|
|
229
293
|
# @return [void]
|
|
230
294
|
def process_dedup_group(pos, items, result, method_overrides_by_pos)
|
|
@@ -243,8 +307,8 @@ module Docscribe
|
|
|
243
307
|
# Group by position
|
|
244
308
|
#
|
|
245
309
|
# @private
|
|
246
|
-
# @param [Array<
|
|
247
|
-
# @return [Hash<Integer, Array<
|
|
310
|
+
# @param [Array<Docscribe::InlineRewriter::insertionPair>] insertions insertions to group
|
|
311
|
+
# @return [Hash<Integer, Array<Docscribe::InlineRewriter::insertionPair>>]
|
|
248
312
|
def group_by_position(insertions)
|
|
249
313
|
groups = {} #: Hash[Integer, untyped]
|
|
250
314
|
insertions.each do |kind, ins|
|
|
@@ -257,8 +321,8 @@ module Docscribe
|
|
|
257
321
|
# Find override items
|
|
258
322
|
#
|
|
259
323
|
# @private
|
|
260
|
-
# @param [Array<
|
|
261
|
-
# @return [Array<
|
|
324
|
+
# @param [Array<Docscribe::InlineRewriter::insertionPair>] plugin_items plugin items to check
|
|
325
|
+
# @return [Array<Docscribe::InlineRewriter::insertionPair>]
|
|
262
326
|
def find_override_items(plugin_items)
|
|
263
327
|
plugin_items.select do |_k, ins|
|
|
264
328
|
ins.is_a?(Hash) && ins[:method_override].is_a?(Hash)
|
|
@@ -268,10 +332,10 @@ module Docscribe
|
|
|
268
332
|
# Handle override case
|
|
269
333
|
#
|
|
270
334
|
# @private
|
|
271
|
-
# @param [Array<
|
|
272
|
-
# @param [Array<
|
|
273
|
-
# @param [Array<
|
|
274
|
-
# @param [Hash<Integer,
|
|
335
|
+
# @param [Array<Docscribe::InlineRewriter::insertionPair>] result accumulated result array
|
|
336
|
+
# @param [Array<Docscribe::InlineRewriter::insertionPair>] items all items in group
|
|
337
|
+
# @param [Array<Docscribe::InlineRewriter::insertionPair>] override_items override plugin items
|
|
338
|
+
# @param [Hash<Integer, Docscribe::InlineRewriter::methodOverride>, nil] method_overrides_by_pos hash mapping position to
|
|
275
339
|
# method override data
|
|
276
340
|
# @param [Integer] pos the source position of the conflict
|
|
277
341
|
# @return [void]
|
|
@@ -288,11 +352,11 @@ module Docscribe
|
|
|
288
352
|
# Deduplicate items
|
|
289
353
|
#
|
|
290
354
|
# @private
|
|
291
|
-
# @param [Array<
|
|
292
|
-
# @param [Array<
|
|
355
|
+
# @param [Array<Docscribe::InlineRewriter::insertionPair>] items all items in group
|
|
356
|
+
# @param [Array<Docscribe::InlineRewriter::insertionPair>] plugin_items plugin items in group
|
|
293
357
|
# @param [Integer] pos the source position of the conflict
|
|
294
|
-
# @param [Array<
|
|
295
|
-
# @return [Array<
|
|
358
|
+
# @param [Array<Docscribe::InlineRewriter::insertionPair>] _method_items method items in group
|
|
359
|
+
# @return [Array<Docscribe::InlineRewriter::insertionPair>]
|
|
296
360
|
def deduplicate_items(items, plugin_items, pos, _method_items)
|
|
297
361
|
plugin_doc_items = plugin_items.select { |pair| plugin_doc_item?(pair) }
|
|
298
362
|
|
|
@@ -306,7 +370,7 @@ module Docscribe
|
|
|
306
370
|
# Plugin doc item
|
|
307
371
|
#
|
|
308
372
|
# @private
|
|
309
|
-
# @param [
|
|
373
|
+
# @param [Docscribe::InlineRewriter::insertionPair] pair insertion pair to check
|
|
310
374
|
# @return [Boolean]
|
|
311
375
|
def plugin_doc_item?(pair)
|
|
312
376
|
_k, ins = pair
|
|
@@ -316,10 +380,10 @@ module Docscribe
|
|
|
316
380
|
# Deduplicate plugin doc case
|
|
317
381
|
#
|
|
318
382
|
# @private
|
|
319
|
-
# @param [Array<
|
|
320
|
-
# @param [Array<
|
|
383
|
+
# @param [Array<Docscribe::InlineRewriter::insertionPair>] items all items in group
|
|
384
|
+
# @param [Array<Docscribe::InlineRewriter::insertionPair>] plugin_doc_items plugin doc items
|
|
321
385
|
# @param [Integer] pos the source position of the conflict
|
|
322
|
-
# @return [Array<
|
|
386
|
+
# @return [Array<Docscribe::InlineRewriter::insertionPair>]
|
|
323
387
|
def deduplicate_plugin_doc_case(items, plugin_doc_items, pos)
|
|
324
388
|
items = items.reject { |k, _| k == :method }
|
|
325
389
|
items = items.reject { |pair| override_or_plugin_method?(pair) }
|
|
@@ -336,7 +400,7 @@ module Docscribe
|
|
|
336
400
|
# Override or plugin method
|
|
337
401
|
#
|
|
338
402
|
# @private
|
|
339
|
-
# @param [
|
|
403
|
+
# @param [Docscribe::InlineRewriter::insertionPair] pair insertion pair to check
|
|
340
404
|
# @return [Boolean]
|
|
341
405
|
def override_or_plugin_method?(pair)
|
|
342
406
|
k, ins = pair
|
|
@@ -346,7 +410,7 @@ module Docscribe
|
|
|
346
410
|
# Max plugin priority
|
|
347
411
|
#
|
|
348
412
|
# @private
|
|
349
|
-
# @param [Array<
|
|
413
|
+
# @param [Array<Docscribe::InlineRewriter::insertionPair>] plugin_items plugin items to scan
|
|
350
414
|
# @return [Integer]
|
|
351
415
|
def max_plugin_priority(plugin_items)
|
|
352
416
|
plugin_items.map { |_k, ins| plugin_insertion_priority(ins) }.max || 0
|
|
@@ -355,9 +419,9 @@ module Docscribe
|
|
|
355
419
|
# Filter lower priority plugins
|
|
356
420
|
#
|
|
357
421
|
# @private
|
|
358
|
-
# @param [Array<
|
|
422
|
+
# @param [Array<Docscribe::InlineRewriter::insertionPair>] items items to filter
|
|
359
423
|
# @param [Integer] threshold minimum priority threshold
|
|
360
|
-
# @return [Array<
|
|
424
|
+
# @return [Array<Docscribe::InlineRewriter::insertionPair>]
|
|
361
425
|
def filter_lower_priority_plugins(items, threshold)
|
|
362
426
|
items.select do |k, ins|
|
|
363
427
|
k == :plugin && ins.is_a?(Hash) && ins[:doc] && plugin_insertion_priority(ins) < threshold
|
|
@@ -367,8 +431,8 @@ module Docscribe
|
|
|
367
431
|
# Warn plugin conflict
|
|
368
432
|
#
|
|
369
433
|
# @private
|
|
370
|
-
# @param [Array<
|
|
371
|
-
# @param [Array<
|
|
434
|
+
# @param [Array<Docscribe::InlineRewriter::insertionPair>] dropped dropped plugin items
|
|
435
|
+
# @param [Array<Docscribe::InlineRewriter::insertionPair>] plugin_items kept plugin items
|
|
372
436
|
# @param [Integer] max_prio the maximum priority value
|
|
373
437
|
# @param [Integer] pos the source position of the conflict
|
|
374
438
|
# @return [void]
|
|
@@ -386,7 +450,7 @@ module Docscribe
|
|
|
386
450
|
#
|
|
387
451
|
# @private
|
|
388
452
|
# @param [Integer] pos the source position of the conflict
|
|
389
|
-
# @param [Array<
|
|
453
|
+
# @param [Array<Docscribe::InlineRewriter::insertionPair>] plugin_items plugin items for location
|
|
390
454
|
# @return [String]
|
|
391
455
|
def conflict_location_str(pos, plugin_items)
|
|
392
456
|
line = plugin_insertion_line(plugin_items.first[1])
|
|
@@ -396,9 +460,9 @@ module Docscribe
|
|
|
396
460
|
# Pick highest priority override insertion
|
|
397
461
|
#
|
|
398
462
|
# @private
|
|
399
|
-
# @param [Array<
|
|
463
|
+
# @param [Array<Docscribe::InlineRewriter::insertionPair>] override_items override items to prioritize
|
|
400
464
|
# @param [Integer] pos begin_pos (used only for debug output)
|
|
401
|
-
# @return [
|
|
465
|
+
# @return [Docscribe::InlineRewriter::pluginInsertion, nil] winning insertion hash (the one whose override will be applied)
|
|
402
466
|
def pick_highest_priority_override_insertion(override_items, pos:)
|
|
403
467
|
return nil if override_items.empty?
|
|
404
468
|
|
|
@@ -414,7 +478,7 @@ module Docscribe
|
|
|
414
478
|
# Max plugin priority for
|
|
415
479
|
#
|
|
416
480
|
# @private
|
|
417
|
-
# @param [Array<
|
|
481
|
+
# @param [Array<Docscribe::InlineRewriter::insertionPair>] override_items override items to evaluate
|
|
418
482
|
# @return [Integer]
|
|
419
483
|
def max_plugin_priority_for(override_items)
|
|
420
484
|
override_items.map { |_k, ins| plugin_insertion_priority(ins) }.max || 0
|
|
@@ -423,8 +487,8 @@ module Docscribe
|
|
|
423
487
|
# Sort winners by order
|
|
424
488
|
#
|
|
425
489
|
# @private
|
|
426
|
-
# @param [Array<
|
|
427
|
-
# @return [Array<
|
|
490
|
+
# @param [Array<Docscribe::InlineRewriter::insertionPair>] winners winning items to sort
|
|
491
|
+
# @return [Array<Docscribe::InlineRewriter::insertionPair>]
|
|
428
492
|
def sort_winners_by_order(winners)
|
|
429
493
|
winners.sort_by do |_k, ins|
|
|
430
494
|
order = ins.is_a?(Hash) ? ins[:__docscribe_plugin_order] : nil
|
|
@@ -435,7 +499,7 @@ module Docscribe
|
|
|
435
499
|
# Warn override conflict
|
|
436
500
|
#
|
|
437
501
|
# @private
|
|
438
|
-
# @param [Array<
|
|
502
|
+
# @param [Array<Docscribe::InlineRewriter::insertionPair>] winners_sorted sorted winning items
|
|
439
503
|
# @param [Integer] max_prio the maximum priority value
|
|
440
504
|
# @param [Integer] pos the source position of the conflict
|
|
441
505
|
# @return [void]
|
|
@@ -455,7 +519,7 @@ module Docscribe
|
|
|
455
519
|
# Plugin insertion priority
|
|
456
520
|
#
|
|
457
521
|
# @private
|
|
458
|
-
# @param [
|
|
522
|
+
# @param [Docscribe::InlineRewriter::pluginInsertion, Docscribe::InlineRewriter::Collector::Insertion, Docscribe::InlineRewriter::Collector::AttrInsertion] insertion the collected
|
|
459
523
|
# method insertion (plugin hash or collected insertion object)
|
|
460
524
|
# @raise [StandardError]
|
|
461
525
|
# @return [Integer]
|
|
@@ -471,7 +535,7 @@ module Docscribe
|
|
|
471
535
|
# Plugin insertion label
|
|
472
536
|
#
|
|
473
537
|
# @private
|
|
474
|
-
# @param [
|
|
538
|
+
# @param [Docscribe::InlineRewriter::pluginInsertion, Docscribe::InlineRewriter::Collector::Insertion, Docscribe::InlineRewriter::Collector::AttrInsertion] insertion the collected
|
|
475
539
|
# method insertion (plugin hash or collected insertion object)
|
|
476
540
|
# @raise [StandardError]
|
|
477
541
|
# @return [String]
|
|
@@ -488,7 +552,7 @@ module Docscribe
|
|
|
488
552
|
# Plugin insertion line
|
|
489
553
|
#
|
|
490
554
|
# @private
|
|
491
|
-
# @param [
|
|
555
|
+
# @param [Docscribe::InlineRewriter::pluginInsertion, Docscribe::InlineRewriter::Collector::Insertion, Docscribe::InlineRewriter::Collector::AttrInsertion] insertion the collected
|
|
492
556
|
# method insertion (plugin hash or collected insertion object)
|
|
493
557
|
# @raise [StandardError]
|
|
494
558
|
# @return [Integer, nil]
|
|
@@ -507,7 +571,7 @@ module Docscribe
|
|
|
507
571
|
#
|
|
508
572
|
# @private
|
|
509
573
|
# @param [Symbol] kind :method, :attr, or :plugin
|
|
510
|
-
# @param [
|
|
574
|
+
# @param [Docscribe::InlineRewriter::pluginInsertion] ins insertion to locate
|
|
511
575
|
# @return [Integer]
|
|
512
576
|
def plugin_insertion_pos(kind, ins)
|
|
513
577
|
case kind
|
|
@@ -525,7 +589,7 @@ module Docscribe
|
|
|
525
589
|
# @private
|
|
526
590
|
# @param [Parser::Source::TreeRewriter] rewriter the TreeRewriter accumulating source transformations
|
|
527
591
|
# @param [Parser::Source::Buffer] buffer the source buffer
|
|
528
|
-
# @param [
|
|
592
|
+
# @param [Docscribe::InlineRewriter::pluginInsertion] insertion { anchor_node:, doc: }
|
|
529
593
|
# @param [Symbol] strategy :safe or :aggressive rewrite mode
|
|
530
594
|
# @param [Docscribe::Config] config the active configuration
|
|
531
595
|
# @return [void]
|
|
@@ -725,9 +789,9 @@ module Docscribe
|
|
|
725
789
|
# Apply method insertion
|
|
726
790
|
#
|
|
727
791
|
# @private
|
|
728
|
-
# @param [
|
|
792
|
+
# @param [Hash] options kwargs with insertion, config, rewriter, buffer, strategy, changes, file, doc params
|
|
729
793
|
# @return [void]
|
|
730
|
-
def apply_method_insertion!(**options)
|
|
794
|
+
def apply_method_insertion!(**options) # rubocop:disable Metrics/AbcSize
|
|
731
795
|
insertion = options[:insertion]
|
|
732
796
|
config = options[:config]
|
|
733
797
|
return unless method_insertion_allowed?(insertion, config)
|
|
@@ -735,6 +799,7 @@ module Docscribe
|
|
|
735
799
|
anchor_bol_range, = method_bol_ranges(options[:buffer], insertion)
|
|
736
800
|
params = build_method_insertion_params(insertion, config, options[:signature_provider],
|
|
737
801
|
options[:core_rbs_provider], options[:method_override])
|
|
802
|
+
seed_declared_param_types!(options[:buffer], insertion, params, config, options[:strategy])
|
|
738
803
|
extract_existing_descriptions!(options[:buffer], insertion, params, options[:strategy], config)
|
|
739
804
|
doc = DocBuilder.build(insertion, **params) # steep:ignore
|
|
740
805
|
dispatch_method_insertion_by_strategy!(anchor_bol_range, options, params, doc)
|
|
@@ -806,8 +871,8 @@ module Docscribe
|
|
|
806
871
|
# @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion
|
|
807
872
|
# @param [Docscribe::Config] config the active configuration
|
|
808
873
|
# @param [Docscribe::Types::ProviderChain, nil] signature_provider RBS signature provider
|
|
809
|
-
# @param [
|
|
810
|
-
# @param [
|
|
874
|
+
# @param [Docscribe::Types::RBS::Provider, nil] core_rbs_provider optional externally-provided core RBS provider
|
|
875
|
+
# @param [Docscribe::InlineRewriter::methodOverride, nil] method_override the raw override data
|
|
811
876
|
# @return [Hash<Symbol, Object>]
|
|
812
877
|
def build_method_insertion_params(insertion, config, signature_provider, core_rbs_provider, method_override)
|
|
813
878
|
override = extract_method_override!(method_override)
|
|
@@ -821,7 +886,7 @@ module Docscribe
|
|
|
821
886
|
#
|
|
822
887
|
# @private
|
|
823
888
|
# @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion
|
|
824
|
-
# @param [
|
|
889
|
+
# @param [Hash] options keyword options
|
|
825
890
|
# @return [Hash<Symbol, Hash<String, String>, nil, String, nil, Array<Docscribe::Plugin::Tag>>]
|
|
826
891
|
def build_effective_params(insertion, **options)
|
|
827
892
|
external_sig = resolve_external_signature(insertion, options[:signature_provider])
|
|
@@ -852,8 +917,8 @@ module Docscribe
|
|
|
852
917
|
end
|
|
853
918
|
|
|
854
919
|
# @private
|
|
855
|
-
# @param [
|
|
856
|
-
# @return [(Integer?, Array<
|
|
920
|
+
# @param [Docscribe::InlineRewriter::Collector::Insertion] insertion
|
|
921
|
+
# @return [(Integer?, Array<String>)]
|
|
857
922
|
def extract_param_info(insertion)
|
|
858
923
|
args = DocBuilder.extract_args_from_node(insertion.node)
|
|
859
924
|
empty = [] #: Array[untyped]
|
|
@@ -873,10 +938,112 @@ module Docscribe
|
|
|
873
938
|
DocBuilder.build_param_types_from_node(insertion.node, external_sig: external_sig, config: config)
|
|
874
939
|
end
|
|
875
940
|
|
|
941
|
+
# Fill param types from `@param` tags already present in the source.
|
|
942
|
+
#
|
|
943
|
+
# A declared `@param` is only a fallback: it is a human comment and may lie,
|
|
944
|
+
# so it applies solely where inference left `Object`/`untyped`. Without it a
|
|
945
|
+
# param like `tag_order` stays `Object`, collapsing
|
|
946
|
+
# `map { |t| t.strip }.each_with_index.to_h` to `Hash<Object, ...>`.
|
|
947
|
+
#
|
|
948
|
+
# Safe mode only: aggressive mode deliberately re-infers param types over
|
|
949
|
+
# declared ones, and `validate_types` needs the declared type kept separate
|
|
950
|
+
# so it can report a mismatch.
|
|
951
|
+
#
|
|
952
|
+
# @private
|
|
953
|
+
# @param [Parser::Source::Buffer] buffer the source buffer
|
|
954
|
+
# @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion
|
|
955
|
+
# @param [Hash<Symbol, Object>] params insertion params
|
|
956
|
+
# @param [Docscribe::Config] config the active configuration
|
|
957
|
+
# @param [Symbol] strategy :safe or :aggressive rewrite mode
|
|
958
|
+
# @return [void]
|
|
959
|
+
def seed_declared_param_types!(buffer, insertion, params, config, strategy) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
|
|
960
|
+
return if strategy == :aggressive || config.validate_types?
|
|
961
|
+
|
|
962
|
+
declared = DocBuilder.parse_existing_doc_tags(
|
|
963
|
+
method_doc_comment_info(buffer, insertion)&.dig(:doc_lines) || []
|
|
964
|
+
)[:param_types]
|
|
965
|
+
|
|
966
|
+
# Invalid YARD types must reach the invalid-type fixer untouched.
|
|
967
|
+
declared = (declared || {}).select { |_name, type| valid_yard_type?(type) }
|
|
968
|
+
return if declared.empty?
|
|
969
|
+
|
|
970
|
+
current = params[:param_types] || {}
|
|
971
|
+
params[:param_types] = current.merge(declared) { |_name, inferred, decl| merge_param_type(inferred, decl) }
|
|
972
|
+
end
|
|
973
|
+
|
|
974
|
+
# Combine an inferred param type with a declared `@param` type.
|
|
975
|
+
#
|
|
976
|
+
# The declared type fills gaps and adds generic detail (`Array` ->
|
|
977
|
+
# `Array<String>`), but the AST wins a real conflict because it reflects
|
|
978
|
+
# what the code does, while a `@param` tag is a human comment that can lie.
|
|
979
|
+
#
|
|
980
|
+
# @private
|
|
981
|
+
# @param [String, nil] inferred type derived from the AST
|
|
982
|
+
# @param [String] declared type from the `@param` tag
|
|
983
|
+
# @return [String, nil]
|
|
984
|
+
def merge_param_type(inferred, declared)
|
|
985
|
+
return declared if inferred.nil? || unknown_type?(inferred)
|
|
986
|
+
return inferred if unknown_type?(declared)
|
|
987
|
+
return inferred unless same_base_type?(inferred, declared)
|
|
988
|
+
|
|
989
|
+
type_arity(declared) > type_arity(inferred) ? declared : inferred
|
|
990
|
+
end
|
|
991
|
+
|
|
992
|
+
# Whether two types name the same base type, ignoring generic arguments.
|
|
993
|
+
#
|
|
994
|
+
# @private
|
|
995
|
+
# @param [String] left first type
|
|
996
|
+
# @param [String] right second type
|
|
997
|
+
# @return [Boolean]
|
|
998
|
+
def same_base_type?(left, right)
|
|
999
|
+
base_type_name(left) == base_type_name(right)
|
|
1000
|
+
end
|
|
1001
|
+
|
|
1002
|
+
# Number of generic arguments carried by a type.
|
|
1003
|
+
#
|
|
1004
|
+
# @private
|
|
1005
|
+
# @param [String] type type string
|
|
1006
|
+
# @return [Integer]
|
|
1007
|
+
def type_arity(type)
|
|
1008
|
+
base_type_name(type) == type.to_s.strip ? 0 : 1
|
|
1009
|
+
end
|
|
1010
|
+
|
|
1011
|
+
# Base name of a type, with any generic arguments stripped.
|
|
1012
|
+
#
|
|
1013
|
+
# @private
|
|
1014
|
+
# @param [String] type type string
|
|
1015
|
+
# @return [String]
|
|
1016
|
+
def base_type_name(type)
|
|
1017
|
+
type.to_s.split('<', 2).first.to_s.strip
|
|
1018
|
+
end
|
|
1019
|
+
|
|
1020
|
+
# Whether a param type carries no usable information.
|
|
1021
|
+
#
|
|
1022
|
+
# @private
|
|
1023
|
+
# @param [String, nil] type param type string
|
|
1024
|
+
# @return [Boolean]
|
|
1025
|
+
def unknown_type?(type)
|
|
1026
|
+
type.nil? || %w[Object untyped nil].include?(type)
|
|
1027
|
+
end
|
|
1028
|
+
|
|
1029
|
+
# Whether a declared `@param` type is valid YARD and safe to reuse for inference.
|
|
1030
|
+
#
|
|
1031
|
+
# @private
|
|
1032
|
+
# @param [String, nil] type declared YARD type string
|
|
1033
|
+
# @raise [StandardError] when the YARD type validator fails on odd syntax
|
|
1034
|
+
# @return [Boolean]
|
|
1035
|
+
def valid_yard_type?(type)
|
|
1036
|
+
return false if type.nil? || type.strip.empty?
|
|
1037
|
+
|
|
1038
|
+
Docscribe::Types::Yard::Validator.valid?(type)
|
|
1039
|
+
rescue StandardError
|
|
1040
|
+
false
|
|
1041
|
+
end
|
|
1042
|
+
|
|
876
1043
|
# Apply method insertion aggressive
|
|
877
1044
|
#
|
|
878
1045
|
# @private
|
|
879
|
-
# @param [
|
|
1046
|
+
# @param [Hash] options keyword options
|
|
880
1047
|
# @return [void]
|
|
881
1048
|
def apply_method_insertion_aggressive!(**options)
|
|
882
1049
|
rewriter = options[:rewriter]
|
|
@@ -907,7 +1074,7 @@ module Docscribe
|
|
|
907
1074
|
# Apply method insertion safe
|
|
908
1075
|
#
|
|
909
1076
|
# @private
|
|
910
|
-
# @param [
|
|
1077
|
+
# @param [Hash] options keyword options
|
|
911
1078
|
# @return [void]
|
|
912
1079
|
def apply_method_insertion_safe!(**options)
|
|
913
1080
|
info = method_doc_comment_info(options[:buffer], options[:insertion])
|
|
@@ -922,7 +1089,7 @@ module Docscribe
|
|
|
922
1089
|
# Apply method insertion safe with info
|
|
923
1090
|
#
|
|
924
1091
|
# @private
|
|
925
|
-
# @param [
|
|
1092
|
+
# @param [Hash] options keyword options
|
|
926
1093
|
# @return [void]
|
|
927
1094
|
def apply_method_insertion_safe_with_info!(**options)
|
|
928
1095
|
i = options[:info]
|
|
@@ -941,9 +1108,9 @@ module Docscribe
|
|
|
941
1108
|
# @private
|
|
942
1109
|
# @param [Parser::Source::TreeRewriter] rewriter the TreeRewriter accumulating source transformations
|
|
943
1110
|
# @param [Parser::Source::Buffer] buffer the source buffer being rewritten
|
|
944
|
-
# @param [
|
|
1111
|
+
# @param [Docscribe::InlineRewriter::docInfo] info hash containing existing doc comment block data
|
|
945
1112
|
# @param [String] new_block the newly constructed replacement doc block string
|
|
946
|
-
# @param [
|
|
1113
|
+
# @param [Hash] rest additional kwargs (old_block, merge_result,
|
|
947
1114
|
# @return [void]
|
|
948
1115
|
def commit_safe_doc_outcome(rewriter, buffer, info, new_block, **rest)
|
|
949
1116
|
handle_doc_replacement(rewriter, buffer, info, new_block,
|
|
@@ -969,9 +1136,9 @@ module Docscribe
|
|
|
969
1136
|
# @private
|
|
970
1137
|
# @param [Parser::Source::TreeRewriter] rewriter the TreeRewriter accumulating source transformations
|
|
971
1138
|
# @param [Parser::Source::Buffer] buffer the source buffer being rewritten
|
|
972
|
-
# @param [
|
|
1139
|
+
# @param [Docscribe::InlineRewriter::docInfo] info hash containing existing doc comment block data (start_pos, end_pos, lines)
|
|
973
1140
|
# @param [String] new_block the newly constructed replacement doc block string
|
|
974
|
-
# @param [
|
|
1141
|
+
# @param [Hash] log_opts additional keyword arguments for logging and recording changes
|
|
975
1142
|
# @return [void]
|
|
976
1143
|
def handle_doc_replacement(rewriter, buffer, info, new_block, **log_opts)
|
|
977
1144
|
range = Parser::Source::Range.new(buffer, info[:start_pos], info[:end_pos])
|
|
@@ -987,44 +1154,146 @@ module Docscribe
|
|
|
987
1154
|
# Compute doc replacement
|
|
988
1155
|
#
|
|
989
1156
|
# @private
|
|
990
|
-
# @param [
|
|
1157
|
+
# @param [Docscribe::InlineRewriter::docInfo] info existing doc info
|
|
991
1158
|
# @param [Array<String>] missing_lines new doc lines to add
|
|
992
|
-
# @param [
|
|
1159
|
+
# @param [Hash] options keyword options
|
|
993
1160
|
# @return [(Boolean, String, String)]
|
|
994
1161
|
def compute_doc_replacement(info, missing_lines, **options)
|
|
995
1162
|
dc = options[:config]
|
|
1163
|
+
filter = filter_for_missing(info, missing_lines)
|
|
996
1164
|
sorted = Docscribe::InlineRewriter::DocBlock.merge(
|
|
997
1165
|
info[:doc_lines], missing_lines: [], sort_tags: dc.sort_tags?, tag_order: dc.tag_order
|
|
998
1166
|
)
|
|
999
1167
|
merged = Docscribe::InlineRewriter::DocBlock.merge(
|
|
1000
|
-
info[:doc_lines], missing_lines: missing_lines, sort_tags: dc.sort_tags?, tag_order: dc.tag_order
|
|
1168
|
+
info[:doc_lines], missing_lines: missing_lines, sort_tags: dc.sort_tags?, tag_order: dc.tag_order,
|
|
1169
|
+
filter_existing: filter
|
|
1001
1170
|
)
|
|
1002
1171
|
[sorted != info[:doc_lines], (info[:preserved_lines] + merged).join, info[:lines].join]
|
|
1003
1172
|
end
|
|
1004
1173
|
|
|
1174
|
+
# Build filter for DocBlock.merge when missing lines replace existing invalid tags.
|
|
1175
|
+
#
|
|
1176
|
+
# @private
|
|
1177
|
+
# @param [Docscribe::InlineRewriter::docInfo] info parsed doc info from method_doc_comment_info
|
|
1178
|
+
# @param [Array<String>] missing_lines generated missing lines
|
|
1179
|
+
# @return [Hash<Symbol, Object>] filter for existing entries
|
|
1180
|
+
def filter_for_missing(info, missing_lines)
|
|
1181
|
+
filter = {} #: Hash[Symbol, untyped]
|
|
1182
|
+
doc_lines = Array(info[:doc_lines]) #: Array[String]
|
|
1183
|
+
filter[:return] = true if return_filter_needed?(doc_lines, missing_lines)
|
|
1184
|
+
names = param_names_for_filter(doc_lines, missing_lines)
|
|
1185
|
+
filter[:param_names] = names if names.any?
|
|
1186
|
+
filter
|
|
1187
|
+
end
|
|
1188
|
+
|
|
1189
|
+
# Whether return filter is needed.
|
|
1190
|
+
#
|
|
1191
|
+
# @private
|
|
1192
|
+
# @param [Array<String>] doc_lines existing doc lines
|
|
1193
|
+
# @param [Array<String>] missing_lines generated missing lines
|
|
1194
|
+
# @return [Boolean]
|
|
1195
|
+
def return_filter_needed?(doc_lines, missing_lines)
|
|
1196
|
+
doc_lines.any? { |l| l.include?('@return') } && missing_lines.any? { |l| l.include?('@return') }
|
|
1197
|
+
end
|
|
1198
|
+
|
|
1199
|
+
# Param names that need filtering.
|
|
1200
|
+
#
|
|
1201
|
+
# @private
|
|
1202
|
+
# @param [Array<String>] doc_lines existing doc lines
|
|
1203
|
+
# @param [Array<String>] missing_lines generated missing lines
|
|
1204
|
+
# @return [Array<String>]
|
|
1205
|
+
def param_names_for_filter(doc_lines, missing_lines)
|
|
1206
|
+
missing_names = missing_lines.filter_map { |l| extract_param_name_for_filter(l) }
|
|
1207
|
+
existing_names = doc_lines.filter_map { |l| extract_param_name_for_filter(l) }
|
|
1208
|
+
missing_names & existing_names
|
|
1209
|
+
end
|
|
1210
|
+
|
|
1211
|
+
# Extract param name from a generated @param line for filtering.
|
|
1212
|
+
#
|
|
1213
|
+
# @private
|
|
1214
|
+
# @param [String] line generated param line
|
|
1215
|
+
# @return [String, nil]
|
|
1216
|
+
def extract_param_name_for_filter(line)
|
|
1217
|
+
content = line.sub(/^\s*#\s*/, '')
|
|
1218
|
+
if (m = content.match(/@param\s+(\S+)\s+\[/))
|
|
1219
|
+
return m[1]
|
|
1220
|
+
elsif (m = content.match(/@param\s+\[/))
|
|
1221
|
+
rest = content[(m.end(0) - 1)..] # steep:ignore
|
|
1222
|
+
type_end = rest.index(']') # steep:ignore
|
|
1223
|
+
return rest[(type_end + 1)..].to_s.strip.split(/\s+/).first if type_end # steep:ignore
|
|
1224
|
+
end
|
|
1225
|
+
|
|
1226
|
+
nil
|
|
1227
|
+
end
|
|
1228
|
+
|
|
1005
1229
|
# Log method doc changes
|
|
1006
1230
|
#
|
|
1007
1231
|
# @private
|
|
1008
1232
|
# @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion
|
|
1009
1233
|
# @param [Hash<Symbol, Object>] merge_result merge operation result
|
|
1010
|
-
# @param [
|
|
1234
|
+
# @param [Hash] rest additional keyword arguments forwarded to add_change
|
|
1011
1235
|
# @return [void]
|
|
1012
1236
|
def log_method_doc_changes!(insertion:, merge_result:, **rest)
|
|
1013
1237
|
reason_specs = merge_result[:reasons] || []
|
|
1014
|
-
|
|
1238
|
+
return unless doc_changed?(rest, reason_specs)
|
|
1015
1239
|
|
|
1016
|
-
|
|
1240
|
+
log_reasons(reason_specs, insertion, rest)
|
|
1241
|
+
end
|
|
1017
1242
|
|
|
1018
|
-
|
|
1019
|
-
|
|
1020
|
-
|
|
1021
|
-
|
|
1243
|
+
# @private
|
|
1244
|
+
# @param [Hash<Symbol, Object>] rest
|
|
1245
|
+
# @param [Array<Hash<Symbol, Object>>] reason_specs
|
|
1246
|
+
# @return [Boolean]
|
|
1247
|
+
def doc_changed?(rest, reason_specs)
|
|
1248
|
+
rest[:new_block] != rest[:old_block] || type_mismatch_reasons?(reason_specs)
|
|
1249
|
+
end
|
|
1250
|
+
|
|
1251
|
+
# @private
|
|
1252
|
+
# @param [Array<Hash<Symbol, Object>>] reason_specs
|
|
1253
|
+
# @return [Boolean]
|
|
1254
|
+
def type_mismatch_reasons?(reason_specs)
|
|
1255
|
+
reason_specs.any? { |r| type_mismatch_type?(r[:type]) }
|
|
1256
|
+
end
|
|
1257
|
+
|
|
1258
|
+
# @private
|
|
1259
|
+
# @param [Symbol] type
|
|
1260
|
+
# @return [Boolean]
|
|
1261
|
+
def type_mismatch_type?(type)
|
|
1262
|
+
%i[updated_param updated_return invalid_type].include?(type)
|
|
1263
|
+
end
|
|
1264
|
+
|
|
1265
|
+
# @private
|
|
1266
|
+
# @param [Array<Hash<Symbol, Object>>] reason_specs
|
|
1267
|
+
# @param [Docscribe::InlineRewriter::Collector::Insertion] insertion
|
|
1268
|
+
# @param [Hash<Symbol, Object>] rest
|
|
1269
|
+
# @return [void]
|
|
1270
|
+
def log_reasons(reason_specs, insertion, rest)
|
|
1271
|
+
reason_specs.each { |reason| log_single_reason(reason, insertion, rest) }
|
|
1272
|
+
end
|
|
1273
|
+
|
|
1274
|
+
# @private
|
|
1275
|
+
# @param [Hash<Symbol, Object>] reason
|
|
1276
|
+
# @param [Docscribe::InlineRewriter::Collector::Insertion] insertion
|
|
1277
|
+
# @param [Hash<Symbol, Object>] rest
|
|
1278
|
+
# @return [void]
|
|
1279
|
+
def log_single_reason(reason, insertion, rest)
|
|
1280
|
+
add_change(changes: rest[:changes], type: reason[:type], insertion: insertion,
|
|
1281
|
+
file: rest[:file], message: reason[:message], extra: extra_for_reason(reason))
|
|
1282
|
+
end
|
|
1283
|
+
|
|
1284
|
+
# @private
|
|
1285
|
+
# @param [Hash<Symbol, Object>] reason
|
|
1286
|
+
# @return [Hash<Symbol, Object>]
|
|
1287
|
+
def extra_for_reason(reason)
|
|
1288
|
+
extra = (reason[:extra] || {}).dup
|
|
1289
|
+
extra[:source] = reason[:source] if reason[:source]
|
|
1290
|
+
extra
|
|
1022
1291
|
end
|
|
1023
1292
|
|
|
1024
1293
|
# Apply method insertion safe without info
|
|
1025
1294
|
#
|
|
1026
1295
|
# @private
|
|
1027
|
-
# @param [
|
|
1296
|
+
# @param [Hash] options keyword options
|
|
1028
1297
|
# @return [void]
|
|
1029
1298
|
def apply_method_insertion_safe_without_info!(**options)
|
|
1030
1299
|
rewriter = options[:rewriter]
|
|
@@ -1042,13 +1311,13 @@ module Docscribe
|
|
|
1042
1311
|
|
|
1043
1312
|
# Filter options to keep only doc-building params for safe-without-info mode.
|
|
1044
1313
|
# @private
|
|
1045
|
-
# @param [
|
|
1314
|
+
# @param [Hash[Symbol, untyped]] options the full options hash to filter
|
|
1046
1315
|
# @return [Object]
|
|
1047
1316
|
|
|
1048
1317
|
# Add change
|
|
1049
1318
|
#
|
|
1050
1319
|
# @private
|
|
1051
|
-
# @param [
|
|
1320
|
+
# @param [Hash] options kwargs for change record (type, file, line, method, message, insertion, changes, extra)
|
|
1052
1321
|
# @return [void]
|
|
1053
1322
|
def add_change(**options)
|
|
1054
1323
|
changes = options[:changes]
|
|
@@ -1074,7 +1343,7 @@ module Docscribe
|
|
|
1074
1343
|
# Apply attr insertion
|
|
1075
1344
|
#
|
|
1076
1345
|
# @private
|
|
1077
|
-
# @param [
|
|
1346
|
+
# @param [Hash] options kwargs (insertion, config, rewriter, buffer, strategy,
|
|
1078
1347
|
# @return [void]
|
|
1079
1348
|
def apply_attr_insertion!(**options)
|
|
1080
1349
|
config = options[:config]
|
|
@@ -1166,7 +1435,7 @@ module Docscribe
|
|
|
1166
1435
|
# @param [Hash<Integer, Array<(Integer, String)>>] merge_inserts deferred merge inserts
|
|
1167
1436
|
# @param [Docscribe::Config] config the active Docscribe::Config
|
|
1168
1437
|
# @param [Docscribe::Types::ProviderChain, nil] signature_provider external RBS signature provider
|
|
1169
|
-
# @return [
|
|
1438
|
+
# @return [Array<(Integer, String)>, nil]
|
|
1170
1439
|
def merge_attr_additions!(insertion:, info:, merge_inserts:, config:, signature_provider:)
|
|
1171
1440
|
additions = build_attr_merge_additions(ins: insertion, existing_lines: info[:lines],
|
|
1172
1441
|
config: config, signature_provider: signature_provider)
|
|
@@ -1262,7 +1531,7 @@ module Docscribe
|
|
|
1262
1531
|
end
|
|
1263
1532
|
|
|
1264
1533
|
# @private
|
|
1265
|
-
# @param [
|
|
1534
|
+
# @param [Docscribe::InlineRewriter::Collector::AttrInsertion] ins
|
|
1266
1535
|
# @param [Array<String>] existing_lines
|
|
1267
1536
|
# @param [String] indent
|
|
1268
1537
|
# @param [Docscribe::Config] config
|
|
@@ -1282,7 +1551,7 @@ module Docscribe
|
|
|
1282
1551
|
end
|
|
1283
1552
|
|
|
1284
1553
|
# @private
|
|
1285
|
-
# @param [
|
|
1554
|
+
# @param [Docscribe::InlineRewriter::Collector::AttrInsertion] ins
|
|
1286
1555
|
# @param [Array<String>] existing_lines
|
|
1287
1556
|
# @param [String] indent
|
|
1288
1557
|
# @param [Docscribe::Config] config
|
|
@@ -1313,7 +1582,7 @@ module Docscribe
|
|
|
1313
1582
|
#
|
|
1314
1583
|
# @private
|
|
1315
1584
|
# @param [Array<String>] lines array of existing doc comment lines
|
|
1316
|
-
# @return [Hash<String,
|
|
1585
|
+
# @return [Hash<String, Boolean>]
|
|
1317
1586
|
def existing_attr_names(lines)
|
|
1318
1587
|
names = {} #: Hash[String, bool]
|
|
1319
1588
|
|
|
@@ -1480,7 +1749,7 @@ module Docscribe
|
|
|
1480
1749
|
# @param [Docscribe::InlineRewriter::Collector::AttrInsertion] ins the attribute insertion object
|
|
1481
1750
|
# @param [Symbol] name_sym the attribute name as a Symbol
|
|
1482
1751
|
# @param [String] indent whitespace indentation prefix
|
|
1483
|
-
# @param [
|
|
1752
|
+
# @param [Hash] opts additional keyword arguments forwarded from build_attr_doc_lines
|
|
1484
1753
|
# @return [Array<String>]
|
|
1485
1754
|
def build_single_attr_lines(ins, name_sym, indent:, **opts)
|
|
1486
1755
|
cfg = opts[:config]
|
|
@@ -1500,7 +1769,7 @@ module Docscribe
|
|
|
1500
1769
|
# @param [String] indent whitespace indentation prefix
|
|
1501
1770
|
# @param [String] attr_type the resolved type string for the attribute
|
|
1502
1771
|
# @param [Symbol] access the access level (:r, :w, or :rw)
|
|
1503
|
-
# @return [
|
|
1772
|
+
# @return [Array<String>, nil]
|
|
1504
1773
|
def append_attr_return_tag(lines, indent, attr_type, access)
|
|
1505
1774
|
lines << "#{indent}# @return [#{attr_type}]" if %i[r rw].include?(access)
|
|
1506
1775
|
end
|
|
@@ -1513,7 +1782,7 @@ module Docscribe
|
|
|
1513
1782
|
# @param [String] attr_type the resolved type string for the attribute
|
|
1514
1783
|
# @param [Symbol] access the access level (:r, :w, or :rw)
|
|
1515
1784
|
# @param [Docscribe::Config] cfg the active Docscribe::Config
|
|
1516
|
-
# @return [
|
|
1785
|
+
# @return [Array<String>, nil]
|
|
1517
1786
|
def append_attr_param_tag(lines, indent, attr_type, access, cfg)
|
|
1518
1787
|
return unless %i[w rw].include?(access)
|
|
1519
1788
|
|
|
@@ -1582,7 +1851,7 @@ module Docscribe
|
|
|
1582
1851
|
# @param [String] code the source code being processed
|
|
1583
1852
|
# @param [String] file the file name
|
|
1584
1853
|
# @raise [StandardError]
|
|
1585
|
-
# @return [
|
|
1854
|
+
# @return [Docscribe::Types::ProviderChain, Docscribe::Types::RBS::Provider, nil]
|
|
1586
1855
|
# @return [Docscribe::Types::RBS::Provider, nil?] if StandardError
|
|
1587
1856
|
def build_signature_provider(config, code, file)
|
|
1588
1857
|
if config.respond_to?(:signature_provider_for)
|
|
@@ -1601,7 +1870,7 @@ module Docscribe
|
|
|
1601
1870
|
# @private
|
|
1602
1871
|
# @param [Parser::Source::Buffer] buffer the source buffer
|
|
1603
1872
|
# @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion
|
|
1604
|
-
# @return [
|
|
1873
|
+
# @return [Docscribe::InlineRewriter::docInfo, nil] doc comment block info or nil
|
|
1605
1874
|
def method_doc_comment_info(buffer, insertion)
|
|
1606
1875
|
anchor_bol_range, def_bol_range = method_bol_ranges(buffer, insertion)
|
|
1607
1876
|
|
|
@@ -1665,8 +1934,8 @@ module Docscribe
|
|
|
1665
1934
|
# Extract method override
|
|
1666
1935
|
#
|
|
1667
1936
|
# @private
|
|
1668
|
-
# @param [
|
|
1669
|
-
# @return [
|
|
1937
|
+
# @param [Docscribe::InlineRewriter::methodOverride, nil] method_override the raw override data
|
|
1938
|
+
# @return [Docscribe::InlineRewriter::methodOverride] normalized override hash
|
|
1670
1939
|
def extract_method_override!(method_override)
|
|
1671
1940
|
return {} unless method_override.is_a?(Hash)
|
|
1672
1941
|
|