docscribe 1.6.1 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +258 -51
  3. data/exe/docscribe-client +26 -7
  4. data/lib/docscribe/cli/config_builder.rb +69 -8
  5. data/lib/docscribe/cli/config_dump.rb +88 -7
  6. data/lib/docscribe/cli/coverage.rb +5 -5
  7. data/lib/docscribe/cli/formatters/json.rb +74 -29
  8. data/lib/docscribe/cli/formatters/sarif.rb +20 -3
  9. data/lib/docscribe/cli/options.rb +36 -2
  10. data/lib/docscribe/cli/rbs_gen.rb +4 -4
  11. data/lib/docscribe/cli/run.rb +297 -52
  12. data/lib/docscribe/cli/update_types.rb +61 -17
  13. data/lib/docscribe/cli.rb +19 -13
  14. data/lib/docscribe/config/defaults.rb +2 -0
  15. data/lib/docscribe/config/plugin.rb +4 -4
  16. data/lib/docscribe/config/rbs.rb +30 -12
  17. data/lib/docscribe/config/sorbet.rb +3 -1
  18. data/lib/docscribe/config/template.rb +6 -0
  19. data/lib/docscribe/config/utils.rb +15 -0
  20. data/lib/docscribe/config/validation.rb +34 -0
  21. data/lib/docscribe/config.rb +35 -1
  22. data/lib/docscribe/infer/behavior.rb +13 -13
  23. data/lib/docscribe/infer/params.rb +2 -2
  24. data/lib/docscribe/infer/raises.rb +5 -6
  25. data/lib/docscribe/infer/returns.rb +1642 -151
  26. data/lib/docscribe/infer.rb +7 -7
  27. data/lib/docscribe/inline_rewriter/doc_builder.rb +551 -102
  28. data/lib/docscribe/inline_rewriter.rb +367 -98
  29. data/lib/docscribe/plugin/registry.rb +1 -0
  30. data/lib/docscribe/server/base.rb +73 -21
  31. data/lib/docscribe/server/client.rb +20 -11
  32. data/lib/docscribe/server/daemon.rb +209 -23
  33. data/lib/docscribe/server/protocol.rb +4 -4
  34. data/lib/docscribe/types/primitive.rb +160 -0
  35. data/lib/docscribe/types/rbs/provider.rb +5 -2
  36. data/lib/docscribe/types/sorbet/base_provider.rb +33 -1
  37. data/lib/docscribe/types/yard/formatter.rb +35 -6
  38. data/lib/docscribe/types/yard/parser.rb +32 -22
  39. data/lib/docscribe/types/yard/repair.rb +142 -0
  40. data/lib/docscribe/types/yard/validator.rb +131 -0
  41. data/lib/docscribe/validator/generic_compatibility.rb +698 -0
  42. data/lib/docscribe/validator/type_mismatch_validator.rb +287 -0
  43. data/lib/docscribe/version.rb +1 -1
  44. metadata +9 -3
