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
|
@@ -10,7 +10,7 @@ module Docscribe
|
|
|
10
10
|
# Two-pass update: rebuild docs then re-merge with RBS types.
|
|
11
11
|
#
|
|
12
12
|
# Usage:
|
|
13
|
-
# docscribe update_types [directory]
|
|
13
|
+
# docscribe update_types [directory|file]
|
|
14
14
|
#
|
|
15
15
|
# Pass 1: `-AkB --rbs-collection <dir>` — aggressive rebuild, keep descriptions,
|
|
16
16
|
# no boilerplate, using RBS collection signatures.
|
|
@@ -18,7 +18,7 @@ module Docscribe
|
|
|
18
18
|
# using RBS collection signatures.
|
|
19
19
|
module UpdateTypes
|
|
20
20
|
BANNER = <<~TEXT
|
|
21
|
-
Usage: docscribe update_types [directory]
|
|
21
|
+
Usage: docscribe update_types [directory|file] [options]
|
|
22
22
|
|
|
23
23
|
Two-pass type-aware documentation update.
|
|
24
24
|
|
|
@@ -28,6 +28,8 @@ module Docscribe
|
|
|
28
28
|
Pass 2 (safe): docscribe -aB --rbs-collection <dir>
|
|
29
29
|
safe merge cleanup, no boilerplate
|
|
30
30
|
|
|
31
|
+
See `docscribe --help` for type options (--rbs, --sig-dir, --rbs-collection, --[no-]validate-types).
|
|
32
|
+
|
|
31
33
|
TEXT
|
|
32
34
|
|
|
33
35
|
class << self
|
|
@@ -35,14 +37,15 @@ module Docscribe
|
|
|
35
37
|
# @return [Integer]
|
|
36
38
|
def run(argv)
|
|
37
39
|
options = parse_options(argv)
|
|
38
|
-
|
|
40
|
+
target = options[:dir]
|
|
41
|
+
@extra_argv = options[:extra_argv]
|
|
39
42
|
|
|
40
43
|
announce_start
|
|
41
44
|
|
|
42
|
-
exit1 = run_first_pass(
|
|
45
|
+
exit1 = run_first_pass(target)
|
|
43
46
|
return exit1 unless exit1.zero?
|
|
44
47
|
|
|
45
|
-
exit2 = run_second_pass(
|
|
48
|
+
exit2 = run_second_pass(target)
|
|
46
49
|
return exit2 unless exit2.zero?
|
|
47
50
|
|
|
48
51
|
announce_complete
|
|
@@ -54,13 +57,28 @@ module Docscribe
|
|
|
54
57
|
# @private
|
|
55
58
|
# @param [Array<String>] argv
|
|
56
59
|
# @return [Hash<Symbol, Object>]
|
|
57
|
-
def parse_options(argv)
|
|
58
|
-
options = { dir: '.' }
|
|
60
|
+
def parse_options(argv) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
|
|
61
|
+
options = { dir: '.', extra_argv: [] }
|
|
62
|
+
extra_argv = []
|
|
59
63
|
OptionParser.new(BANNER) do |opts|
|
|
60
64
|
opts.on('-h', '--help', 'Show this help') { puts opts or exit 0 }
|
|
65
|
+
opts.on('--[no-]rbs', 'Use RBS signatures when available') do |v|
|
|
66
|
+
extra_argv << (v ? '--rbs' : '--no-rbs')
|
|
67
|
+
end
|
|
68
|
+
opts.on('--sig-dir DIR', 'Add an RBS signature directory (repeatable). Implies --rbs.') do |v|
|
|
69
|
+
extra_argv << '--sig-dir' << v
|
|
70
|
+
end
|
|
71
|
+
opts.on('--rbs-collection', 'Auto-discover RBS collection from rbs_collection.lock.yaml. Implies --rbs.') do
|
|
72
|
+
extra_argv << '--rbs-collection'
|
|
73
|
+
end
|
|
74
|
+
opts.on('--[no-]validate-types', 'Validate YARD types against inferred/RBS types (optional, default: off)') do |v|
|
|
75
|
+
extra_argv << (v ? '--validate-types' : '--no-validate-types')
|
|
76
|
+
end
|
|
61
77
|
opts.parse!(argv)
|
|
62
78
|
end
|
|
63
79
|
options[:dir] = argv.first if argv.any?
|
|
80
|
+
options[:extra_argv] = extra_argv
|
|
81
|
+
@extra_argv = extra_argv
|
|
64
82
|
options
|
|
65
83
|
end
|
|
66
84
|
|
|
@@ -72,23 +90,49 @@ module Docscribe
|
|
|
72
90
|
end
|
|
73
91
|
|
|
74
92
|
# @private
|
|
75
|
-
# @param [String]
|
|
93
|
+
# @param [String] target
|
|
76
94
|
# @return [Integer]
|
|
77
|
-
def run_first_pass(
|
|
78
|
-
|
|
79
|
-
|
|
95
|
+
def run_first_pass(target) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
|
|
96
|
+
dir_for_flag = File.file?(target) ? File.dirname(target) : target
|
|
97
|
+
has_collection = File.exist?(File.join(dir_for_flag, 'rbs_collection.lock.yaml')) || File.exist?('rbs_collection.lock.yaml')
|
|
98
|
+
flag = has_collection ? '--rbs-collection' : '--rbs'
|
|
99
|
+
extra = @extra_argv || []
|
|
100
|
+
filtered = extra.reject { |a| a == '--no-rbs' }
|
|
101
|
+
has_rbs_flag = extra.any? { |a| %w[--rbs --rbs-collection --no-rbs].include?(a) }
|
|
102
|
+
has_no_rbs = extra.include?('--no-rbs')
|
|
103
|
+
argv1 = ['-AkB']
|
|
104
|
+
argv1.concat(filtered)
|
|
105
|
+
if has_rbs_flag
|
|
106
|
+
argv1 << dir_for_flag unless has_no_rbs || argv1.include?(dir_for_flag)
|
|
107
|
+
else
|
|
108
|
+
argv1 << flag << dir_for_flag
|
|
109
|
+
end
|
|
110
|
+
puts "Pass 1: Aggressive rebuild with #{has_collection ? 'RBS collection' : 'RBS'}#{' + validate-types' if extra.include?('--validate-types')}..."
|
|
80
111
|
options1 = Docscribe::CLI::Options.parse!(argv1)
|
|
81
|
-
Docscribe::CLI::Run.run(options: options1, argv: [
|
|
112
|
+
Docscribe::CLI::Run.run(options: options1, argv: [target])
|
|
82
113
|
end
|
|
83
114
|
|
|
84
115
|
# @private
|
|
85
|
-
# @param [String]
|
|
116
|
+
# @param [String] target
|
|
86
117
|
# @return [Integer]
|
|
87
|
-
def run_second_pass(
|
|
88
|
-
|
|
89
|
-
|
|
118
|
+
def run_second_pass(target) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
|
|
119
|
+
dir_for_flag = File.file?(target) ? File.dirname(target) : target
|
|
120
|
+
has_collection = File.exist?(File.join(dir_for_flag, 'rbs_collection.lock.yaml')) || File.exist?('rbs_collection.lock.yaml')
|
|
121
|
+
flag = has_collection ? '--rbs-collection' : '--rbs'
|
|
122
|
+
extra = @extra_argv || []
|
|
123
|
+
filtered = extra.reject { |a| a == '--no-rbs' }
|
|
124
|
+
has_rbs_flag = extra.any? { |a| %w[--rbs --rbs-collection --no-rbs].include?(a) }
|
|
125
|
+
has_no_rbs = extra.include?('--no-rbs')
|
|
126
|
+
argv2 = ['-aB']
|
|
127
|
+
argv2.concat(filtered)
|
|
128
|
+
if has_rbs_flag
|
|
129
|
+
argv2 << dir_for_flag unless has_no_rbs || argv2.include?(dir_for_flag)
|
|
130
|
+
else
|
|
131
|
+
argv2 << flag << dir_for_flag
|
|
132
|
+
end
|
|
133
|
+
puts "Pass 2: Safe merge with #{has_collection ? 'RBS collection' : 'RBS'}#{' + validate-types' if extra.include?('--validate-types')}..."
|
|
90
134
|
options2 = Docscribe::CLI::Options.parse!(argv2)
|
|
91
|
-
Docscribe::CLI::Run.run(options: options2, argv: [
|
|
135
|
+
Docscribe::CLI::Run.run(options: options2, argv: [target])
|
|
92
136
|
end
|
|
93
137
|
|
|
94
138
|
# @private
|
data/lib/docscribe/cli.rb
CHANGED
|
@@ -6,6 +6,24 @@ require 'docscribe/cli/run'
|
|
|
6
6
|
module Docscribe
|
|
7
7
|
# CLI entry point and command dispatch.
|
|
8
8
|
module CLI
|
|
9
|
+
COMMANDS = {
|
|
10
|
+
'check_for_comments' => :CheckForComments,
|
|
11
|
+
'config' => :ConfigDump,
|
|
12
|
+
'coverage' => :Coverage,
|
|
13
|
+
'generate' => :Generate,
|
|
14
|
+
'init' => :Init,
|
|
15
|
+
'rbs' => :RbsGen,
|
|
16
|
+
'server' => :ServerCmd,
|
|
17
|
+
'sigs' => :Sigs,
|
|
18
|
+
'update_types' => :UpdateTypes
|
|
19
|
+
}.freeze
|
|
20
|
+
|
|
21
|
+
# Subcommands whose file name differs from the command name.
|
|
22
|
+
SUBCOMMAND_FILES = {
|
|
23
|
+
'config' => 'config_dump',
|
|
24
|
+
'rbs' => 'rbs_gen'
|
|
25
|
+
}.freeze
|
|
26
|
+
|
|
9
27
|
class << self
|
|
10
28
|
# @param [Array<String>] argv
|
|
11
29
|
# @return [Integer]
|
|
@@ -17,18 +35,6 @@ module Docscribe
|
|
|
17
35
|
Docscribe::CLI::Run.run(options: options, argv: argv)
|
|
18
36
|
end
|
|
19
37
|
|
|
20
|
-
COMMANDS = {
|
|
21
|
-
'check_for_comments' => :CheckForComments,
|
|
22
|
-
'config' => :ConfigDump,
|
|
23
|
-
'coverage' => :Coverage,
|
|
24
|
-
'generate' => :Generate,
|
|
25
|
-
'init' => :Init,
|
|
26
|
-
'rbs' => :RbsGen,
|
|
27
|
-
'server' => :ServerCmd,
|
|
28
|
-
'sigs' => :Sigs,
|
|
29
|
-
'update_types' => :UpdateTypes
|
|
30
|
-
}.freeze
|
|
31
|
-
|
|
32
38
|
private
|
|
33
39
|
|
|
34
40
|
# @private
|
|
@@ -46,7 +52,7 @@ module Docscribe
|
|
|
46
52
|
const_name = COMMANDS[cmd]
|
|
47
53
|
return 0 unless const_name
|
|
48
54
|
|
|
49
|
-
require "docscribe/cli/#{cmd
|
|
55
|
+
require "docscribe/cli/#{SUBCOMMAND_FILES.fetch(cmd) { cmd }}"
|
|
50
56
|
Docscribe::CLI.const_get(const_name).run(argv)
|
|
51
57
|
end
|
|
52
58
|
end
|
|
@@ -5,9 +5,9 @@ module Docscribe
|
|
|
5
5
|
class Config
|
|
6
6
|
# Load and register plugins declared under `plugins.require` in config.
|
|
7
7
|
#
|
|
8
|
-
# Each entry is expanded relative to the
|
|
9
|
-
# passed to `require`. Registration is expected to
|
|
10
|
-
# required file via {Docscribe::Plugin::Registry.register}.
|
|
8
|
+
# Each entry is expanded relative to {#config_root} (the directory holding
|
|
9
|
+
# `docscribe.yml`) and passed to `require`. Registration is expected to
|
|
10
|
+
# happen inside the required file via {Docscribe::Plugin::Registry.register}.
|
|
11
11
|
#
|
|
12
12
|
# Loading failures are non-fatal: a warning is printed and the run
|
|
13
13
|
# continues without the plugin.
|
|
@@ -21,7 +21,7 @@ module Docscribe
|
|
|
21
21
|
require 'docscribe/plugin'
|
|
22
22
|
|
|
23
23
|
paths.each do |path|
|
|
24
|
-
require
|
|
24
|
+
require resolve_path(path)
|
|
25
25
|
rescue LoadError => e
|
|
26
26
|
warn "Docscribe: could not load plugin #{path.inspect}: #{e.message}"
|
|
27
27
|
end
|
data/lib/docscribe/config/rbs.rb
CHANGED
|
@@ -66,12 +66,10 @@ module Docscribe
|
|
|
66
66
|
# @return [nil] if LoadError
|
|
67
67
|
def build_rbs_provider
|
|
68
68
|
require 'docscribe/types/rbs/provider'
|
|
69
|
-
Docscribe::Types::RBS::Provider.new(
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
collapse_object_generics: rbs_collapse_object_generics?
|
|
74
|
-
)
|
|
69
|
+
Docscribe::Types::RBS::Provider.new(sig_dirs: rbs_sig_dirs, collection_dirs: rbs_collection_dirs,
|
|
70
|
+
collapse_generics: rbs_collapse_generics?,
|
|
71
|
+
collapse_object_generics: rbs_collapse_object_generics?,
|
|
72
|
+
config_root: config_root)
|
|
75
73
|
rescue LoadError
|
|
76
74
|
warn 'Docscribe: --rbs requires the `rbs` gem. Add `gem "rbs"` to your Gemfile and run `bundle install`.'
|
|
77
75
|
nil
|
|
@@ -85,20 +83,19 @@ module Docscribe
|
|
|
85
83
|
# @return [nil] if LoadError
|
|
86
84
|
def build_core_rbs_provider
|
|
87
85
|
require 'docscribe/types/rbs/provider'
|
|
88
|
-
Docscribe::Types::RBS::Provider.new(
|
|
89
|
-
sig_dirs: [],
|
|
90
|
-
collapse_generics: false
|
|
91
|
-
)
|
|
86
|
+
Docscribe::Types::RBS::Provider.new(sig_dirs: [], collapse_generics: false, config_root: config_root)
|
|
92
87
|
rescue LoadError
|
|
93
88
|
nil
|
|
94
89
|
end
|
|
95
90
|
|
|
96
91
|
# Signature directories used by the RBS provider.
|
|
97
92
|
#
|
|
93
|
+
# Relative entries resolve against {#config_root}, not `Dir.pwd`.
|
|
94
|
+
#
|
|
98
95
|
# @private
|
|
99
96
|
# @return [Array<String>]
|
|
100
97
|
def rbs_sig_dirs
|
|
101
|
-
Array(raw.dig('rbs', 'sig_dirs') || DEFAULT.dig('rbs', 'sig_dirs')).map(
|
|
98
|
+
Array(raw.dig('rbs', 'sig_dirs') || DEFAULT.dig('rbs', 'sig_dirs')).map { |dir| resolve_path(dir.to_s) } # steep:ignore
|
|
102
99
|
end
|
|
103
100
|
|
|
104
101
|
# RBS collection directories (auto-discovered from rbs_collection.lock.yaml).
|
|
@@ -107,10 +104,31 @@ module Docscribe
|
|
|
107
104
|
# RBS environment errors (e.g. duplicate declarations against core
|
|
108
105
|
# stdlib types) do not silence all RBS lookups.
|
|
109
106
|
#
|
|
107
|
+
# When no explicit dirs are configured but `rbs.collection: true` is
|
|
108
|
+
# set, the lock file is auto-discovered (same as `--rbs-collection`),
|
|
109
|
+
# so plain `check` gets the full environment without extra flags.
|
|
110
|
+
#
|
|
110
111
|
# @private
|
|
111
112
|
# @return [Array<String>]
|
|
112
113
|
def rbs_collection_dirs
|
|
113
|
-
Array(raw.dig('rbs', 'collection_dirs')).map(
|
|
114
|
+
explicit = Array(raw.dig('rbs', 'collection_dirs')).map { |dir| resolve_path(dir.to_s) } # steep:ignore
|
|
115
|
+
return explicit unless explicit.empty?
|
|
116
|
+
return [] unless raw.dig('rbs', 'collection')
|
|
117
|
+
|
|
118
|
+
Array(discovered_collection_dir).compact
|
|
119
|
+
end
|
|
120
|
+
|
|
121
|
+
# Resolve the collection directory from rbs_collection.lock.yaml.
|
|
122
|
+
#
|
|
123
|
+
# @private
|
|
124
|
+
# @raise [LoadError]
|
|
125
|
+
# @return [String, nil] resolved directory or nil when no lock file
|
|
126
|
+
# @return [nil] if LoadError
|
|
127
|
+
def discovered_collection_dir
|
|
128
|
+
require 'docscribe/types/rbs/collection_loader'
|
|
129
|
+
Docscribe::Types::RBS::CollectionLoader.resolve(root: config_root)
|
|
130
|
+
rescue LoadError
|
|
131
|
+
nil
|
|
114
132
|
end
|
|
115
133
|
|
|
116
134
|
# Whether generic RBS types should be collapsed to simpler container names.
|
|
@@ -92,9 +92,11 @@ module Docscribe
|
|
|
92
92
|
|
|
93
93
|
# RBI directories searched by the Sorbet provider.
|
|
94
94
|
#
|
|
95
|
+
# Relative entries resolve against {#config_root}, not `Dir.pwd`.
|
|
96
|
+
#
|
|
95
97
|
# @return [Array<String>]
|
|
96
98
|
def sorbet_rbi_dirs
|
|
97
|
-
Array(raw.dig('sorbet', 'rbi_dirs') || DEFAULT.dig('sorbet', 'rbi_dirs')).map(
|
|
99
|
+
Array(raw.dig('sorbet', 'rbi_dirs') || DEFAULT.dig('sorbet', 'rbi_dirs')).map { |dir| resolve_path(dir.to_s) } # steep:ignore
|
|
98
100
|
end
|
|
99
101
|
|
|
100
102
|
# Whether generic Sorbet/RBI container types should be simplified.
|
|
@@ -106,6 +106,12 @@ module Docscribe
|
|
|
106
106
|
# Skip @param for anonymous block arguments (&) (Ruby 3.2+)
|
|
107
107
|
skip_anonymous_block_params: false
|
|
108
108
|
|
|
109
|
+
# Validate YARD types against inferred/RBS types
|
|
110
|
+
validate_types: true
|
|
111
|
+
|
|
112
|
+
# Report syntactically broken YARD types (e.g. [Sym bol])
|
|
113
|
+
warn_invalid_yard: true
|
|
114
|
+
|
|
109
115
|
plugins:
|
|
110
116
|
# Load custom plugins
|
|
111
117
|
# Example:
|
|
@@ -82,6 +82,21 @@ module Docscribe
|
|
|
82
82
|
end
|
|
83
83
|
end
|
|
84
84
|
|
|
85
|
+
# Recursively convert hash keys to strings.
|
|
86
|
+
#
|
|
87
|
+
# `Config.new` receives overrides as Ruby keyword arguments (symbol keys)
|
|
88
|
+
# while the defaults and every reader use string keys, so mixed hashes would
|
|
89
|
+
# silently keep the default value instead of the override.
|
|
90
|
+
#
|
|
91
|
+
# @private
|
|
92
|
+
# @param [Hash<Object, Object>] hash the hash to normalize
|
|
93
|
+
# @return [Hash<String, Object>]
|
|
94
|
+
def stringify_keys(hash)
|
|
95
|
+
hash.each_with_object({}) do |(key, value), out|
|
|
96
|
+
out[key.to_s] = value.is_a?(Hash) ? stringify_keys(value) : value
|
|
97
|
+
end
|
|
98
|
+
end
|
|
99
|
+
|
|
85
100
|
# Deep-merge two hashes, preferring values from the second hash.
|
|
86
101
|
#
|
|
87
102
|
# Nested hashes are merged recursively; non-hash values are replaced.
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module Docscribe
|
|
4
|
+
# Validation-related configuration.
|
|
5
|
+
class Config
|
|
6
|
+
# Whether to validate YARD types against inferred / external types.
|
|
7
|
+
#
|
|
8
|
+
# When enabled, each `@param`/`@return` type written in YARD is compared
|
|
9
|
+
# against the type inferred from the method body or provided via RBS/Sorbet.
|
|
10
|
+
# Mismatches are reported as `updated_param` / `updated_return` and, in
|
|
11
|
+
# check mode, cause exit 1.
|
|
12
|
+
#
|
|
13
|
+
# Enabled by default; pass `--no-validate-types` or set
|
|
14
|
+
# `validate_types: false` in `docscribe.yml` to silence it.
|
|
15
|
+
#
|
|
16
|
+
# @return [Boolean]
|
|
17
|
+
def validate_types?
|
|
18
|
+
fetch_bool(%w[validate_types], true)
|
|
19
|
+
end
|
|
20
|
+
|
|
21
|
+
# Whether to report syntactically broken YARD types.
|
|
22
|
+
#
|
|
23
|
+
# Independent of {#validate_types?}: syntax validity is a property of the
|
|
24
|
+
# YARD type string itself, not a comparison against inferred or external
|
|
25
|
+
# types. Enabled by default so a broken `[Sym bol]` is still surfaced (and
|
|
26
|
+
# safely fixed) on plain runs; set `warn_invalid_yard: false` or pass
|
|
27
|
+
# `--no-warn-invalid-yard` to silence it.
|
|
28
|
+
#
|
|
29
|
+
# @return [Boolean]
|
|
30
|
+
def warn_invalid_yard?
|
|
31
|
+
fetch_bool(%w[warn_invalid_yard], true)
|
|
32
|
+
end
|
|
33
|
+
end
|
|
34
|
+
end
|
data/lib/docscribe/config.rb
CHANGED
|
@@ -23,10 +23,43 @@ module Docscribe
|
|
|
23
23
|
# @param [Hash<String, Object>] raw user-provided config hash
|
|
24
24
|
# @return [void]
|
|
25
25
|
def initialize(config_path: nil, **raw)
|
|
26
|
-
@raw = deep_merge(DEFAULT, raw)
|
|
26
|
+
@raw = deep_merge(DEFAULT, stringify_keys(raw))
|
|
27
27
|
@config_path = config_path
|
|
28
28
|
end
|
|
29
29
|
|
|
30
|
+
# Resolve a config-relative path against the config root.
|
|
31
|
+
#
|
|
32
|
+
# Absolute paths are returned unchanged without touching the filesystem;
|
|
33
|
+
# relative paths are expanded from the config root rather than the process
|
|
34
|
+
# working directory.
|
|
35
|
+
#
|
|
36
|
+
# @param [String] path path as written in the config file or CLI
|
|
37
|
+
# @return [String] absolute path
|
|
38
|
+
def resolve_path(path)
|
|
39
|
+
absolute = Pathname.new(path.to_s).absolute?
|
|
40
|
+
return path.to_s if absolute
|
|
41
|
+
|
|
42
|
+
File.expand_path(path.to_s, config_root)
|
|
43
|
+
end
|
|
44
|
+
|
|
45
|
+
# Directory that relative paths in the config file resolve against.
|
|
46
|
+
#
|
|
47
|
+
# This is the directory containing `docscribe.yml`, so `sig_dirs`,
|
|
48
|
+
# `rbi_dirs`, `plugins.require` and the RBS collection lock file resolve the
|
|
49
|
+
# same whether Docscribe runs from the project root or from a subdirectory.
|
|
50
|
+
# Without a config file it falls back to the current working directory.
|
|
51
|
+
#
|
|
52
|
+
# @raise [Docscribe::Error] when the config directory no longer exists
|
|
53
|
+
# @return [String] absolute path to the config root
|
|
54
|
+
def config_root
|
|
55
|
+
return File.expand_path(Dir.pwd) unless config_path
|
|
56
|
+
|
|
57
|
+
root = File.expand_path(File.dirname(config_path))
|
|
58
|
+
return root if File.directory?(root)
|
|
59
|
+
|
|
60
|
+
raise Docscribe::Error, "Docscribe: config directory not found for #{config_path.inspect} (resolved #{root})"
|
|
61
|
+
end
|
|
62
|
+
|
|
30
63
|
# @return [Object]
|
|
31
64
|
def to_h
|
|
32
65
|
hash = {} #: Hash[String, Object]
|
|
@@ -49,3 +82,4 @@ require_relative 'config/rbs'
|
|
|
49
82
|
require_relative 'config/sorting'
|
|
50
83
|
require_relative 'config/sorbet'
|
|
51
84
|
require_relative 'config/plugin'
|
|
85
|
+
require_relative 'config/validation'
|
|
@@ -8,9 +8,9 @@ module Docscribe
|
|
|
8
8
|
insert update_all delete_all].freeze
|
|
9
9
|
|
|
10
10
|
class << self
|
|
11
|
-
# @param [
|
|
12
|
-
# @param [
|
|
13
|
-
# @return [Hash<Symbol,
|
|
11
|
+
# @param [Parser::AST::Node, nil] body
|
|
12
|
+
# @param [Symbol?] method_name
|
|
13
|
+
# @return [Hash<Symbol, Boolean, String, nil>]
|
|
14
14
|
def analyze(body, method_name)
|
|
15
15
|
result = default_result(method_name)
|
|
16
16
|
|
|
@@ -20,8 +20,8 @@ module Docscribe
|
|
|
20
20
|
result
|
|
21
21
|
end
|
|
22
22
|
|
|
23
|
-
# @param [
|
|
24
|
-
# @return [Hash<Symbol,
|
|
23
|
+
# @param [Symbol?] method_name
|
|
24
|
+
# @return [Hash<Symbol, Boolean, String, nil>]
|
|
25
25
|
def default_result(method_name)
|
|
26
26
|
{
|
|
27
27
|
predicate: method_name&.to_s&.end_with?('?') || false,
|
|
@@ -33,8 +33,8 @@ module Docscribe
|
|
|
33
33
|
}
|
|
34
34
|
end
|
|
35
35
|
|
|
36
|
-
# @param [Hash<Symbol,
|
|
37
|
-
# @param [
|
|
36
|
+
# @param [Hash<Symbol, Boolean, String, nil>] analysis
|
|
37
|
+
# @param [Symbol?] _method_name
|
|
38
38
|
# @return [String?]
|
|
39
39
|
def infer_description(analysis, _method_name)
|
|
40
40
|
return nil unless analysis[:has_side_effects] || analysis[:predicate]
|
|
@@ -51,8 +51,8 @@ module Docscribe
|
|
|
51
51
|
private
|
|
52
52
|
|
|
53
53
|
# @private
|
|
54
|
-
# @param [
|
|
55
|
-
# @param [Hash<Symbol,
|
|
54
|
+
# @param [Parser::AST::Node] node
|
|
55
|
+
# @param [Hash<Symbol, Boolean, String, nil>] result
|
|
56
56
|
# @return [void]
|
|
57
57
|
def analyze_body(node, result)
|
|
58
58
|
case node.type
|
|
@@ -68,8 +68,8 @@ module Docscribe
|
|
|
68
68
|
end
|
|
69
69
|
|
|
70
70
|
# @private
|
|
71
|
-
# @param [
|
|
72
|
-
# @param [Hash<Symbol,
|
|
71
|
+
# @param [Parser::AST::Node] node
|
|
72
|
+
# @param [Hash<Symbol, Boolean, String, nil>] result
|
|
73
73
|
# @return [void]
|
|
74
74
|
def recurse_children(node, result)
|
|
75
75
|
node.children.each do |child|
|
|
@@ -78,8 +78,8 @@ module Docscribe
|
|
|
78
78
|
end
|
|
79
79
|
|
|
80
80
|
# @private
|
|
81
|
-
# @param [
|
|
82
|
-
# @param [Hash<Symbol,
|
|
81
|
+
# @param [Parser::AST::Node] node
|
|
82
|
+
# @param [Hash<Symbol, Boolean, String, nil>] result
|
|
83
83
|
# @return [void]
|
|
84
84
|
def analyze_send(node, result)
|
|
85
85
|
_receiver, method_name = *node
|
|
@@ -33,8 +33,8 @@ module Docscribe
|
|
|
33
33
|
# @return [String, nil]
|
|
34
34
|
def prefix_param_type(name)
|
|
35
35
|
return 'Array' if name.start_with?('*') && !name.start_with?('**')
|
|
36
|
-
return 'Hash'
|
|
37
|
-
return 'Proc'
|
|
36
|
+
return 'Hash' if name.start_with?('**')
|
|
37
|
+
return 'Proc' if name.start_with?('&')
|
|
38
38
|
|
|
39
39
|
nil
|
|
40
40
|
end
|
|
@@ -23,10 +23,9 @@ module Docscribe
|
|
|
23
23
|
raises = [] #: Array[String]
|
|
24
24
|
|
|
25
25
|
ASTWalk.walk(node) do |n|
|
|
26
|
-
|
|
27
|
-
when :resbody
|
|
26
|
+
if n&.type == :resbody
|
|
28
27
|
raises.concat(exception_names_from_rescue_list(n.children[0]))
|
|
29
|
-
|
|
28
|
+
elsif n&.type == :send
|
|
30
29
|
collect_send_raise(raises, n)
|
|
31
30
|
end
|
|
32
31
|
end
|
|
@@ -45,9 +44,9 @@ module Docscribe
|
|
|
45
44
|
# @param [Parser::AST::Node, nil] exc_list rescue exception list node
|
|
46
45
|
# @return [Array<String>]
|
|
47
46
|
def exception_names_from_rescue_list(exc_list)
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
47
|
+
return [DEFAULT_ERROR] unless exc_list.is_a?(Parser::AST::Node)
|
|
48
|
+
|
|
49
|
+
if exc_list.type == :array
|
|
51
50
|
exc_list.children.map { |e| Names.const_full_name(e) || DEFAULT_ERROR }
|
|
52
51
|
else
|
|
53
52
|
[Names.const_full_name(exc_list) || DEFAULT_ERROR]
|