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.
@@ -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
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Docscribe
4
- VERSION = '1.6.2'
4
+ VERSION = '1.7.0'
5
5
  end
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.6.2
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.6.2. Your future self (and your team) thank you.
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.21
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.