docscribe 1.6.2 → 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 +347 -23
- data/lib/docscribe/cli/config_builder.rb +34 -8
- data/lib/docscribe/cli/config_dump.rb +88 -7
- data/lib/docscribe/cli/options.rb +20 -1
- data/lib/docscribe/cli/run.rb +193 -31
- data/lib/docscribe/config/defaults.rb +2 -1
- data/lib/docscribe/config/plugin.rb +4 -4
- data/lib/docscribe/config/rbs.rb +10 -13
- data/lib/docscribe/config/sorbet.rb +3 -1
- data/lib/docscribe/config/template.rb +4 -1
- data/lib/docscribe/config/utils.rb +15 -0
- data/lib/docscribe/config/validation.rb +18 -3
- data/lib/docscribe/config.rb +34 -1
- data/lib/docscribe/infer/returns.rb +46 -16
- data/lib/docscribe/inline_rewriter/doc_builder.rb +69 -3
- data/lib/docscribe/inline_rewriter.rb +104 -1
- data/lib/docscribe/server/base.rb +37 -16
- data/lib/docscribe/server/daemon.rb +10 -1
- data/lib/docscribe/types/rbs/provider.rb +5 -2
- data/lib/docscribe/types/sorbet/base_provider.rb +1 -1
- data/lib/docscribe/types/yard/parser.rb +9 -4
- data/lib/docscribe/types/yard/repair.rb +142 -0
- data/lib/docscribe/version.rb +1 -1
- metadata +4 -3
|
@@ -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
|
data/lib/docscribe/version.rb
CHANGED
metadata
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: docscribe
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 1.
|
|
4
|
+
version: 1.7.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- unurgunite
|
|
@@ -229,6 +229,7 @@ files:
|
|
|
229
229
|
- lib/docscribe/types/sorbet/source_provider.rb
|
|
230
230
|
- lib/docscribe/types/yard/formatter.rb
|
|
231
231
|
- lib/docscribe/types/yard/parser.rb
|
|
232
|
+
- lib/docscribe/types/yard/repair.rb
|
|
232
233
|
- lib/docscribe/types/yard/types.rb
|
|
233
234
|
- lib/docscribe/types/yard/validator.rb
|
|
234
235
|
- lib/docscribe/validator/generic_compatibility.rb
|
|
@@ -243,7 +244,7 @@ metadata:
|
|
|
243
244
|
changelog_uri: https://github.com/unurgunite/docscribe/blob/master/CHANGELOG.md
|
|
244
245
|
rubygems_mfa_required: 'true'
|
|
245
246
|
post_install_message: |
|
|
246
|
-
You installed docscribe 1.
|
|
247
|
+
You installed docscribe 1.7.0. Your future self (and your team) thank you.
|
|
247
248
|
|
|
248
249
|
$ docscribe --help
|
|
249
250
|
|
|
@@ -263,7 +264,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
|
263
264
|
- !ruby/object:Gem::Version
|
|
264
265
|
version: '0'
|
|
265
266
|
requirements: []
|
|
266
|
-
rubygems_version: 4.0.
|
|
267
|
+
rubygems_version: 4.0.23
|
|
267
268
|
specification_version: 4
|
|
268
269
|
summary: Auto-generate inline YARD documentation for Ruby by analyzing code AST. Supports
|
|
269
270
|
RBS and Sorbet type signatures.
|