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
data/exe/docscribe-client
CHANGED
|
@@ -13,7 +13,8 @@ SOCKET_DIR = begin
|
|
|
13
13
|
sock_overhead = "/docscribe-#{'a' * 32}.sock".bytesize
|
|
14
14
|
tmp.bytesize <= 104 - sock_overhead ? tmp : '/tmp'
|
|
15
15
|
end
|
|
16
|
-
ENV_FILES = %w[Gemfile.lock rbs_collection.lock.yaml].freeze
|
|
16
|
+
ENV_FILES = %w[Gemfile.lock rbs_collection.lock.yaml docscribe.yml].freeze
|
|
17
|
+
SIG_RBS_GLOB = 'sig/**/*.rbs'
|
|
17
18
|
|
|
18
19
|
def socket_path(config_path = nil)
|
|
19
20
|
seed = +Dir.pwd
|
|
@@ -27,13 +28,27 @@ def socket_path(config_path = nil)
|
|
|
27
28
|
end
|
|
28
29
|
|
|
29
30
|
def env_hash
|
|
30
|
-
parts = ENV_FILES.map
|
|
31
|
-
|
|
32
|
-
File.exist?(path) ? File.mtime(path).to_f.to_s : '0'
|
|
33
|
-
end
|
|
31
|
+
parts = ENV_FILES.map { |file| env_file_mtime(file) }
|
|
32
|
+
parts.concat(sig_env_parts)
|
|
34
33
|
Digest::MD5.hexdigest(parts.join(':'))
|
|
35
34
|
end
|
|
36
35
|
|
|
36
|
+
def env_file_mtime(file)
|
|
37
|
+
path = File.join(Dir.pwd, file)
|
|
38
|
+
File.exist?(path) ? File.mtime(path).to_f.to_s : '0'
|
|
39
|
+
end
|
|
40
|
+
|
|
41
|
+
def sig_env_parts
|
|
42
|
+
files = sig_files
|
|
43
|
+
mtimes = files.map { |p| File.mtime(p).to_f.to_s }
|
|
44
|
+
mtimes << files.size.to_s
|
|
45
|
+
mtimes
|
|
46
|
+
end
|
|
47
|
+
|
|
48
|
+
def sig_files
|
|
49
|
+
Dir.glob(File.join(Dir.pwd, SIG_RBS_GLOB)).sort
|
|
50
|
+
end
|
|
51
|
+
|
|
37
52
|
def config_hash(config_path)
|
|
38
53
|
resolved = File.expand_path(config_path)
|
|
39
54
|
mtime = File.exist?(resolved) ? File.mtime(resolved).to_f : 0.0
|
|
@@ -141,8 +156,12 @@ when :ping
|
|
|
141
156
|
puts JSON.generate(result || { error: 'Connection failed' })
|
|
142
157
|
when :status
|
|
143
158
|
alive = begin
|
|
144
|
-
File.exist?(sock)
|
|
145
|
-
UNIXSocket.new(sock).close
|
|
159
|
+
if File.exist?(sock)
|
|
160
|
+
UNIXSocket.new(sock).close
|
|
161
|
+
true
|
|
162
|
+
else
|
|
163
|
+
false
|
|
164
|
+
end
|
|
146
165
|
rescue StandardError
|
|
147
166
|
false
|
|
148
167
|
end
|
|
@@ -22,13 +22,14 @@ module Docscribe
|
|
|
22
22
|
# @param [Hash<Symbol, Object>] options parsed CLI options
|
|
23
23
|
# @return [Docscribe::Config] merged effective config
|
|
24
24
|
def build(base, options)
|
|
25
|
-
return base unless needs_override?(options)
|
|
25
|
+
return warn_and_return_base(base, options) unless needs_override?(options)
|
|
26
26
|
|
|
27
27
|
raw = Marshal.load(Marshal.dump(base.raw))
|
|
28
28
|
apply_filter_overrides(raw, options)
|
|
29
|
-
apply_rbs_overrides(raw, options) if rbs_overrides?(options)
|
|
29
|
+
apply_rbs_overrides(raw, options, base) if rbs_overrides?(options)
|
|
30
30
|
apply_sorbet_overrides(raw, options) if sorbet_overrides?(options)
|
|
31
31
|
apply_output_overrides(raw, options)
|
|
32
|
+
apply_validation_overrides(raw, options) if validation_overrides?(options)
|
|
32
33
|
conf = Docscribe::Config.new(config_path: base.config_path, **raw)
|
|
33
34
|
warn_missing_rbs_collection(conf, options)
|
|
34
35
|
conf
|
|
@@ -43,7 +44,21 @@ module Docscribe
|
|
|
43
44
|
filter_overrides?(options) ||
|
|
44
45
|
rbs_overrides?(options) ||
|
|
45
46
|
sorbet_overrides?(options) ||
|
|
46
|
-
output_overrides?(options)
|
|
47
|
+
output_overrides?(options) ||
|
|
48
|
+
validation_overrides?(options)
|
|
49
|
+
end
|
|
50
|
+
|
|
51
|
+
# Warn about a missing collection opt-in and return the base config unchanged.
|
|
52
|
+
#
|
|
53
|
+
# Used when no CLI override is present so the nudge still fires on plain runs.
|
|
54
|
+
#
|
|
55
|
+
# @note module_function: defines #warn_and_return_base (visibility: private)
|
|
56
|
+
# @param [Docscribe::Config] base base config loaded from YAML/defaults
|
|
57
|
+
# @param [Hash<Symbol, Object>] options parsed CLI options
|
|
58
|
+
# @return [Docscribe::Config] base config unchanged
|
|
59
|
+
def warn_and_return_base(base, options)
|
|
60
|
+
warn_missing_rbs_collection(base, options)
|
|
61
|
+
base
|
|
47
62
|
end
|
|
48
63
|
|
|
49
64
|
# Whether any method or file filter CLI options were provided.
|
|
@@ -115,15 +130,16 @@ module Docscribe
|
|
|
115
130
|
# @note module_function: defines #apply_rbs_overrides (visibility: private)
|
|
116
131
|
# @param [Hash<String, Object>] raw raw config hash
|
|
117
132
|
# @param [Hash<Symbol, Object>] options parsed CLI options
|
|
133
|
+
# @param [Docscribe::Config] base base config whose root anchors collection lookup
|
|
118
134
|
# @return [void]
|
|
119
|
-
def apply_rbs_overrides(raw, options)
|
|
135
|
+
def apply_rbs_overrides(raw, options, base)
|
|
120
136
|
raw['rbs'] ||= {}
|
|
121
137
|
raw['rbs']['enabled'] = true
|
|
122
138
|
raw['rbs']['sig_dirs'] = Array(raw['rbs']['sig_dirs']) + options[:sig_dirs] if options[:sig_dirs].any?
|
|
123
139
|
|
|
124
140
|
return unless options[:rbs_collection]
|
|
125
141
|
|
|
126
|
-
apply_rbs_collection(raw)
|
|
142
|
+
apply_rbs_collection(raw, base)
|
|
127
143
|
end
|
|
128
144
|
|
|
129
145
|
# Whether any Sorbet-related CLI options were provided.
|
|
@@ -138,12 +154,16 @@ module Docscribe
|
|
|
138
154
|
|
|
139
155
|
# Resolve and apply the RBS collection path into the raw config hash.
|
|
140
156
|
#
|
|
157
|
+
# The lock file is looked up in the config root so that `-C other/dir/docscribe.yml`
|
|
158
|
+
# finds the collection next to that config rather than under `Dir.pwd`.
|
|
159
|
+
#
|
|
141
160
|
# @note module_function: defines #apply_rbs_collection (visibility: private)
|
|
142
161
|
# @param [Hash<String, Object>] raw raw config hash
|
|
162
|
+
# @param [Docscribe::Config] base base config whose root anchors the lookup
|
|
143
163
|
# @return [void]
|
|
144
|
-
def apply_rbs_collection(raw)
|
|
164
|
+
def apply_rbs_collection(raw, base)
|
|
145
165
|
require 'docscribe/types/rbs/collection_loader'
|
|
146
|
-
collection_path = Docscribe::Types::RBS::CollectionLoader.resolve
|
|
166
|
+
collection_path = Docscribe::Types::RBS::CollectionLoader.resolve(root: base.config_root)
|
|
147
167
|
if collection_path
|
|
148
168
|
raw['rbs']['collection_dirs'] = Array(raw['rbs']['collection_dirs']) + [collection_path]
|
|
149
169
|
else
|
|
@@ -195,8 +215,32 @@ module Docscribe
|
|
|
195
215
|
raw['emit']['include_param_documentation'] = false if options[:no_boilerplate]
|
|
196
216
|
end
|
|
197
217
|
|
|
218
|
+
# Whether any validation-related CLI options were provided.
|
|
219
|
+
#
|
|
220
|
+
# @note module_function: defines #validation_overrides? (visibility: private)
|
|
221
|
+
# @param [Hash<Symbol, Object>] options parsed CLI options
|
|
222
|
+
# @return [Boolean]
|
|
223
|
+
def validation_overrides?(options)
|
|
224
|
+
!options[:validate_types].nil? || !options[:warn_invalid_yard].nil?
|
|
225
|
+
end
|
|
226
|
+
|
|
227
|
+
# Apply validation-related CLI overrides to the raw config.
|
|
228
|
+
#
|
|
229
|
+
# @note module_function: defines #apply_validation_overrides (visibility: private)
|
|
230
|
+
# @param [Hash<String, Object>] raw raw config hash
|
|
231
|
+
# @param [Hash<Symbol, Object>] options parsed CLI options
|
|
232
|
+
# @return [void]
|
|
233
|
+
def apply_validation_overrides(raw, options)
|
|
234
|
+
raw['validate_types'] = options[:validate_types] unless options[:validate_types].nil?
|
|
235
|
+
raw['warn_invalid_yard'] = options[:warn_invalid_yard] unless options[:warn_invalid_yard].nil?
|
|
236
|
+
end
|
|
237
|
+
|
|
198
238
|
# Warn when rbs_collection.lock.yaml exists but --rbs-collection was not passed.
|
|
199
239
|
#
|
|
240
|
+
# Fires on plain runs and on runs with unrelated overrides alike: the check
|
|
241
|
+
# lives outside the `needs_override?` branch. The lock file is looked up in the
|
|
242
|
+
# config root so the nudge appears regardless of the current directory.
|
|
243
|
+
#
|
|
200
244
|
# The warning can be suppressed by setting `rbs.warn_missing_collection: false`
|
|
201
245
|
# in the project's `docscribe.yml`.
|
|
202
246
|
#
|
|
@@ -206,13 +250,30 @@ module Docscribe
|
|
|
206
250
|
# @return [void]
|
|
207
251
|
def warn_missing_rbs_collection(conf, options)
|
|
208
252
|
return if options[:rbs_collection]
|
|
253
|
+
return if conf.raw.dig('rbs', 'collection')
|
|
209
254
|
return unless conf.rbs_warn_missing_collection?
|
|
210
|
-
return unless File.exist?('rbs_collection.lock.yaml')
|
|
255
|
+
return unless File.exist?(File.join(config_root_for_warning(conf), 'rbs_collection.lock.yaml'))
|
|
211
256
|
|
|
212
257
|
warn 'Docscribe: rbs_collection.lock.yaml found but --rbs-collection not set. ' \
|
|
213
258
|
'Pass --rbs-collection or set `rbs.collection: true` in docscribe.yml to enable RBS collection. ' \
|
|
214
259
|
'Set `rbs.warn_missing_collection: false` to suppress this warning.'
|
|
215
260
|
end
|
|
261
|
+
|
|
262
|
+
# Config root for the missing-collection nudge.
|
|
263
|
+
#
|
|
264
|
+
# A warning must never abort a run, so an unresolvable config directory
|
|
265
|
+
# (e.g. a config path pointing at a removed directory) falls back to the
|
|
266
|
+
# working directory.
|
|
267
|
+
#
|
|
268
|
+
# @note module_function: defines #config_root_for_warning (visibility: private)
|
|
269
|
+
# @param [Docscribe::Config] conf effective config
|
|
270
|
+
# @raise [Docscribe::Error] when the config directory is gone (caught here)
|
|
271
|
+
# @return [String]
|
|
272
|
+
def config_root_for_warning(conf)
|
|
273
|
+
conf.config_root
|
|
274
|
+
rescue Docscribe::Error
|
|
275
|
+
File.expand_path(Dir.pwd)
|
|
276
|
+
end
|
|
216
277
|
end
|
|
217
278
|
end
|
|
218
279
|
end
|
|
@@ -1,18 +1,21 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
|
+
require 'json'
|
|
3
4
|
require 'optparse'
|
|
4
5
|
require 'yaml'
|
|
5
6
|
require 'docscribe/config'
|
|
6
7
|
require 'docscribe/cli/config_builder'
|
|
8
|
+
require 'docscribe/cli/options'
|
|
7
9
|
|
|
8
10
|
module Docscribe
|
|
9
11
|
module CLI
|
|
10
|
-
# Print the fully resolved configuration as YAML
|
|
12
|
+
# Print the fully resolved configuration as YAML, JSON or text,
|
|
13
|
+
# optionally limited to the keys that differ from the built-in defaults.
|
|
11
14
|
module ConfigDump
|
|
12
15
|
BANNER = <<~TEXT
|
|
13
16
|
Usage: docscribe config [options]
|
|
14
17
|
|
|
15
|
-
Print the fully resolved configuration
|
|
18
|
+
Print the fully resolved configuration.
|
|
16
19
|
|
|
17
20
|
Options:
|
|
18
21
|
TEXT
|
|
@@ -24,10 +27,9 @@ module Docscribe
|
|
|
24
27
|
opts = parse_options(argv)
|
|
25
28
|
return 0 if opts[:help]
|
|
26
29
|
|
|
27
|
-
conf =
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
puts conf.to_h.to_yaml
|
|
30
|
+
conf = build_config(argv, opts)
|
|
31
|
+
data = opts[:only_changed] ? changed_from_defaults(conf.raw) : conf.raw
|
|
32
|
+
puts render(data, conf, opts)
|
|
31
33
|
0
|
|
32
34
|
end
|
|
33
35
|
|
|
@@ -37,7 +39,7 @@ module Docscribe
|
|
|
37
39
|
# @param [Array<String>] argv
|
|
38
40
|
# @return [Hash<Symbol, Object>]
|
|
39
41
|
def parse_options(argv)
|
|
40
|
-
opts = { config: nil }
|
|
42
|
+
opts = { config: nil, only_changed: false, format: 'yaml' }
|
|
41
43
|
build_parser(opts).parse!(argv)
|
|
42
44
|
opts
|
|
43
45
|
end
|
|
@@ -49,6 +51,8 @@ module Docscribe
|
|
|
49
51
|
OptionParser.new do |o|
|
|
50
52
|
o.banner = BANNER
|
|
51
53
|
o.on('--config PATH', 'Path to config file') { |v| opts[:config] = v }
|
|
54
|
+
o.on('--only-changed', 'Show only keys that differ from defaults') { opts[:only_changed] = true }
|
|
55
|
+
o.on('--format FORMAT', %w[yaml json text], 'Output format: yaml, json, text') { |v| opts[:format] = v }
|
|
52
56
|
o.on('-h', '--help', 'Show help') do
|
|
53
57
|
opts[:help] = true
|
|
54
58
|
puts o
|
|
@@ -56,6 +60,15 @@ module Docscribe
|
|
|
56
60
|
end
|
|
57
61
|
end
|
|
58
62
|
|
|
63
|
+
# @private
|
|
64
|
+
# @param [Array<String>] argv
|
|
65
|
+
# @param [Hash<Symbol, Object>] opts
|
|
66
|
+
# @return [Docscribe::Config]
|
|
67
|
+
def build_config(argv, opts)
|
|
68
|
+
conf = Docscribe::Config.load(opts[:config])
|
|
69
|
+
Docscribe::CLI::ConfigBuilder.build(conf, parse_cli_overrides(argv))
|
|
70
|
+
end
|
|
71
|
+
|
|
59
72
|
# @private
|
|
60
73
|
# @param [Array<String>] argv
|
|
61
74
|
# @return [Hash<Symbol, Object>]
|
|
@@ -64,6 +77,74 @@ module Docscribe
|
|
|
64
77
|
opts.slice(:rbs, :rbs_collection, :sorbet, :sig_dirs, :rbi_dirs, :include, :exclude, :include_file,
|
|
65
78
|
:exclude_file)
|
|
66
79
|
end
|
|
80
|
+
|
|
81
|
+
# Keep only the nested keys whose effective value differs from the
|
|
82
|
+
# built-in default.
|
|
83
|
+
#
|
|
84
|
+
# @private
|
|
85
|
+
# @param [Hash<String, Object>] effective merged config
|
|
86
|
+
# @return [Hash<String, Object>]
|
|
87
|
+
def changed_from_defaults(effective)
|
|
88
|
+
diff_against(Docscribe::Config::DEFAULT, effective)
|
|
89
|
+
end
|
|
90
|
+
|
|
91
|
+
# Recursive comparison; a single overridden leaf keeps its parent
|
|
92
|
+
# sections while untouched siblings are dropped.
|
|
93
|
+
#
|
|
94
|
+
# @private
|
|
95
|
+
# @param [Hash<String, Object>] defaults
|
|
96
|
+
# @param [Hash<String, Object>] effective
|
|
97
|
+
# @return [Hash<String, Object>]
|
|
98
|
+
def diff_against(defaults, effective)
|
|
99
|
+
effective.each_with_object({}) do |(key, value), acc|
|
|
100
|
+
default = defaults[key]
|
|
101
|
+
if value.is_a?(Hash) && default.is_a?(Hash)
|
|
102
|
+
nested = diff_against(default, value)
|
|
103
|
+
acc[key] = nested unless nested.empty?
|
|
104
|
+
elsif value != default
|
|
105
|
+
acc[key] = value
|
|
106
|
+
end
|
|
107
|
+
end
|
|
108
|
+
end
|
|
109
|
+
|
|
110
|
+
# @private
|
|
111
|
+
# @param [Hash<String, Object>] data
|
|
112
|
+
# @param [Docscribe::Config] conf
|
|
113
|
+
# @param [Hash<Symbol, Object>] opts
|
|
114
|
+
# @return [String]
|
|
115
|
+
def render(data, conf, opts)
|
|
116
|
+
case opts[:format]
|
|
117
|
+
when 'json' then JSON.pretty_generate(data)
|
|
118
|
+
when 'text' then render_text(data, conf)
|
|
119
|
+
else data.to_yaml
|
|
120
|
+
end
|
|
121
|
+
end
|
|
122
|
+
|
|
123
|
+
# @private
|
|
124
|
+
# @param [Hash<String, Object>] data
|
|
125
|
+
# @param [Docscribe::Config] _conf unused, kept for format symmetry
|
|
126
|
+
# @return [String]
|
|
127
|
+
def render_text(data, _conf)
|
|
128
|
+
flat = flatten(data, '')
|
|
129
|
+
return "(no changes from defaults)\n" if flat.empty?
|
|
130
|
+
|
|
131
|
+
flat.map { |key, value| "#{key}=#{value}" }.join("\n")
|
|
132
|
+
end
|
|
133
|
+
|
|
134
|
+
# @private
|
|
135
|
+
# @param [Hash<String, Object>] data
|
|
136
|
+
# @param [String] prefix dotted path of the current level
|
|
137
|
+
# @return [Hash<String, Object>]
|
|
138
|
+
def flatten(data, prefix)
|
|
139
|
+
data.each_with_object({}) do |(key, value), acc|
|
|
140
|
+
path = prefix.empty? ? key.to_s : "#{prefix}.#{key}"
|
|
141
|
+
if value.is_a?(Hash)
|
|
142
|
+
acc.merge!(flatten(value, path))
|
|
143
|
+
else
|
|
144
|
+
acc[path] = value
|
|
145
|
+
end
|
|
146
|
+
end
|
|
147
|
+
end
|
|
67
148
|
end
|
|
68
149
|
end
|
|
69
150
|
end
|
|
@@ -172,7 +172,7 @@ module Docscribe
|
|
|
172
172
|
end
|
|
173
173
|
|
|
174
174
|
# @private
|
|
175
|
-
# @param [
|
|
175
|
+
# @param [Parser::AST::Node] node
|
|
176
176
|
# @param [Docscribe::CLI::Coverage::CoverageStats] stats
|
|
177
177
|
# @param [String] src
|
|
178
178
|
# @return [void]
|
|
@@ -185,7 +185,7 @@ module Docscribe
|
|
|
185
185
|
end
|
|
186
186
|
|
|
187
187
|
# @private
|
|
188
|
-
# @param [
|
|
188
|
+
# @param [Parser::AST::Node] node
|
|
189
189
|
# @param [Docscribe::CLI::Coverage::CoverageStats] stats
|
|
190
190
|
# @param [String] src
|
|
191
191
|
# @return [void]
|
|
@@ -202,7 +202,7 @@ module Docscribe
|
|
|
202
202
|
end
|
|
203
203
|
|
|
204
204
|
# @private
|
|
205
|
-
# @param [
|
|
205
|
+
# @param [Parser::AST::Node] node
|
|
206
206
|
# @param [Docscribe::CLI::Coverage::CoverageStats] stats
|
|
207
207
|
# @param [String] doc_comment
|
|
208
208
|
# @return [void]
|
|
@@ -218,7 +218,7 @@ module Docscribe
|
|
|
218
218
|
end
|
|
219
219
|
|
|
220
220
|
# @private
|
|
221
|
-
# @param [
|
|
221
|
+
# @param [Parser::AST::Node] node
|
|
222
222
|
# @param [Docscribe::CLI::Coverage::CoverageStats] stats
|
|
223
223
|
# @return [void]
|
|
224
224
|
def count_method_params(node, stats)
|
|
@@ -226,7 +226,7 @@ module Docscribe
|
|
|
226
226
|
end
|
|
227
227
|
|
|
228
228
|
# @private
|
|
229
|
-
# @param [
|
|
229
|
+
# @param [Parser::AST::Node] node
|
|
230
230
|
# @return [Integer]
|
|
231
231
|
def count_params(node)
|
|
232
232
|
args_node = node.children[2] || node.children[1]
|
|
@@ -20,7 +20,8 @@ module Docscribe
|
|
|
20
20
|
insert_full_doc_block: 'convention',
|
|
21
21
|
unsorted_tags: 'convention',
|
|
22
22
|
updated_param: 'warning',
|
|
23
|
-
updated_return: 'warning'
|
|
23
|
+
updated_return: 'warning',
|
|
24
|
+
invalid_type: 'warning'
|
|
24
25
|
}.freeze
|
|
25
26
|
|
|
26
27
|
COP_NAME_MAP = {
|
|
@@ -32,7 +33,8 @@ module Docscribe
|
|
|
32
33
|
insert_full_doc_block: 'Docscribe/MissingDocBlock',
|
|
33
34
|
unsorted_tags: 'Docscribe/UnsortedTags',
|
|
34
35
|
updated_param: 'Docscribe/UpdatedParam',
|
|
35
|
-
updated_return: 'Docscribe/UpdatedReturn'
|
|
36
|
+
updated_return: 'Docscribe/UpdatedReturn',
|
|
37
|
+
invalid_type: 'Docscribe/InvalidType'
|
|
36
38
|
}.freeze
|
|
37
39
|
|
|
38
40
|
# Output JSON check summary.
|
|
@@ -60,7 +62,7 @@ module Docscribe
|
|
|
60
62
|
# @private
|
|
61
63
|
# @param [Docscribe::CLI::Formatters::state] state formatter state hash
|
|
62
64
|
# @param [Docscribe::CLI::Formatters::opts] _options runtime options hash
|
|
63
|
-
# @return [
|
|
65
|
+
# @return [Docscribe::CLI::Formatters::Json::json_document]
|
|
64
66
|
def build_document(state, _options)
|
|
65
67
|
document_hash(build_files(state), state)
|
|
66
68
|
end
|
|
@@ -68,9 +70,9 @@ module Docscribe
|
|
|
68
70
|
# Build document hash structure.
|
|
69
71
|
#
|
|
70
72
|
# @private
|
|
71
|
-
# @param [Array<
|
|
73
|
+
# @param [Array<Docscribe::CLI::Formatters::Json::json_file>] files files offenses array
|
|
72
74
|
# @param [Docscribe::CLI::Formatters::state] state formatter state hash
|
|
73
|
-
# @return [
|
|
75
|
+
# @return [Docscribe::CLI::Formatters::Json::json_document]
|
|
74
76
|
def document_hash(files, state)
|
|
75
77
|
{
|
|
76
78
|
metadata: metadata_hash,
|
|
@@ -82,7 +84,7 @@ module Docscribe
|
|
|
82
84
|
# Build tool metadata hash.
|
|
83
85
|
#
|
|
84
86
|
# @private
|
|
85
|
-
# @return [
|
|
87
|
+
# @return [Docscribe::CLI::Formatters::Json::json_metadata]
|
|
86
88
|
def metadata_hash
|
|
87
89
|
{
|
|
88
90
|
docscribe_version: Docscribe::VERSION,
|
|
@@ -93,9 +95,9 @@ module Docscribe
|
|
|
93
95
|
# Build summary statistics hash.
|
|
94
96
|
#
|
|
95
97
|
# @private
|
|
96
|
-
# @param [Array<
|
|
98
|
+
# @param [Array<Docscribe::CLI::Formatters::Json::json_file>] files files offenses array
|
|
97
99
|
# @param [Docscribe::CLI::Formatters::state] state formatter state hash
|
|
98
|
-
# @return [
|
|
100
|
+
# @return [Docscribe::CLI::Formatters::Json::json_summary]
|
|
99
101
|
def summary_hash(files, state)
|
|
100
102
|
{
|
|
101
103
|
offense_count: files.sum { |f| f[:offenses].size },
|
|
@@ -109,7 +111,7 @@ module Docscribe
|
|
|
109
111
|
#
|
|
110
112
|
# @private
|
|
111
113
|
# @param [Docscribe::CLI::Formatters::state] state formatter state hash
|
|
112
|
-
# @return [Array<
|
|
114
|
+
# @return [Array<Docscribe::CLI::Formatters::Json::json_file>]
|
|
113
115
|
def build_files(state)
|
|
114
116
|
files = [] #: Array[Hash[untyped, untyped]]
|
|
115
117
|
|
|
@@ -124,15 +126,16 @@ module Docscribe
|
|
|
124
126
|
#
|
|
125
127
|
# @private
|
|
126
128
|
# @param [Docscribe::CLI::Formatters::state] state formatter state hash
|
|
127
|
-
# @param [Array<
|
|
129
|
+
# @param [Array<Docscribe::CLI::Formatters::Json::json_file>] files files offenses array
|
|
128
130
|
# @return [void]
|
|
129
131
|
def append_check_files(state, files)
|
|
130
132
|
state[:fail_paths].each do |path|
|
|
131
|
-
files
|
|
133
|
+
merge_or_append(files, path, build_offenses(state[:fail_changes][path] || []))
|
|
132
134
|
end
|
|
133
135
|
|
|
134
136
|
state[:type_mismatch_paths].each do |path|
|
|
135
|
-
|
|
137
|
+
changes = state[:type_mismatch_changes][path] || []
|
|
138
|
+
merge_or_append(files, path, build_offenses(changes, severity: 'warning'))
|
|
136
139
|
end
|
|
137
140
|
end
|
|
138
141
|
|
|
@@ -140,7 +143,7 @@ module Docscribe
|
|
|
140
143
|
#
|
|
141
144
|
# @private
|
|
142
145
|
# @param [Docscribe::CLI::Formatters::state] state formatter state hash
|
|
143
|
-
# @param [Array<
|
|
146
|
+
# @param [Array<Docscribe::CLI::Formatters::Json::json_file>] files files offenses array
|
|
144
147
|
# @return [void]
|
|
145
148
|
def append_corrected_files(state, files)
|
|
146
149
|
state[:corrected_paths].each do |path|
|
|
@@ -152,7 +155,7 @@ module Docscribe
|
|
|
152
155
|
#
|
|
153
156
|
# @private
|
|
154
157
|
# @param [Docscribe::CLI::Formatters::state] state formatter state hash
|
|
155
|
-
# @param [Array<
|
|
158
|
+
# @param [Array<Docscribe::CLI::Formatters::Json::json_file>] files files offenses array
|
|
156
159
|
# @return [void]
|
|
157
160
|
def append_error_files(state, files)
|
|
158
161
|
state[:error_paths].each do |path|
|
|
@@ -163,12 +166,12 @@ module Docscribe
|
|
|
163
166
|
# Merge or append file offenses.
|
|
164
167
|
#
|
|
165
168
|
# @private
|
|
166
|
-
# @param [Array<
|
|
169
|
+
# @param [Array<Docscribe::CLI::Formatters::Json::json_file>] files files offenses array
|
|
167
170
|
# @param [String] path file path string
|
|
168
|
-
# @param [Array<
|
|
171
|
+
# @param [Array<Docscribe::CLI::Formatters::Json::json_offense>] offenses offense objects array
|
|
169
172
|
# @return [void]
|
|
170
173
|
def merge_or_append(files, path, offenses)
|
|
171
|
-
existing = files.find { |f| f[:path] == path }
|
|
174
|
+
existing = files.find { |f| normalize_path(f[:path]) == normalize_path(path) }
|
|
172
175
|
|
|
173
176
|
if existing
|
|
174
177
|
existing[:offenses].concat(offenses)
|
|
@@ -177,15 +180,18 @@ module Docscribe
|
|
|
177
180
|
end
|
|
178
181
|
end
|
|
179
182
|
|
|
180
|
-
#
|
|
183
|
+
# Normalize a path for dedup comparison, resolving symlinks
|
|
184
|
+
# (e.g. /tmp vs /private/tmp on macOS).
|
|
181
185
|
#
|
|
182
186
|
# @private
|
|
183
187
|
# @param [String] path file path string
|
|
184
|
-
# @
|
|
185
|
-
# @
|
|
186
|
-
# @return [
|
|
187
|
-
def
|
|
188
|
-
|
|
188
|
+
# @raise [SystemCallError]
|
|
189
|
+
# @raise [ArgumentError]
|
|
190
|
+
# @return [String]
|
|
191
|
+
def normalize_path(path)
|
|
192
|
+
File.realpath(path)
|
|
193
|
+
rescue SystemCallError, ArgumentError
|
|
194
|
+
File.expand_path(path)
|
|
189
195
|
end
|
|
190
196
|
|
|
191
197
|
# Build error offense entry.
|
|
@@ -193,7 +199,7 @@ module Docscribe
|
|
|
193
199
|
# @private
|
|
194
200
|
# @param [Docscribe::CLI::Formatters::state] state formatter state hash
|
|
195
201
|
# @param [String] path file path string
|
|
196
|
-
# @return [
|
|
202
|
+
# @return [Docscribe::CLI::Formatters::Json::json_offense]
|
|
197
203
|
def error_offense(state, path)
|
|
198
204
|
error_offense_hash(state[:error_messages][path] || 'Unknown error')
|
|
199
205
|
end
|
|
@@ -202,7 +208,7 @@ module Docscribe
|
|
|
202
208
|
#
|
|
203
209
|
# @private
|
|
204
210
|
# @param [String] message error message string
|
|
205
|
-
# @return [
|
|
211
|
+
# @return [Docscribe::CLI::Formatters::Json::json_offense]
|
|
206
212
|
def error_offense_hash(message)
|
|
207
213
|
{ severity: 'fatal', cop_name: 'Docscribe/ProcessingError', message: message,
|
|
208
214
|
corrected: false, correctable: false, location: default_location }
|
|
@@ -211,7 +217,7 @@ module Docscribe
|
|
|
211
217
|
# Default location hash value.
|
|
212
218
|
#
|
|
213
219
|
# @private
|
|
214
|
-
# @return [
|
|
220
|
+
# @return [Docscribe::CLI::Formatters::Json::json_location]
|
|
215
221
|
def default_location
|
|
216
222
|
{ start_line: 1, start_column: 1, last_line: 1, last_column: 1 }
|
|
217
223
|
end
|
|
@@ -221,7 +227,7 @@ module Docscribe
|
|
|
221
227
|
# @private
|
|
222
228
|
# @param [Array<Docscribe::CLI::Formatters::change>] changes changes info array
|
|
223
229
|
# @param [String?] severity offense severity level
|
|
224
|
-
# @return [Array<
|
|
230
|
+
# @return [Array<Docscribe::CLI::Formatters::Json::json_offense>]
|
|
225
231
|
def build_offenses(changes, severity: nil)
|
|
226
232
|
changes.map { |change| build_offense(change, severity) }
|
|
227
233
|
end
|
|
@@ -231,8 +237,18 @@ module Docscribe
|
|
|
231
237
|
# @private
|
|
232
238
|
# @param [Docscribe::CLI::Formatters::change] change change info hash
|
|
233
239
|
# @param [String?] severity offense severity level
|
|
234
|
-
# @return [
|
|
240
|
+
# @return [Docscribe::CLI::Formatters::Json::json_offense]
|
|
235
241
|
def build_offense(change, severity)
|
|
242
|
+
offense = base_offense(change, severity)
|
|
243
|
+
attach_source(offense, change)
|
|
244
|
+
attach_type(offense, change)
|
|
245
|
+
end
|
|
246
|
+
|
|
247
|
+
# @private
|
|
248
|
+
# @param [Docscribe::CLI::Formatters::change] change
|
|
249
|
+
# @param [String?] severity
|
|
250
|
+
# @return [Docscribe::CLI::Formatters::Json::json_offense]
|
|
251
|
+
def base_offense(change, severity)
|
|
236
252
|
{
|
|
237
253
|
severity: severity || SEVERITY_MAP[change[:type]] || 'convention',
|
|
238
254
|
cop_name: COP_NAME_MAP[change[:type]] || cop_name_fallback(change),
|
|
@@ -243,11 +259,40 @@ module Docscribe
|
|
|
243
259
|
}
|
|
244
260
|
end
|
|
245
261
|
|
|
262
|
+
# @private
|
|
263
|
+
# @param [Docscribe::CLI::Formatters::Json::json_offense] offense
|
|
264
|
+
# @param [Docscribe::CLI::Formatters::change] change
|
|
265
|
+
# @return [Docscribe::CLI::Formatters::Json::json_offense]
|
|
266
|
+
def attach_source(offense, change)
|
|
267
|
+
source = offense_source(change)
|
|
268
|
+
offense[:source] = source if source
|
|
269
|
+
offense
|
|
270
|
+
end
|
|
271
|
+
|
|
272
|
+
# Attach machine-readable change type when present.
|
|
273
|
+
#
|
|
274
|
+
# @private
|
|
275
|
+
# @param [Docscribe::CLI::Formatters::Json::json_offense] offense offense hash being built
|
|
276
|
+
# @param [Docscribe::CLI::Formatters::change] change change info hash
|
|
277
|
+
# @return [Docscribe::CLI::Formatters::Json::json_offense]
|
|
278
|
+
def attach_type(offense, change)
|
|
279
|
+
type = change[:type] || change['type']
|
|
280
|
+
offense[:type] = type.to_s if type
|
|
281
|
+
offense
|
|
282
|
+
end
|
|
283
|
+
|
|
284
|
+
# @private
|
|
285
|
+
# @param [Docscribe::CLI::Formatters::change] change
|
|
286
|
+
# @return [String, nil]
|
|
287
|
+
def offense_source(change)
|
|
288
|
+
change[:source] || change['source']
|
|
289
|
+
end
|
|
290
|
+
|
|
246
291
|
# Build location hash from change.
|
|
247
292
|
#
|
|
248
293
|
# @private
|
|
249
294
|
# @param [Docscribe::CLI::Formatters::change] change change info hash
|
|
250
|
-
# @return [
|
|
295
|
+
# @return [Docscribe::CLI::Formatters::Json::json_location]
|
|
251
296
|
def location_for(change)
|
|
252
297
|
line = change[:line] || 1
|
|
253
298
|
{ start_line: line, start_column: 1, last_line: line, last_column: 1 }
|
|
@@ -24,7 +24,8 @@ module Docscribe
|
|
|
24
24
|
insert_full_doc_block: 'note',
|
|
25
25
|
unsorted_tags: 'note',
|
|
26
26
|
updated_param: 'warning',
|
|
27
|
-
updated_return: 'warning'
|
|
27
|
+
updated_return: 'warning',
|
|
28
|
+
invalid_type: 'warning'
|
|
28
29
|
}.freeze
|
|
29
30
|
|
|
30
31
|
COP_NAME_MAP = {
|
|
@@ -36,7 +37,8 @@ module Docscribe
|
|
|
36
37
|
insert_full_doc_block: 'Docscribe/MissingDocBlock',
|
|
37
38
|
unsorted_tags: 'Docscribe/UnsortedTags',
|
|
38
39
|
updated_param: 'Docscribe/UpdatedParam',
|
|
39
|
-
updated_return: 'Docscribe/UpdatedReturn'
|
|
40
|
+
updated_return: 'Docscribe/UpdatedReturn',
|
|
41
|
+
invalid_type: 'Docscribe/InvalidType'
|
|
40
42
|
}.freeze
|
|
41
43
|
|
|
42
44
|
SARIF_SCHEMA = 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/' \
|
|
@@ -159,12 +161,27 @@ module Docscribe
|
|
|
159
161
|
# @param [String?] level
|
|
160
162
|
# @return [Hash<Symbol, Object>]
|
|
161
163
|
def build_result(change, path, level: nil)
|
|
162
|
-
{
|
|
164
|
+
result = {
|
|
163
165
|
ruleId: cop_name_for(change),
|
|
164
166
|
level: level || SEVERITY_MAP[change[:type]] || 'note',
|
|
165
167
|
message: { text: message_for(change) },
|
|
166
168
|
locations: [location(path, change[:line] || 1)]
|
|
167
169
|
}
|
|
170
|
+
properties = result_properties(change)
|
|
171
|
+
result[:properties] = properties unless properties.empty?
|
|
172
|
+
result
|
|
173
|
+
end
|
|
174
|
+
|
|
175
|
+
# @private
|
|
176
|
+
# @param [Docscribe::CLI::Formatters::change] change
|
|
177
|
+
# @return [Hash<Symbol, String>]
|
|
178
|
+
def result_properties(change)
|
|
179
|
+
source = change[:source] || change['source']
|
|
180
|
+
type = change[:type] || change['type']
|
|
181
|
+
properties = {}
|
|
182
|
+
properties[:source] = source if source
|
|
183
|
+
properties[:type] = type.to_s if type
|
|
184
|
+
properties
|
|
168
185
|
end
|
|
169
186
|
|
|
170
187
|
# @private
|