@@ -0,0 +1,160 @@
1
+ # frozen_string_literal: true
2
+
3
+ # NOTE: no top-level `require 'rbs'` here on purpose — the rbs gem is
4
+ # optional (excluded on old rubies via BUNDLE_WITHOUT). It is required
5
+ # lazily in `.load_rbs_core`, which falls back to a hardcoded list when
6
+ # the gem is unavailable.
7
+ #
8
+ # `set` is required eagerly: it is a default gem on all supported rubies
9
+ # and `load_core_primitives` cannot run without it.
10
+ require 'set'
11
+
12
+ module Docscribe
13
+ module Types
14
+ # Dynamic primitive type detection via RBS core + YARD.
15
+ #
16
+ # Replaces hardcoded %w[String Integer ...] lists in
17
+ # Returns and GenericCompatibility with RBS environment inspection.
18
+ module Primitive
19
+ module_function
20
+
21
+ # Whether token matches alias pattern (lowercase after :: or capitalized not in primitives)
22
+ #
23
+ # @note module_function: defines #alias_pattern? (visibility: private)
24
+ # @param [String] token
25
+ # @return [Boolean]
26
+ def alias_pattern?(token)
27
+ base = normalized_base(token)
28
+ return true if base =~ /\A[a-z]/ || base.include?('::')
29
+ return true if base =~ /\A[A-Z]\z/
30
+
31
+ !!(base =~ /\A[A-Z][A-Za-z0-9_]*\z/ && !core_primitives.include?(base))
32
+ end
33
+
34
+ # Whether a type string is an alias (contains alias token inside generic)
35
+ #
36
+ # @note module_function: defines #alias_type? (visibility: private)
37
+ # @param [String] type_str
38
+ # @return [Boolean]
39
+ def alias_type?(type_str)
40
+ # Check if any comma-separated inner is alias
41
+ # For "Array<Elem>" or "MyAlias" etc
42
+ type_str.split(',').any? { |part| alias_token?(part.strip) }
43
+ end
44
+
45
+ # Whether token is an alias/generic placeholder (Elem, U, ParamTag, MyAlias)
46
+ # vs primitive. Inverse of primitive?.
47
+ #
48
+ # @note module_function: defines #alias_token? (visibility: private)
49
+ # @param [String] token single type token
50
+ # @return [Boolean] true if alias
51
+ def alias_token?(token)
52
+ base = normalized_base(token)
53
+ return false if primitive?(base)
54
+ return true if base =~ /\A[a-z]/ || base.include?('::')
55
+ return true if base =~ /\A[A-Z]\z/
56
+
57
+ !!(base =~ /\A[A-Z][A-Za-z0-9_]*\z/ && !core_primitives.include?(base))
58
+ end
59
+
60
+ # Whether token is a primitive type (String, Integer, etc) vs alias (Elem, U, ParamTag).
61
+ #
62
+ # Uses RBS core class declarations + YARD pseudo types (Boolean, void, untyped)
63
+ # to avoid hardcoding the full list. Falls back to a minimal list if RBS unavailable.
64
+ #
65
+ # @note module_function: defines #primitive? (visibility: private)
66
+ # @param [String] token type token (e.g., "String", "Elem", "ParamTag", "untyped")
67
+ # @return [Boolean] true if primitive, false if alias/generic placeholder
68
+ def primitive?(token)
69
+ base = normalized_base(token)
70
+ return false if base.empty?
71
+ return true if %w[untyped void nil].include?(base)
72
+ # YARD pseudo types that are not real RBS classes but considered primitives
73
+ return true if %w[Boolean void untyped nil].include?(base)
74
+
75
+ core_primitives.include?(base)
76
+ end
77
+
78
+ # @note module_function: defines #normalized_base (visibility: private)
79
+ # @param [String] token
80
+ # @return [String]
81
+ def normalized_base(token)
82
+ token.split('<').first.split('[').first.strip.delete_suffix('?').strip
83
+ end
84
+
85
+ # All core primitive class/module names from RBS environment (String, Array, etc)
86
+ # plus YARD primitives. Computed once and cached.
87
+ #
88
+ # @note module_function: defines #core_primitives (visibility: private)
89
+ # @return [Array<String>] primitive names
90
+ def core_primitives
91
+ @core_primitives ||= load_core_primitives
92
+ end
93
+
94
+ # Load core primitives from RBS environment. Falls back to minimal hardcoded list
95
+ # if RBS not available (e.g., in test env without rbs gem).
96
+ #
97
+ # @note module_function: defines #load_core_primitives (visibility: private)
98
+ # @return [Array<String>]
99
+ def load_core_primitives
100
+ primitives = Set.new
101
+ load_yard_primitives(primitives)
102
+ load_rbs_core(primitives)
103
+ merge_primitives(primitives)
104
+ primitives.to_a
105
+ end
106
+
107
+ # @note module_function: defines #load_yard_primitives (visibility: private)
108
+ # @param [Set<String>] primitives
109
+ # @return [Set<String>]
110
+ def load_yard_primitives(primitives)
111
+ primitives.merge(%w[Boolean void untyped nil true false])
112
+ end
113
+
114
+ # @note module_function: defines #load_rbs_core (visibility: private)
115
+ # @param [Set<String>] primitives
116
+ # @raise [LoadError]
117
+ # @raise [StandardError]
118
+ # @return [Set<String>]
119
+ # @return [Set<String>] if LoadError, StandardError
120
+ def load_rbs_core(primitives)
121
+ require 'rbs'
122
+ loader = RBS::EnvironmentLoader.new
123
+ env = RBS::Environment.new
124
+ loader.load(env: env)
125
+ populate_class_decls(env, primitives)
126
+ populate_interface_decls(env, primitives)
127
+ rescue LoadError, StandardError
128
+ primitives.merge(%w[String Integer Float Numeric Symbol Array Hash Range Regexp Proc Method NilClass TrueClass FalseClass BasicObject Kernel Object Class Module IO File Dir Time Date Enumerator
129
+ Set Enumerable])
130
+ end
131
+
132
+ # @note module_function: defines #populate_class_decls (visibility: private)
133
+ # @param [RBS::Environment] env
134
+ # @param [Set<String>] primitives
135
+ # @return [void]
136
+ def populate_class_decls(env, primitives)
137
+ return unless env.respond_to?(:class_decls)
138
+
139
+ env.class_decls.each_key { |k| primitives.merge([k.to_s.split('::').last, k.to_s]) }
140
+ end
141
+
142
+ # @note module_function: defines #populate_interface_decls (visibility: private)
143
+ # @param [RBS::Environment] env
144
+ # @param [Set<String>] primitives
145
+ # @return [void]
146
+ def populate_interface_decls(env, primitives)
147
+ return unless env.respond_to?(:interface_decls)
148
+
149
+ env.interface_decls.each_key { |k| primitives << k.to_s.split('::').last }
150
+ end
151
+
152
+ # @note module_function: defines #merge_primitives (visibility: private)
153
+ # @param [Set<String>] primitives
154
+ # @return [Set<String>]
155
+ def merge_primitives(primitives)
156
+ primitives.merge(%w[String Integer Float Numeric Symbol Array Hash Range Regexp Proc Method NilClass TrueClass FalseClass BasicObject Kernel Object])
157
+ end
158
+ end
159
+ end
160
+ end
@@ -21,13 +21,16 @@ module Docscribe
21
21
  # @param [Array<String>] collection_dirs RBS collection directories
