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
|
@@ -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(
|
|
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
|
-
|
|
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)
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
99
|
+
if peek == '<'
|
|
100
100
|
parse_generic(Named.new(name: name))
|
|
101
|
-
elsif
|
|
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
|
|
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
|
|
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
|
|
137
|
+
while peek && peek != '>'
|
|
138
|
+
before = @i
|
|
138
139
|
args << parse_generic_arg
|
|
139
140
|
skip_space
|
|
140
|
-
|
|
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
|
|
158
|
+
while peek && peek != close
|
|
154
159
|
types << parse_tuple_element
|
|
155
|
-
@i += 1 and skip_space if
|
|
160
|
+
@i += 1 and skip_space if peek == ','
|
|
156
161
|
end
|
|
157
|
-
@i += 1 if
|
|
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
|
|
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
|
|
184
|
+
@i += 2 if @s[@i, 2] == '=>'
|
|
180
185
|
value = parse_union
|
|
181
|
-
@i += 1 if
|
|
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
|
|
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
|
-
|
|
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
|
|
239
|
+
@i += 1 while peek&.match?(/\s/)
|
|
230
240
|
end
|
|
231
241
|
|
|
232
242
|
# @private
|
|
233
243
|
# @return [String?]
|
|
234
|
-
def peek
|
|
235
|
-
@
|
|
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
|