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
|
@@ -28,7 +28,10 @@ module Docscribe
|
|
|
28
28
|
no_boilerplate: false,
|
|
29
29
|
progress: false,
|
|
30
30
|
parallel: false,
|
|
31
|
-
|
|
31
|
+
jobs: nil, #: Integer? when --jobs is passed
|
|
32
|
+
server: false,
|
|
33
|
+
validate_types: nil, #: true or false when --[no-]validate-types is passed, nil otherwise
|
|
34
|
+
warn_invalid_yard: nil #: true or false when --[no-]warn-invalid-yard is passed, nil otherwise
|
|
32
35
|
}.freeze
|
|
33
36
|
|
|
34
37
|
module_function
|
|
@@ -39,7 +42,7 @@ module Docscribe
|
|
|
39
42
|
docscribe generate <type> <name> [options]
|
|
40
43
|
docscribe sigs [options] [files...]
|
|
41
44
|
docscribe rbs [options] [files...]
|
|
42
|
-
docscribe update_types [directory]
|
|
45
|
+
docscribe update_types [directory|file]
|
|
43
46
|
docscribe check_for_comments [paths...]
|
|
44
47
|
|
|
45
48
|
Default behavior:
|
|
@@ -63,6 +66,7 @@ module Docscribe
|
|
|
63
66
|
--sorbet Use Sorbet signatures from inline sigs / RBI files when available
|
|
64
67
|
--rbi-dir DIR Add a Sorbet RBI directory (repeatable). Implies --sorbet.
|
|
65
68
|
--rbs-collection Auto-discover RBS collection from rbs_collection.lock.yaml. Implies --rbs.
|
|
69
|
+
--validate-types Validate YARD types against inferred/RBS types and report mismatches
|
|
66
70
|
|
|
67
71
|
Filtering:
|
|
68
72
|
--include PATTERN Include PATTERN (method id or file path; glob or /regex/)
|
|
@@ -202,6 +206,8 @@ module Docscribe
|
|
|
202
206
|
define_sorbet_option(opts, options)
|
|
203
207
|
define_rbi_dir_option(opts, options)
|
|
204
208
|
define_rbs_collection_option(opts, options)
|
|
209
|
+
define_validate_types_option(opts, options)
|
|
210
|
+
define_warn_invalid_yard_option(opts, options)
|
|
205
211
|
end
|
|
206
212
|
|
|
207
213
|
# Define rbs option
|
|
@@ -267,6 +273,30 @@ module Docscribe
|
|
|
267
273
|
end
|
|
268
274
|
end
|
|
269
275
|
|
|
276
|
+
# Define validate types option
|
|
277
|
+
#
|
|
278
|
+
# @note module_function: defines #define_validate_types_option (visibility: private)
|
|
279
|
+
# @param [OptionParser] opts the option parser to configure
|
|
280
|
+
# @param [Hash<Symbol, Object>] options mutable parsed options hash
|
|
281
|
+
# @return [void]
|
|
282
|
+
def define_validate_types_option(opts, options)
|
|
283
|
+
opts.on('--[no-]validate-types', 'Validate YARD types against inferred/RBS types and report mismatches') do |value|
|
|
284
|
+
options[:validate_types] = value
|
|
285
|
+
end
|
|
286
|
+
end
|
|
287
|
+
|
|
288
|
+
# Define warn invalid yard option
|
|
289
|
+
#
|
|
290
|
+
# @note module_function: defines #define_warn_invalid_yard_option (visibility: private)
|
|
291
|
+
# @param [OptionParser] opts the option parser to configure
|
|
292
|
+
# @param [Hash<Symbol, Object>] options mutable parsed options hash
|
|
293
|
+
# @return [void]
|
|
294
|
+
def define_warn_invalid_yard_option(opts, options)
|
|
295
|
+
opts.on('--[no-]warn-invalid-yard', 'Report syntactically broken YARD types (default: on)') do |value|
|
|
296
|
+
options[:warn_invalid_yard] = value
|
|
297
|
+
end
|
|
298
|
+
end
|
|
299
|
+
|
|
270
300
|
# Define filter options
|
|
271
301
|
#
|
|
272
302
|
# @note module_function: defines #define_filter_options (visibility: private)
|
|
@@ -381,6 +411,10 @@ module Docscribe
|
|
|
381
411
|
opts.on('--parallel', 'Process files in parallel (default: sequential)') do
|
|
382
412
|
options[:parallel] = true
|
|
383
413
|
end
|
|
414
|
+
opts.on('--jobs N', Integer, 'Parallel worker count (implies --parallel)') do |n|
|
|
415
|
+
options[:jobs] = n
|
|
416
|
+
options[:parallel] = true
|
|
417
|
+
end
|
|
384
418
|
end
|
|
385
419
|
|
|
386
420
|
# Define explain option
|
|
@@ -29,7 +29,7 @@ module Docscribe
|
|
|
29
29
|
# @!attribute [rw] options
|
|
30
30
|
# @return [Array<Docscribe::CLI::RbsGen::ParamTag>]
|
|
31
31
|
# @param [Array<Docscribe::CLI::RbsGen::ParamTag>] value
|
|
32
|
-
YardTags = Struct.new(:params, :return_type, :options, keyword_init: true)
|
|
32
|
+
YardTags = Struct.new(:params, :return_type, :options, keyword_init: true) #: Class[YardTags]
|
|
33
33
|
# @!attribute [rw] name
|
|
34
34
|
# @return [String]
|
|
35
35
|
# @param [String] value
|
|
@@ -37,7 +37,7 @@ module Docscribe
|
|
|
37
37
|
# @!attribute [rw] type
|
|
38
38
|
# @return [String]
|
|
39
39
|
# @param [String] value
|
|
40
|
-
ParamTag = Struct.new(:name, :type, keyword_init: true)
|
|
40
|
+
ParamTag = Struct.new(:name, :type, keyword_init: true) #: Class[ParamTag]
|
|
41
41
|
# @!attribute [rw] name
|
|
42
42
|
# @return [Symbol]
|
|
43
43
|
# @param [Symbol] value
|
|
@@ -61,7 +61,7 @@ module Docscribe
|
|
|
61
61
|
# @!attribute [rw] yard_tags
|
|
62
62
|
# @return [Docscribe::CLI::RbsGen::YardTags?]
|
|
63
63
|
# @param [Docscribe::CLI::RbsGen::YardTags?] value
|
|
64
|
-
MethodDef = Struct.new(:name, :scope, :container, :file, :line, :yard_tags, keyword_init: true)
|
|
64
|
+
MethodDef = Struct.new(:name, :scope, :container, :file, :line, :yard_tags, keyword_init: true) #: Class[MethodDef]
|
|
65
65
|
# @!attribute [rw] containers
|
|
66
66
|
# @return [Array<String>]
|
|
67
67
|
# @param [Array<String>] value
|
|
@@ -86,7 +86,7 @@ module Docscribe
|
|
|
86
86
|
# @return [Boolean]
|
|
87
87
|
# @param [Boolean] value
|
|
88
88
|
WalkContext = Struct.new(:containers, :method_defs, :path, :comment_map, :src_lines, :inside_sclass,
|
|
89
|
-
keyword_init: true)
|
|
89
|
+
keyword_init: true) #: Class[WalkContext]
|
|
90
90
|
|
|
91
91
|
class << self
|
|
92
92
|
# @param [Array<String>] argv
|
data/lib/docscribe/cli/run.rb
CHANGED
|
@@ -42,8 +42,12 @@ module Docscribe
|
|
|
42
42
|
include exclude include_file exclude_file
|
|
43
43
|
rbs rbs_collection sig_dirs
|
|
44
44
|
sorbet rbi_dirs
|
|
45
|
+
validate_types warn_invalid_yard
|
|
45
46
|
].freeze
|
|
46
47
|
|
|
48
|
+
# [no-] flags where an explicit false must override a `true` from config.
|
|
49
|
+
NEGATABLE_KEYS = %i[validate_types warn_invalid_yard].freeze
|
|
50
|
+
|
|
47
51
|
# Run Docscribe for files or STDIN using the selected mode and strategy.
|
|
48
52
|
#
|
|
49
53
|
# Modes:
|
|
@@ -145,7 +149,7 @@ module Docscribe
|
|
|
145
149
|
#
|
|
146
150
|
# @param [Docscribe::CLI::Formatters::opts] options parsed CLI options
|
|
147
151
|
# @param [Docscribe::Config] conf effective config
|
|
148
|
-
# @return [
|
|
152
|
+
# @return [Docscribe::CLI::Run::rewrite_result] rewrite result with :output key
|
|
149
153
|
def stdin_rewrite_result(options, conf)
|
|
150
154
|
Docscribe::InlineRewriter.rewrite_with_report(
|
|
151
155
|
$stdin.read,
|
|
@@ -243,7 +247,7 @@ module Docscribe
|
|
|
243
247
|
# @param [Hash<String, Object>] result server result with :changed and :changes keys
|
|
244
248
|
# @param [Array<Docscribe::CLI::Formatters::change>] file_changes change records
|
|
245
249
|
# @param [String] path file path
|
|
246
|
-
# @param [
|
|
250
|
+
# @param [Docscribe::CLI::Run::run_ctx] ctx context hash with :display_path, :options, :state keys
|
|
247
251
|
# @return [void]
|
|
248
252
|
def dispatch_server_result(result, file_changes, path, **ctx)
|
|
249
253
|
if ctx[:options][:mode] == :check
|
|
@@ -326,14 +330,17 @@ module Docscribe
|
|
|
326
330
|
#
|
|
327
331
|
# @param [Hash<String, Object>] change change record from server
|
|
328
332
|
# @return [Docscribe::CLI::Formatters::change]
|
|
329
|
-
def symbolize_change(change)
|
|
330
|
-
{
|
|
333
|
+
def symbolize_change(change) # steep:ignore
|
|
334
|
+
hash = {
|
|
331
335
|
type: change['type'].to_sym,
|
|
332
336
|
file: change['file'],
|
|
333
337
|
line: change['line'],
|
|
334
338
|
method: change['method'],
|
|
335
|
-
message: change['message']
|
|
339
|
+
message: change['message'],
|
|
340
|
+
source: change['source']
|
|
336
341
|
}
|
|
342
|
+
hash[:param] = change['param'] if change['param']
|
|
343
|
+
hash.compact
|
|
337
344
|
end
|
|
338
345
|
|
|
339
346
|
# Expand CLI path arguments into a sorted list of Ruby files.
|
|
@@ -341,6 +348,10 @@ module Docscribe
|
|
|
341
348
|
# Directories are expanded recursively to `**/*.rb`.
|
|
342
349
|
# If no arguments are provided, the current directory is used.
|
|
343
350
|
#
|
|
351
|
+
# Deduplication uses the canonical path, so overlapping arguments
|
|
352
|
+
# that spell one file differently (absolute vs relative, `./`-prefixed,
|
|
353
|
+
# symlinked) are processed once. The first spelling wins.
|
|
354
|
+
#
|
|
344
355
|
# @param [Array<String>] args file and/or directory arguments
|
|
345
356
|
# @return [Array<String>] unique sorted Ruby file paths
|
|
346
357
|
def expand_paths(args)
|
|
@@ -351,7 +362,34 @@ module Docscribe
|
|
|
351
362
|
append_expanded_path(files, path)
|
|
352
363
|
end
|
|
353
364
|
|
|
354
|
-
files.
|
|
365
|
+
dedupe_paths(files).sort
|
|
366
|
+
end
|
|
367
|
+
|
|
368
|
+
# Drop later spellings of a file already collected.
|
|
369
|
+
#
|
|
370
|
+
# @param [Array<String>] files expanded paths, possibly overlapping
|
|
371
|
+
# @return [Array<String>] paths with one entry per canonical file
|
|
372
|
+
def dedupe_paths(files)
|
|
373
|
+
seen = {} #: Hash[String, true]
|
|
374
|
+
files.each_with_object([]) do |path, acc| #: Array[String]
|
|
375
|
+
key = canonical_path(path)
|
|
376
|
+
next if seen[key]
|
|
377
|
+
|
|
378
|
+
seen[key] = true
|
|
379
|
+
acc << path
|
|
380
|
+
end
|
|
381
|
+
end
|
|
382
|
+
|
|
383
|
+
# Canonical identity for a path, resolving symlinks and relative segments.
|
|
384
|
+
#
|
|
385
|
+
# @param [String] path file path
|
|
386
|
+
# @raise [SystemCallError] when the file is gone (caught here)
|
|
387
|
+
# @raise [ArgumentError] when the path is malformed (caught here)
|
|
388
|
+
# @return [String]
|
|
389
|
+
def canonical_path(path)
|
|
390
|
+
File.realpath(path)
|
|
391
|
+
rescue SystemCallError, ArgumentError
|
|
392
|
+
File.expand_path(path)
|
|
355
393
|
end
|
|
356
394
|
|
|
357
395
|
# Append a file or recursively expand a directory into the files array.
|
|
@@ -401,7 +439,7 @@ module Docscribe
|
|
|
401
439
|
run_exit_code(options, state)
|
|
402
440
|
end
|
|
403
441
|
|
|
404
|
-
# Process files in parallel using
|
|
442
|
+
# Process files in parallel using forked workers.
|
|
405
443
|
#
|
|
406
444
|
# @param [Docscribe::CLI::Formatters::opts] options parsed CLI options
|
|
407
445
|
# @param [Docscribe::Config] conf effective config
|
|
@@ -416,53 +454,147 @@ module Docscribe
|
|
|
416
454
|
run_exit_code(options, state)
|
|
417
455
|
end
|
|
418
456
|
|
|
419
|
-
#
|
|
420
|
-
#
|
|
457
|
+
# Split the work across forked children and merge their states.
|
|
458
|
+
#
|
|
459
|
+
# Children inherit the warmed process (gems, config, RBS env) through
|
|
460
|
+
# copy-on-write, so each fork skips the cold-start cost that made the
|
|
461
|
+
# earlier thread implementation slower than a sequential run.
|
|
462
|
+
#
|
|
463
|
+
# @param [Docscribe::CLI::Formatters::opts] options
|
|
464
|
+
# @param [Docscribe::Config] conf
|
|
421
465
|
# @param [Array<String>] paths
|
|
422
466
|
# @param [Docscribe::CLI::Formatters::state] state
|
|
467
|
+
# @raise [StandardError]
|
|
423
468
|
# @return [void]
|
|
424
469
|
def run_parallel_workers(options, conf, paths, state)
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
470
|
+
return if paths.empty?
|
|
471
|
+
return run_files_sequential(options, conf, paths, state) unless fork_supported?
|
|
472
|
+
|
|
473
|
+
jobs = parallel_job_count(options)
|
|
474
|
+
warm_rewrite_env(options, conf, paths)
|
|
475
|
+
slices = split_paths(paths, jobs).reject(&:empty?)
|
|
476
|
+
return if slices.empty?
|
|
477
|
+
|
|
478
|
+
children = slices.map { |slice| start_forked_slice(slice, options, conf) }
|
|
479
|
+
merge_forked_slices(children, state)
|
|
431
480
|
end
|
|
432
481
|
|
|
433
|
-
#
|
|
434
|
-
#
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
482
|
+
# Whether forked workers can run here.
|
|
483
|
+
#
|
|
484
|
+
# Without fork (Windows, some locked-down containers) spawning workers
|
|
485
|
+
# would raise NotImplementedError, so parallel mode silently degrades to
|
|
486
|
+
# the sequential path. Threads are not used as a fallback: on CPU-bound
|
|
487
|
+
# rewriting they are measurably slower than a plain sequential run.
|
|
488
|
+
#
|
|
489
|
+
# @return [Boolean]
|
|
490
|
+
def fork_supported?
|
|
491
|
+
Process.respond_to?(:fork)
|
|
492
|
+
end
|
|
493
|
+
|
|
494
|
+
# Run the same file list sequentially, reusing the shared state.
|
|
495
|
+
#
|
|
496
|
+
# @param [Docscribe::CLI::Formatters::opts] options
|
|
497
|
+
# @param [Docscribe::Config] conf
|
|
498
|
+
# @param [Array<String>] paths
|
|
499
|
+
# @param [Docscribe::CLI::Formatters::state] state
|
|
500
|
+
# @return [void]
|
|
501
|
+
def run_files_sequential(options, conf, paths, state)
|
|
502
|
+
paths.each do |path|
|
|
503
|
+
process_one_file(path, options: options, conf: conf, pwd: Pathname.pwd, state: state)
|
|
504
|
+
end
|
|
505
|
+
end
|
|
506
|
+
|
|
507
|
+
# Fork one child per slice and return its pipe and pid.
|
|
508
|
+
#
|
|
509
|
+
# All children are started before any is collected, so the slices
|
|
510
|
+
# actually overlap instead of running one after another.
|
|
511
|
+
#
|
|
512
|
+
# @param [Array<String>] slice paths handled by this child
|
|
513
|
+
# @param [Docscribe::CLI::Formatters::opts] options
|
|
514
|
+
# @param [Docscribe::Config] conf
|
|
515
|
+
# @raise [StandardError] when the fork itself fails
|
|
516
|
+
# @return [(Integer, IO)] pid and reader pipe for the child
|
|
517
|
+
def start_forked_slice(slice, options, conf)
|
|
518
|
+
reader, writer = IO.pipe
|
|
519
|
+
pid = fork { run_forked_slice(slice, options, conf, writer) }
|
|
520
|
+
writer.close
|
|
521
|
+
[pid, reader]
|
|
522
|
+
end
|
|
523
|
+
|
|
524
|
+
# Collect every child's marshalled state and merge it into the parent.
|
|
525
|
+
#
|
|
526
|
+
# @param [Array<(Integer, IO)>] children pid and reader pairs
|
|
527
|
+
# @param [Docscribe::CLI::Formatters::state] state shared parent state
|
|
528
|
+
# @return [void]
|
|
529
|
+
def merge_forked_slices(children, state)
|
|
530
|
+
mutex = Mutex.new
|
|
531
|
+
children.each do |(pid, reader)|
|
|
532
|
+
payload = reader.read
|
|
533
|
+
reader.close
|
|
534
|
+
Process.wait(pid)
|
|
535
|
+
local_state = Marshal.load(payload) if payload && !payload.empty? # rubocop:disable Security/MarshalLoad
|
|
536
|
+
merge_state(state, local_state, mutex) if local_state
|
|
441
537
|
end
|
|
442
538
|
end
|
|
443
539
|
|
|
540
|
+
# Warm the shared rewrite environment once before forking.
|
|
541
|
+
#
|
|
542
|
+
# Doing the first rewrite here means every child inherits the built
|
|
543
|
+
# RBS provider instead of racing to construct its own.
|
|
544
|
+
#
|
|
545
|
+
# @param [Docscribe::CLI::Formatters::opts] options
|
|
546
|
+
# @param [Docscribe::Config] conf
|
|
444
547
|
# @param [Array<String>] paths
|
|
445
|
-
# @
|
|
446
|
-
# @return [
|
|
447
|
-
def
|
|
448
|
-
path =
|
|
449
|
-
|
|
450
|
-
|
|
548
|
+
# @raise [StandardError] when the warm-up rewrite fails (ignored here)
|
|
549
|
+
# @return [void]
|
|
550
|
+
def warm_rewrite_env(options, conf, paths)
|
|
551
|
+
path = paths.first
|
|
552
|
+
return unless path
|
|
553
|
+
|
|
554
|
+
warm_state = initial_run_state
|
|
555
|
+
process_one_file(path, options: options, conf: conf, pwd: Pathname.pwd, state: warm_state)
|
|
556
|
+
rescue StandardError
|
|
557
|
+
nil
|
|
451
558
|
end
|
|
452
559
|
|
|
453
|
-
#
|
|
454
|
-
#
|
|
560
|
+
# Child-process body: process a slice and ship its state back.
|
|
561
|
+
#
|
|
562
|
+
# @param [Array<String>] slice
|
|
563
|
+
# @param [Docscribe::CLI::Formatters::opts] options
|
|
564
|
+
# @param [Docscribe::Config] conf
|
|
565
|
+
# @param [IO] writer pipe back to the parent
|
|
455
566
|
# @raise [StandardError]
|
|
456
567
|
# @return [void]
|
|
457
|
-
|
|
458
|
-
def run_and_merge(path, pool)
|
|
568
|
+
def run_forked_slice(slice, options, conf, writer)
|
|
459
569
|
local_state = initial_run_state
|
|
460
|
-
|
|
461
|
-
|
|
570
|
+
slice.each do |path|
|
|
571
|
+
process_one_file(path, options: options, conf: conf, pwd: Pathname.pwd, state: local_state)
|
|
572
|
+
end
|
|
573
|
+
writer.write(Marshal.dump(local_state))
|
|
462
574
|
rescue StandardError => e
|
|
463
|
-
|
|
575
|
+
writer.write(Marshal.dump(error_only_state(slice, e)))
|
|
576
|
+
ensure
|
|
577
|
+
writer.close
|
|
578
|
+
exit!(0)
|
|
579
|
+
end
|
|
580
|
+
|
|
581
|
+
# Build a state carrying just the error for a failed slice.
|
|
582
|
+
#
|
|
583
|
+
# @param [Array<String>] slice
|
|
584
|
+
# @param [StandardError] exception
|
|
585
|
+
# @return [Docscribe::CLI::Formatters::state]
|
|
586
|
+
def error_only_state(slice, exception)
|
|
587
|
+
local_state = initial_run_state
|
|
588
|
+
local_state[:had_errors] = true
|
|
589
|
+
slice.each do |path|
|
|
590
|
+
local_state[:error_paths] << path
|
|
591
|
+
local_state[:error_messages][path] = "#{exception.class}: #{exception.message}"
|
|
592
|
+
end
|
|
593
|
+
local_state
|
|
464
594
|
end
|
|
465
595
|
|
|
596
|
+
# Record a worker failure on the shared state.
|
|
597
|
+
#
|
|
466
598
|
# @param [StandardError] exception
|
|
467
599
|
# @param [String] path
|
|
468
600
|
# @param [Docscribe::CLI::Formatters::state] state
|
|
@@ -477,6 +609,38 @@ module Docscribe
|
|
|
477
609
|
$stderr.print('E')
|
|
478
610
|
end
|
|
479
611
|
|
|
612
|
+
# Resolve the worker count: --jobs, then DOCSCRIBE_THREADS, then CPU count.
|
|
613
|
+
#
|
|
614
|
+
# @param [Docscribe::CLI::Formatters::opts] options
|
|
615
|
+
# @return [Integer] positive worker count
|
|
616
|
+
def parallel_job_count(options)
|
|
617
|
+
requested = options[:jobs] || ENV.fetch('DOCSCRIBE_THREADS', nil)&.to_i
|
|
618
|
+
jobs = requested || default_job_count
|
|
619
|
+
jobs.positive? ? jobs : 1
|
|
620
|
+
end
|
|
621
|
+
|
|
622
|
+
# @raise [StandardError] when processor detection is unavailable
|
|
623
|
+
# @return [Integer] default worker count based on available CPUs
|
|
624
|
+
def default_job_count
|
|
625
|
+
require 'etc'
|
|
626
|
+
Etc.nprocessors
|
|
627
|
+
rescue StandardError
|
|
628
|
+
PARALLEL_DEFAULT_THREADS
|
|
629
|
+
end
|
|
630
|
+
|
|
631
|
+
# Split paths into contiguous slices of roughly equal size.
|
|
632
|
+
#
|
|
633
|
+
# @param [Array<String>] paths
|
|
634
|
+
# @param [Integer] jobs
|
|
635
|
+
# @return [Array<Array<String>>]
|
|
636
|
+
def split_paths(paths, jobs)
|
|
637
|
+
return [paths] if jobs <= 1
|
|
638
|
+
|
|
639
|
+
size = (paths.size.to_f / jobs).ceil
|
|
640
|
+
size = 1 if size < 1
|
|
641
|
+
paths.each_slice(size).to_a
|
|
642
|
+
end
|
|
643
|
+
|
|
480
644
|
# Merge a thread-local state into the shared state under mutex protection.
|
|
481
645
|
#
|
|
482
646
|
# @param [Docscribe::CLI::Formatters::state] target shared state to merge into
|
|
@@ -537,7 +701,9 @@ module Docscribe
|
|
|
537
701
|
overrides = options.slice(*CLI_OVERRIDE_KEYS)
|
|
538
702
|
acc = {} #: Hash[String, untyped]
|
|
539
703
|
overrides.each do |k, v|
|
|
540
|
-
next if v.nil?
|
|
704
|
+
next if v.nil?
|
|
705
|
+
# Negations matter for [no-] flags: false must beat a `true` in yml.
|
|
706
|
+
next if v == false && !NEGATABLE_KEYS.include?(k)
|
|
541
707
|
next if v.is_a?(Array) && v.empty?
|
|
542
708
|
|
|
543
709
|
acc[k.to_s] = v
|
|
@@ -605,7 +771,7 @@ module Docscribe
|
|
|
605
771
|
return unless result
|
|
606
772
|
|
|
607
773
|
dispatch_file_result(path, src: src, out: result[:output], file_changes: result[:changes] || [],
|
|
608
|
-
display_path: display_path, options: options, state: state)
|
|
774
|
+
display_path: display_path, options: options, state: state, conf: conf)
|
|
609
775
|
end
|
|
610
776
|
|
|
611
777
|
# Print progress indicator to stderr when --progress is active.
|
|
@@ -629,7 +795,7 @@ module Docscribe
|
|
|
629
795
|
# @param [String] src original source code
|
|
630
796
|
# @param [String] out rewritten source code
|
|
631
797
|
# @param [Array<Docscribe::CLI::Formatters::change>] file_changes structured change records
|
|
632
|
-
# @param [
|
|
798
|
+
# @param [Docscribe::CLI::Run::run_ctx] ctx context hash with :options, :state, :display_path, :conf
|
|
633
799
|
# @return [void]
|
|
634
800
|
def dispatch_file_result(path, src:, out:, file_changes:, **ctx)
|
|
635
801
|
if ctx[:options][:mode] == :check
|
|
@@ -687,9 +853,9 @@ module Docscribe
|
|
|
687
853
|
# @private
|
|
688
854
|
# @param [String] path file path
|
|
689
855
|
# @param [String] src source code
|
|
690
|
-
# @param [
|
|
856
|
+
# @param [Docscribe::CLI::Run::run_ctx] ctx context hash with :conf, :display_path, :options, :state keys
|
|
691
857
|
# @raise [StandardError]
|
|
692
|
-
# @return [
|
|
858
|
+
# @return [Docscribe::CLI::Run::rewrite_result, nil]
|
|
693
859
|
# @return [nil] if StandardError
|
|
694
860
|
def rewrite_result_for_path(path, src:, ctx:)
|
|
695
861
|
conf = ctx[:conf]
|
|
@@ -710,7 +876,7 @@ module Docscribe
|
|
|
710
876
|
# @private
|
|
711
877
|
# @param [String] path file path that caused the error
|
|
712
878
|
# @param [StandardError] error the exception raised during rewriting
|
|
713
|
-
# @param [
|
|
879
|
+
# @param [Docscribe::CLI::Run::run_ctx] ctx context hash with :state, :options, :display_path
|
|
714
880
|
# @return [void]
|
|
715
881
|
def record_rewrite_error(path, error, ctx)
|
|
716
882
|
state = ctx[:state]
|
|
@@ -733,18 +899,97 @@ module Docscribe
|
|
|
733
899
|
# @param [String] src original source code
|
|
734
900
|
# @param [String] out rewritten source code
|
|
735
901
|
# @param [Array<Docscribe::CLI::Formatters::change>] file_changes structured change records
|
|
736
|
-
# @param [
|
|
902
|
+
# @param [Docscribe::CLI::Run::run_ctx] ctx context hash with :display_path, :options, :state keys
|
|
737
903
|
# @return [void]
|
|
738
904
|
def handle_check_result(path, src:, out:, file_changes:, **ctx)
|
|
739
905
|
type_mismatches = type_mismatch_changes(file_changes)
|
|
740
|
-
has_real_changes =
|
|
906
|
+
has_real_changes = real_changes?(file_changes)
|
|
907
|
+
return handle_validated_type_mismatch(path, file_changes, type_mismatches, ctx) if validated_mismatch?(ctx, type_mismatches, out, src, has_real_changes)
|
|
908
|
+
return handle_no_changes(path, type_mismatches, ctx) if no_real_changes?(out, src, has_real_changes)
|
|
741
909
|
|
|
742
|
-
|
|
743
|
-
|
|
744
|
-
|
|
745
|
-
|
|
746
|
-
|
|
910
|
+
handle_failed_check(path, file_changes, ctx)
|
|
911
|
+
end
|
|
912
|
+
|
|
913
|
+
# @private
|
|
914
|
+
# @param [Array<Docscribe::CLI::Formatters::change>] file_changes
|
|
915
|
+
# @return [Boolean]
|
|
916
|
+
def real_changes?(file_changes)
|
|
917
|
+
file_changes.any? { |c| !%i[updated_param updated_return invalid_type].include?(c[:type]) }
|
|
918
|
+
end
|
|
919
|
+
|
|
920
|
+
# @private
|
|
921
|
+
# @param [Docscribe::CLI::Run::run_ctx] ctx
|
|
922
|
+
# @param [Array<Docscribe::CLI::Formatters::change>] type_mismatches
|
|
923
|
+
# @param [String] out
|
|
924
|
+
# @param [String] src
|
|
925
|
+
# @param [Boolean] has_real_changes
|
|
926
|
+
# @return [Boolean]
|
|
927
|
+
def validated_mismatch?(ctx, type_mismatches, out, src, has_real_changes)
|
|
928
|
+
validate_types_enabled?(ctx) && type_mismatches.any? && out == src && !has_real_changes
|
|
929
|
+
end
|
|
747
930
|
|
|
931
|
+
# @private
|
|
932
|
+
# @param [Docscribe::CLI::Run::run_ctx] ctx
|
|
933
|
+
# @return [Boolean]
|
|
934
|
+
def validate_types_enabled?(ctx)
|
|
935
|
+
return true if ctx[:options][:validate_types] == true
|
|
936
|
+
return false if ctx[:options][:validate_types] == false
|
|
937
|
+
|
|
938
|
+
ctx[:conf].respond_to?(:validate_types?) && ctx[:conf].validate_types?
|
|
939
|
+
end
|
|
940
|
+
|
|
941
|
+
# @private
|
|
942
|
+
# @param [String] out
|
|
943
|
+
# @param [String] src
|
|
944
|
+
# @param [Boolean] has_real_changes
|
|
945
|
+
# @return [Boolean]
|
|
946
|
+
def no_real_changes?(out, src, has_real_changes)
|
|
947
|
+
out == src && !has_real_changes
|
|
948
|
+
end
|
|
949
|
+
|
|
950
|
+
# @private
|
|
951
|
+
# @param [String] path
|
|
952
|
+
# @param [Array<Docscribe::CLI::Formatters::change>] file_changes
|
|
953
|
+
# @param [Array<Docscribe::CLI::Formatters::change>] type_mismatches
|
|
954
|
+
# @param [Docscribe::CLI::Run::run_ctx] ctx
|
|
955
|
+
# @return [void]
|
|
956
|
+
def handle_validated_type_mismatch(path, file_changes, type_mismatches, ctx)
|
|
957
|
+
handle_failed_check(path, file_changes, ctx)
|
|
958
|
+
# Drop the records the tracker already holds: the same mismatch must
|
|
959
|
+
# not appear (and count) twice in JSON output.
|
|
960
|
+
stored = ctx[:state][:fail_changes][path] || []
|
|
961
|
+
ctx[:state][:fail_changes][path] = stored - type_mismatches
|
|
962
|
+
track_validated_mismatch(type_mismatches, ctx, path)
|
|
963
|
+
end
|
|
964
|
+
|
|
965
|
+
# @private
|
|
966
|
+
# @param [Array<Docscribe::CLI::Formatters::change>] type_mismatches
|
|
967
|
+
# @param [Docscribe::CLI::Run::run_ctx] ctx
|
|
968
|
+
# @param [String] path raw file path, used as the map key so fail and
|
|
969
|
+
# mismatch entries merge in JSON output
|
|
970
|
+
# @return [void]
|
|
971
|
+
def track_validated_mismatch(type_mismatches, ctx, path)
|
|
972
|
+
state = ctx[:state]
|
|
973
|
+
state[:type_mismatch_paths] << path unless state[:type_mismatch_paths].include?(path)
|
|
974
|
+
state[:type_mismatch_changes][path] = type_mismatches
|
|
975
|
+
end
|
|
976
|
+
|
|
977
|
+
# @private
|
|
978
|
+
# @param [String] path
|
|
979
|
+
# @param [Array<Docscribe::CLI::Formatters::change>] type_mismatches
|
|
980
|
+
# @param [Docscribe::CLI::Run::run_ctx] ctx
|
|
981
|
+
# @return [void]
|
|
982
|
+
def handle_no_changes(path, type_mismatches, ctx)
|
|
983
|
+
handle_check_no_changes(path, type_mismatches: type_mismatches, display_path: ctx[:display_path],
|
|
984
|
+
options: ctx[:options], state: ctx[:state])
|
|
985
|
+
end
|
|
986
|
+
|
|
987
|
+
# @private
|
|
988
|
+
# @param [String] path
|
|
989
|
+
# @param [Array<Docscribe::CLI::Formatters::change>] file_changes
|
|
990
|
+
# @param [Docscribe::CLI::Run::run_ctx] ctx
|
|
991
|
+
# @return [void]
|
|
992
|
+
def handle_failed_check(path, file_changes, ctx)
|
|
748
993
|
handle_check_failed(path, file_changes: file_changes, display_path: ctx[:display_path],
|
|
749
994
|
options: ctx[:options], state: ctx[:state])
|
|
750
995
|
end
|
|
@@ -755,7 +1000,7 @@ module Docscribe
|
|
|
755
1000
|
# @param [Array<Docscribe::CLI::Formatters::change>] file_changes structured change records
|
|
756
1001
|
# @return [Array<Docscribe::CLI::Formatters::change>]
|
|
757
1002
|
def type_mismatch_changes(file_changes)
|
|
758
|
-
file_changes.select { |c| %i[updated_param updated_return].include?(c[:type]) }
|
|
1003
|
+
file_changes.select { |c| %i[updated_param updated_return invalid_type].include?(c[:type]) }
|
|
759
1004
|
end
|
|
760
1005
|
|
|
761
1006
|
# Handle check result when there are no real changes.
|
|
@@ -809,7 +1054,7 @@ module Docscribe
|
|
|
809
1054
|
# @param [String] src original source code
|
|
810
1055
|
# @param [String] out rewritten source code
|
|
811
1056
|
# @param [Array<Docscribe::CLI::Formatters::change>] file_changes structured change records
|
|
812
|
-
# @param [
|
|
1057
|
+
# @param [Docscribe::CLI::Run::run_ctx] ctx context hash with :display_path, :options, :state keys
|
|
813
1058
|
# @raise [StandardError]
|
|
814
1059
|
# @return [void]
|
|
815
1060
|
# @return [Object] if StandardError
|
|
@@ -827,7 +1072,7 @@ module Docscribe
|
|
|
827
1072
|
# @param [String] path file path
|
|
828
1073
|
# @param [String] out rewritten source code
|
|
829
1074
|
# @param [Array<Docscribe::CLI::Formatters::change>] file_changes structured change records
|
|
830
|
-
# @param [
|
|
1075
|
+
# @param [Docscribe::CLI::Run::run_ctx] ctx context hash with :display_path, :options, :state keys
|
|
831
1076
|
# @return [void]
|
|
832
1077
|
def apply_correction(path, out, file_changes, ctx)
|
|
833
1078
|
File.write(path, out)
|