22
22
  # @param [Boolean] collapse_generics whether generic container types
23
23
  # @param [Boolean] collapse_object_generics collapse Object generics flag
24
+ # @param [String] config_root directory holding `rbs_collection.lock.yaml`
24
25
  # @return [void]
25
- def initialize(sig_dirs:, collection_dirs: [], collapse_generics: false, collapse_object_generics: false)
26
+ def initialize(sig_dirs:, collection_dirs: [], collapse_generics: false, collapse_object_generics: false,
27
+ config_root: Dir.pwd)
26
28
  require 'rbs'
27
29
  @sig_dirs = Array(sig_dirs).map(&:to_s)
28
30
  @collection_dirs = Array(collection_dirs).map(&:to_s)
29
31
  @collapse_generics = !!collapse_generics
30
32
  @collapse_object_generics = !!collapse_object_generics
33
+ @config_root = config_root
31
34
  @env = nil
32
35
  @builder = nil
33
36
  @warned = false
@@ -223,7 +226,7 @@ module Docscribe
223
226
  # @return [void]
224
227
  # @return [nil] if StandardError
225
228
  def load_stdlib_libraries!(loader)
226
- lock_path = File.join(Dir.pwd, 'rbs_collection.lock.yaml')
229
+ lock_path = File.join(@config_root, 'rbs_collection.lock.yaml')
227
230
  return unless File.exist?(lock_path)
