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,131 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative 'parser'
4
+
5
+ module Docscribe
6
+ module Types
7
+ module Yard
8
+ # Validates YARD type strings for syntax errors.
9
+ #
10
+ # This validator is intentionally lightweight and does not perform
11
+ # semantic type-existence checks (e.g. `Symbol2l` vs `Symbol`).
12
+ # Semantic checks are handled by `Docscribe::Validator::TypeMismatchValidator`
13
+ # which compares a YARD tag against the inferred / RBS type.
14
+ module Validator
15
+ module_function
16
+
17
+ # Check if a YARD type string is syntactically valid.
18
+ #
19
+ # Criteria:
20
+ # - non-empty after strip
21
+ # - brackets are balanced (`<>`, `()`, `{}`, `[]`)
22
+ # - no `,,`, `<>`, `,]` artefacts
23
+ # - `Yard::Parser` consumes the entire string (catches `Sym bol` leftover)
24
+ #
25
+ # @note module_function: defines #valid? (visibility: private)
26
+ # @param [String, nil] type_str the YARD type string to validate (e.g. "String", "Array<String>", "Sym bol")
27
+ # @raise [StandardError]
28
+ # @return [Boolean]
29
+ # @return [Boolean] if StandardError
30
+ def valid?(type_str)
31
+ syntax_valid?(type_str)
32
+ rescue StandardError
33
+ false
34
+ end
35
+
36
+ # Strict syntax validation with balanced brackets and full consumption.
37
+ #
38
+ # @note module_function: defines #syntax_valid? (visibility: private)
39
+ # @param [String, nil] type_str
40
+ # @raise [StandardError]
41
+ # @return [Boolean]
42
+ # @return [Boolean] if StandardError
43
+ def syntax_valid?(type_str)
44
+ return false if blank_type?(type_str)
45
+ return false unless balanced_brackets?(type_str)
46
+ return false if artefact_type?(type_str)
47
+
48
+ fully_consumed?(type_str)
49
+ rescue StandardError
50
+ false
51
+ end
52
+
53
+ # @note module_function: defines #blank_type? (visibility: private)
54
+ # @param [String, nil] type_str
55
+ # @return [Boolean]
56
+ def blank_type?(type_str)
57
+ type_str.nil? || type_str.strip.empty?
58
+ end
59
+
60
+ # @note module_function: defines #artefact_type? (visibility: private)
61
+ # @param [String, nil] type_str
62
+ # @return [Boolean]
63
+ def artefact_type?(type_str)
64
+ return false if type_str.nil?
65
+
66
+ type_str.include?(',,') || type_str.include?('<>') || type_str.include?(',]')
67
+ end
68
+
69
+ # Check balanced brackets for `<>`, `()`, `{}`, `[]`.
70
+ #
71
+ # @note module_function: defines #balanced_brackets? (visibility: private)
72
+ # @param [String, nil] type_str
73
+ # @return [Boolean]
74
+ def balanced_brackets?(type_str)
75
+ return false if type_str.nil?
76
+
77
+ stack = [] #: Array[String]
78
+ pairs = { '>' => '<', ')' => '(', '}' => '{', ']' => '[' }
79
+ opens = pairs.values
80
+
81
+ type_str.each_char do |ch|
82
+ return false unless process_bracket_char?(ch, stack, pairs, opens)
83
+ end
84
+
85
+ stack.empty?
86
+ end
87
+
88
+ # @note module_function: defines #process_bracket_char? (visibility: private)
89
+ # @param [String] char
90
+ # @param [Array<String>] stack
91
+ # @param [Hash<String, String>] pairs
92
+ # @param [Array<String>] opens
93
+ # @return [Boolean]
94
+ def process_bracket_char?(char, stack, pairs, opens)
95
+ if opens.include?(char)
96
+ stack << char
97
+ elsif pairs.key?(char)
98
+ return false if stack.empty? || stack.pop != pairs[char]
99
+ end
100
+ true
101
+ end
102
+
103
+ # Whether `Yard::Parser` consumes the entire string.
104
+ #
105
+ # Catches cases like `Sym bol` where parser would return `Sym` and
106
+ # leave ` bol` unconsumed.
107
+ #
108
+ # @note module_function: defines #fully_consumed? (visibility: private)
109
+ # @param [String, nil] type_str
110
+ # @raise [StandardError]
111
+ # @return [Boolean]
112
+ # @return [Boolean] if StandardError
113
+ def fully_consumed?(type_str)
114
+ return false if type_str.nil?
115
+
116
+ stripped = type_str.strip
117
+ parser = Parser.new(stripped)
118
+ node = parser.parse
119
+ return false unless node
120
+
121
+ idx = parser.instance_variable_get(:@i)
122
+ # `Parser#parse` calls `skip_space` before and after `parse_union`,
123
+ # so `idx` should be at the end if fully consumed.
124
+ idx == stripped.length
125
+ rescue StandardError
126
+ false
127
+ end
128
+ end
129
+ end
130
+ end
131
+ end