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
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 do |file|
31
- path = File.join(Dir.pwd, file)
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 && true
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 as YAML.
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 = Docscribe::Config.load(opts[:config])
28
- conf = Docscribe::CLI::ConfigBuilder.build(conf, parse_cli_overrides(argv))
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 [Object] node
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 [Object] node
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 [Object] node
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 [Object] node
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 [Object] node
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 [Hash<Symbol, Object>]
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<Hash<Symbol, Object>>] files files offenses 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 [Hash<Symbol, Object>]
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 [Hash<Symbol, String>]
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<Hash<Symbol, Object>>] files files offenses 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 [Hash<Symbol, Integer>]
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<Hash<Symbol, Object>>]
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<Hash<Symbol, Object>>] files files offenses 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 << file_entry(path, state[:fail_changes][path] || [])
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
- files << file_entry(path, state[:type_mismatch_changes][path] || [], severity: 'warning')
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<Hash<Symbol, Object>>] files files offenses 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<Hash<Symbol, Object>>] files files offenses 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<Hash<Symbol, Object>>] files files offenses 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<Hash<Symbol, Object>>] offenses offense objects 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
- # Build single file entry hash.
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
- # @param [Array<Docscribe::CLI::Formatters::change>] changes changes info array
185
- # @param [String?] severity offense severity level
186
- # @return [Hash<Symbol, Object>]
187
- def file_entry(path, changes, severity: nil)
188
- { path: path, offenses: build_offenses(changes, severity: severity) }
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 [Hash<Symbol, Object>]
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 [Hash<Symbol, Object>]
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 [Hash<Symbol, Integer>]
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<Hash<Symbol, Object>>]
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 [Hash<Symbol, Object>]
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 [Hash<Symbol, Integer>]
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