228
231
 
229
232
  lock = YAML.safe_load_file(lock_path) # steep:ignore
@@ -59,7 +59,7 @@ module Docscribe
59
59
  return unless defined?(RubyVM::AbstractSyntaxTree)
60
60
 
61
61
  parser = ::RBS::Prototype::RBI.new
62
- parser.parse(source)
62
+ parse(parser, source)
63
63
  index_decls(parser.decls)
64
64
  rescue LoadError
65
65
  nil
@@ -68,6 +68,38 @@ module Docscribe
68
68
  nil
69
69
  end
70
70
 
71
+ # Parse the source with the RBS RBI prototype, suppressing the parser's
72
+ # "Unexpected type_node" STDERR noise unless DOCSCRIBE_RBS_DEBUG=1.
73
+ #
74
+ # @private
75
+ # @param [RBS::Prototype::RBI] parser RBI parser instance
76
+ # @param [String] source source text to parse
77
+ # @return [void]
78
+ def parse(parser, source)
79
+ if ENV['DOCSCRIBE_RBS_DEBUG'] == '1'
80
+ parser.parse(source)
81
+ else
82
+ suppress_rbs_noise { parser.parse(source) }
83
+ end
84
+ end
85
+
86
+ # Run the block with STDERR discarded. RBS's RBI prototype prints
87
+ # "Unexpected type_node" directly to STDERR for constructs it doesn't
88
+ # model (e.g. Herb-typed RBIs); the fallback to `Any` is already handled
89
+ # by the parser, so the noise is safe to drop. `IO#reopen` needs a real
90
+ # IO or path, so redirect to File::NULL rather than a StringIO.
91
+ #
92
+ # @private
93
+ # @return [T] the block's return value
94
+ def suppress_rbs_noise
95
+ original_stderr = $stderr.dup
96
+ $stderr.reopen(File::NULL, 'w')
97
+ yield
98
+ ensure
99
+ $stderr.reopen(original_stderr)
100
+ original_stderr.close
101
+ end
102
+
71
103
  # Index parsed declarations into the provider lookup table.
72
104
  #
73
105
  # @private
@@ -10,24 +10,53 @@ module Docscribe
10
10
  class << self
11
11
  # @param [Docscribe::Types::Yard::node?] node
12
12
  # @return [String]
13
- def to_rbs(node) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
13
+ def to_rbs(node)
14
14
  return 'untyped' if node.nil?
15
15
 
16
+ rbs_for_node(node) || 'untyped'
17
+ end
18
+
19
+ private
20
+
21
+ # @private
22
+ # @param [Docscribe::Types::Yard::node] node
23
+ # @return [String, nil]
24
+ def rbs_for_node(node)
25
+ simple_type(node) || composite_type(node) || collection_type(node)
26
+ end
27
+
28
+ # @private
29
+ # @param [Docscribe::Types::Yard::node] node
30
+ # @return [String, nil]
31
+ def simple_type(node)
16
32
  case node
17
33
  when Named then format_named(node)
18
- when Generic then format_generic(node)
34
+ when Literal then format_literal(node)
35
+ end
36
+ end
37
+
38
+ # @private
39
+ # @param [Docscribe::Types::Yard::node] node
40
+ # @return [String, nil]
41
+ def composite_type(node)
42
+ case node
19
43
  when Union then format_union(node)
20
44
  when Intersection then format_intersection(node)
21
45
  when Optional then format_optional(node)
46
+ end
47
+ end
48
+
49
+ # @private
50
+ # @param [Docscribe::Types::Yard::node] node
51
+ # @return [String, nil]
52
+ def collection_type(node)
53
+ case node
54
+ when Generic then format_generic(node)
22
55
  when Tuple then format_tuple(node)
23
56
  when HashMap then format_hash_map(node)
24
- when Literal then format_literal(node)
25
- else 'untyped'
26
57
  end
27
58
  end
28
59
 
29
- private
30
-
31
60
  # @private
32
61
  # @param [Docscribe::Types::Yard::Named] node
33
62
  # @return [String]
@@ -40,7 +40,7 @@ module Docscribe
40
40
  def parse_union
41
41
  types = [parse_intersection]
42
42
  skip_space
43
- while @i < @s.length && @s[@i] == ','
43
+ while peek == ','
44
44
  @i += 1
45
45
  skip_space
46
46
  types << parse_intersection
@@ -54,7 +54,7 @@ module Docscribe
54
54
  def parse_intersection
55
55
  types = [parse_optional]
56
56
  skip_space
57
- while @i < @s.length && @s[@i] == '&'
57
+ while peek == '&'
58
58
  @i += 1
59
59
  skip_space
60
60
  types << parse_optional
@@ -68,7 +68,7 @@ module Docscribe
68
68
  def parse_optional
69
69
  type = parse_primary
70
70
  skip_space
71
- if @i < @s.length && @s[@i] == '?'
71
+ if peek == '?'
72
72
  @i += 1
73
73
  Optional.new(type: type)
74
74
  else
@@ -81,7 +81,7 @@ module Docscribe
81
81
  def parse_primary
82
82
  skip_space
83
83
  case peek
84
- when '(' then parse_tuple
84
+ when '(', '[' then parse_tuple
85
85
  when '{' then parse_hash_map
86
86
  when '#' then parse_duck_type
87
87
  else
@@ -96,9 +96,9 @@ module Docscribe
96
96
  return Literal.new(value: name) if literal?(name)
97
97
 
98
98
  skip_space
99
- if @i < @s.length && @s[@i] == '<'
99
+ if peek == '<'
100
100
  parse_generic(Named.new(name: name))
101
- elsif @i < @s.length && @s[@i] == '{'
101
+ elsif peek == '{'
102
102
  parse_named_hash_map
103
103
  else
104
104
  Named.new(name: name)
@@ -111,7 +111,7 @@ module Docscribe
111
111
  def parse_generic(base)
112
112
  @i += 1
113
113
  args = parse_generic_args
114
- @i += 1 if @i < @s.length && @s[@i] == '>'
114
+ @i += 1 if peek == '>'
115
115
  Generic.new(base: base.name, args: args)
116
116
  end
117
117
 
@@ -120,7 +120,7 @@ module Docscribe
120
120
  def parse_generic_arg
121
121
  types = [parse_intersection]
122
122
  skip_space
123
- while @i < @s.length && @s[@i] == '|'
123
+ while peek == '|'
124
124
  @i += 1
125
125
  skip_space
126
126
  types << parse_intersection
@@ -131,13 +131,17 @@ module Docscribe
131
131
 
132
132
  # @private
133
133
  # @return [Array<Docscribe::Types::Yard::node>]
134
- def parse_generic_args
134
+ def parse_generic_args # rubocop:disable Metrics/MethodLength
135
135
  args = [] #: Array[untyped]
136
136
  skip_space
137
- while @i < @s.length && @s[@i] != '>'
137
+ while peek && peek != '>'
138
+ before = @i
138
139
  args << parse_generic_arg
139
140
  skip_space
140
- next unless @i < @s.length && @s[@i] == ','
141
+ # A branch that consumed nothing would otherwise loop forever.
142
+ break if @i == before
143
+
144
+ next unless peek == ','
141
145
 
142
146
  @i += 1
143
147
  skip_space
@@ -148,13 +152,14 @@ module Docscribe
148
152
  # @private
149
153
  # @return [Docscribe::Types::Yard::Tuple]
150
154
  def parse_tuple
155
+ close = peek == '[' ? ']' : ')'
151
156
  @i += 1
152
157
  types = [] #: Array[untyped]
153
- while @i < @s.length && @s[@i] != ')'
158
+ while peek && peek != close
154
159
  types << parse_tuple_element
155
- @i += 1 and skip_space if @s[@i] == ','
160
+ @i += 1 and skip_space if peek == ','
156
161
  end
157
- @i += 1 if @s[@i] == ')'
162
+ @i += 1 if peek == close
158
163
  Tuple.new(types: types)
159
164
  end
160
165
 
@@ -163,7 +168,7 @@ module Docscribe
163
168
  def parse_tuple_element
164
169
  type = parse_intersection
165
170
  skip_space
166
- if @i < @s.length && @s[@i] == '?'
171
+ if peek == '?'
167
172
  @i += 1
168
173
  Optional.new(type: type)
169
174
  else
@@ -176,9 +181,9 @@ module Docscribe
176
181
  def parse_hash_map
177
182
  @i += 1
178
183
  key = parse_union
179
- @i += 2 if @s[@i..(@i + 1)] == '=>'
184
+ @i += 2 if @s[@i, 2] == '=>'
180
185
  value = parse_union
181
- @i += 1 if @s[@i] == '}'
186
+ @i += 1 if peek == '}'
182
187
  HashMap.new(key_type: key, value_type: value)
183
188
  end
184
189
 
@@ -192,7 +197,7 @@ module Docscribe
192
197
  # @return [Docscribe::Types::Yard::Duck]
193
198
  def parse_duck_type
194
199
  methods = [] #: Array[String]
195
- while @i < @s.length && @s[@i] == '#'
200
+ while peek == '#'
196
201
  @i += 1
197
202
  name = scan_name
198
203
  methods << name
@@ -205,7 +210,12 @@ module Docscribe
205
210
  # @return [String]
206
211
  def scan_name
207
212
  start = @i
208
- @i += 1 while @i < @s.length && name_char?(@s[@i])
213
+ loop do
214
+ c = peek
215
+ break unless c && name_char?(c)
216
+
217
+ @i += 1
218
+ end
209
219
  @s[start...@i]
210
220
  end
211
221
 
@@ -226,13 +236,13 @@ module Docscribe
226
236
  # @private
227
237
  # @return [void]
228
238
  def skip_space
229
- @i += 1 while @i < @s.length && @s[@i].match?(/\s/)
239
+ @i += 1 while peek&.match?(/\s/)
230
240
  end
231
241
 
232
242
  # @private
233
243
  # @return [String?]
234
- def peek
235
- @i < @s.length ? @s[@i] : nil
244
+ def peek #: String?
245
+ @s[@i]
236
246
  end
237
247
  end
238
248
  end
@@ -0,0 +1,142 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'set'
4
+ require_relative 'validator'
5
+
6
+ module Docscribe
7
+ module Types
8
+ module Yard
9
+ # Repairs broken YARD type strings back to a valid form.
10
+ #
11
+ # The common failure is a stray space inside a constant name, e.g.
12
+ # `Sym bol` or `Array<Str ing>`. Writers of `@param` tags split long
13
+ # names by accident; the parser then silently truncates at the space
14
+ # (`Sym bol` parses as `Sym`), so the emitted type is both wrong and
15
+ # unvalidated. Squeezing whitespace restores `Symbol`.
16
+ #
17
+ # Repair only claims a fix when the squeezed result is a type we
18
+ # actually know (a core primitive, or a generic built from known
19
+ # primitives). Otherwise it declines, so an unknown identifier is
20
+ # never silently rewritten into a guess.
21
+ module Repair
22
+ module_function
23
+
24
+ # Recursively repair a YARD type string.
25
+ #
26
+ # @note module_function: defines #repair (visibility: public)
27
+ # @param [String, nil] type_str broken type string
28
+ # @return [String, nil] repaired type, or nil when no safe repair exists
29
+ def repair(type_str)
30
+ return nil if type_str.nil?
31
+
32
+ stripped = type_str.strip
33
+ return stripped if Validator.valid?(stripped) && !stripped.match?(/\s/)
34
+ return nil if stripped.empty?
35
+
36
+ known_repair(stripped.gsub(/\s+/, ''))
37
+ end
38
+
39
+ # Repair a squeezed type only when every name in it is known.
40
+ #
41
+ # @note module_function: defines #known_repair (visibility: private)
42
+ # @param [String] squeezed type with whitespace removed
43
+ # @return [String, nil]
44
+ def known_repair(squeezed) # rubocop:disable Metrics/CyclomaticComplexity
45
+ return nil unless Validator.valid?(squeezed)
46
+ return squeezed if names_known?([squeezed])
47
+
48
+ parts = split_generic(squeezed)
49
+ return nil unless parts
50
+
51
+ base, args = parts
52
+ return nil unless names_known?([base])
53
+
54
+ inner = args.map { |arg| repair_arg(arg) }
55
+ return nil if inner.any?(&:nil?)
56
+
57
+ "#{base}<#{inner.join(',')}>"
58
+ end
59
+
60
+ # Repair one generic argument, recursing into nested generics.
61
+ #
62
+ # @note module_function: defines #repair_arg (visibility: private)
63
+ # @param [String] arg squeezed argument
64
+ # @return [String, nil]
65
+ def repair_arg(arg)
66
+ return arg if names_known?([arg])
67
+
68
+ nested = split_generic(arg)
69
+ return nil unless nested
70
+
71
+ base, args = nested
72
+ return nil unless names_known?([base])
73
+
74
+ inner = args.map { |a| repair_arg(a) }
75
+ return nil if inner.any?(&:nil?)
76
+
77
+ "#{base}<#{inner.join(',')}>"
78
+ end
79
+
80
+ # Split `Base<A, B>` into its base and arguments.
81
+ #
82
+ # @note module_function: defines #split_generic (visibility: private)
83
+ # @param [String] squeezed type string
84
+ # @return [(String, Array<String>), nil] base and args, nil when malformed
85
+ def split_generic(squeezed)
86
+ open_idx = squeezed.index('<')
87
+ return nil unless open_idx && squeezed.end_with?('>')
88
+
89
+ base = squeezed[0...open_idx]
90
+ inner = squeezed[(open_idx + 1)..-2]
91
+ return nil if base.empty? || inner.nil? || inner.empty?
92
+
93
+ [base, split_args(inner)]
94
+ end
95
+
96
+ # Split generic arguments on top-level commas only.
97
+ #
98
+ # @note module_function: defines #split_args (visibility: private)
99
+ # @param [String] inner generic body
100
+ # @return [Array<String>]
101
+ def split_args(inner) # rubocop:disable Metrics/MethodLength
102
+ args = [] #: Array[String]
103
+ depth = 0
104
+ current = +''
105
+
106
+ inner.each_char do |ch|
107
+ depth += 1 if ch == '<'
108
+ depth -= 1 if ch == '>'
109
+ if ch == ',' && depth.zero?
110
+ args << current
111
+ current = +''
112
+ else
113
+ current << ch
114
+ end
115
+ end
116
+ args << current
117
+ args
118
+ end
119
+
120
+ # Whether a name is a known YARD type.
121
+ #
122
+ # @note module_function: defines #names_known? (visibility: private)
123
+ # @param [Array<String>] names
124
+ # @return [Boolean]
125
+ def names_known?(names)
126
+ names.all? { |name| known_names.include?(name.sub(/\A::/, '')) }
127
+ end
128
+
129
+ # Bare names of core primitives, without the leading `::`.
130
+ #
131
+ # @note module_function: defines #known_names (visibility: private)
132
+ # @return [Set<String>]
133
+ def known_names
134
+ @known_names ||= begin
135
+ require_relative '../primitive'
136
+ Docscribe::Types::Primitive.core_primitives.to_set { |p| p.sub(/\A::/, '') }
137
+ end
138
+ end
139
+ end
140
+ end
141
+ end
142
+ end