docscribe 1.6.2 → 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 +347 -23
- data/lib/docscribe/cli/config_builder.rb +34 -8
- data/lib/docscribe/cli/config_dump.rb +88 -7
- data/lib/docscribe/cli/options.rb +20 -1
- data/lib/docscribe/cli/run.rb +193 -31
- data/lib/docscribe/config/defaults.rb +2 -1
- data/lib/docscribe/config/plugin.rb +4 -4
- data/lib/docscribe/config/rbs.rb +10 -13
- data/lib/docscribe/config/sorbet.rb +3 -1
- data/lib/docscribe/config/template.rb +4 -1
- data/lib/docscribe/config/utils.rb +15 -0
- data/lib/docscribe/config/validation.rb +18 -3
- data/lib/docscribe/config.rb +34 -1
- data/lib/docscribe/infer/returns.rb +46 -16
- data/lib/docscribe/inline_rewriter/doc_builder.rb +69 -3
- data/lib/docscribe/inline_rewriter.rb +104 -1
- data/lib/docscribe/server/base.rb +37 -16
- data/lib/docscribe/server/daemon.rb +10 -1
- data/lib/docscribe/types/rbs/provider.rb +5 -2
- data/lib/docscribe/types/sorbet/base_provider.rb +1 -1
- data/lib/docscribe/types/yard/parser.rb +9 -4
- data/lib/docscribe/types/yard/repair.rb +142 -0
- data/lib/docscribe/version.rb +1 -1
- metadata +4 -3
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]
|
|
@@ -1184,21 +1184,6 @@ module Docscribe
|
|
|
1184
1184
|
extract_array_elem_strict(recv_type) || enumerator_object_elem(recv_type)
|
|
1185
1185
|
end
|
|
1186
1186
|
|
|
1187
|
-
# @note module_function: defines #enumerator_recv_type (visibility: private)
|
|
1188
|
-
# @param [Parser::AST::Node, nil] recv
|
|
1189
|
-
# @param [Hash] opts
|
|
1190
|
-
# @return [String, nil]
|
|
1191
|
-
def enumerator_recv_type(recv, **opts)
|
|
1192
|
-
receiver_rbs_type_name(recv, opts[:core_rbs_provider], opts[:local_var_types],
|
|
1193
|
-
opts[:param_types]) ||
|
|
1194
|
-
run_last_expr_type(recv, fallback_type: nil, nil_as_optional: false,
|
|
1195
|
-
local_var_types: opts[:local_var_types],
|
|
1196
|
-
param_types: opts[:param_types],
|
|
1197
|
-
core_rbs_provider: opts[:core_rbs_provider],
|
|
1198
|
-
signature_provider: opts[:signature_provider],
|
|
1199
|
-
container: opts[:container])
|
|
1200
|
-
end
|
|
1201
|
-
|
|
1202
1187
|
# @note module_function: defines #extract_array_elem_strict (visibility: private)
|
|
1203
1188
|
# @param [String] type_str
|
|
1204
1189
|
# @return [String, nil]
|
|
@@ -1227,10 +1212,42 @@ module Docscribe
|
|
|
1227
1212
|
return unless meth == :to_h && recv && recv.type == :send && recv.children[1] == :each_with_index
|
|
1228
1213
|
|
|
1229
1214
|
inner_recv = recv.children[0]
|
|
1215
|
+
# `hash.each_with_index.to_h` rebuilds the same hash, so keep K and V.
|
|
1216
|
+
rebuilt = hash_rebuild_type(inner_recv, **opts)
|
|
1217
|
+
return rebuilt if rebuilt
|
|
1218
|
+
|
|
1230
1219
|
elem = hash_elem_from_enumerator(inner_recv, **opts) || 'Object'
|
|
1231
1220
|
"Hash<#{elem}, Integer>"
|
|
1232
1221
|
end
|
|
1233
1222
|
|
|
1223
|
+
# The rebuilt hash type when `each_with_index` runs over a `Hash`.
|
|
1224
|
+
#
|
|
1225
|
+
# @note module_function: defines #hash_rebuild_type (visibility: private)
|
|
1226
|
+
# @param [Parser::AST::Node, nil] inner_recv the `each_with_index` receiver
|
|
1227
|
+
# @param [Hash] opts
|
|
1228
|
+
# @return [String, nil]
|
|
1229
|
+
def hash_rebuild_type(inner_recv, **opts)
|
|
1230
|
+
source_type = enumerator_recv_type(inner_recv, **opts)
|
|
1231
|
+
return nil unless source_type&.start_with?('Hash<')
|
|
1232
|
+
|
|
1233
|
+
source_type
|
|
1234
|
+
end
|
|
1235
|
+
|
|
1236
|
+
# @note module_function: defines #enumerator_recv_type (visibility: private)
|
|
1237
|
+
# @param [Parser::AST::Node, nil] recv
|
|
1238
|
+
# @param [Hash] opts
|
|
1239
|
+
# @return [String, nil]
|
|
1240
|
+
def enumerator_recv_type(recv, **opts)
|
|
1241
|
+
receiver_rbs_type_name(recv, opts[:core_rbs_provider], opts[:local_var_types],
|
|
1242
|
+
opts[:param_types]) ||
|
|
1243
|
+
run_last_expr_type(recv, fallback_type: nil, nil_as_optional: false,
|
|
1244
|
+
local_var_types: opts[:local_var_types],
|
|
1245
|
+
param_types: opts[:param_types],
|
|
1246
|
+
core_rbs_provider: opts[:core_rbs_provider],
|
|
1247
|
+
signature_provider: opts[:signature_provider],
|
|
1248
|
+
container: opts[:container])
|
|
1249
|
+
end
|
|
1250
|
+
|
|
1234
1251
|
# @note module_function: defines #hash_elem_from_enumerator (visibility: private)
|
|
1235
1252
|
# @param [Parser::AST::Node, nil] inner_recv
|
|
1236
1253
|
# @param [Hash] opts
|
|
@@ -2289,7 +2306,20 @@ module Docscribe
|
|
|
2289
2306
|
|
|
2290
2307
|
new_rbs = rbs.dup
|
|
2291
2308
|
mapping.each { |var, val| new_rbs = new_rbs.gsub(/\b#{Regexp.escape(var)}\b/, val) }
|
|
2292
|
-
new_rbs
|
|
2309
|
+
new_rbs = new_rbs.gsub(/\bself\b/, recv_type) if new_rbs.include?('self')
|
|
2310
|
+
resolve_free_variables(new_rbs)
|
|
2311
|
+
end
|
|
2312
|
+
|
|
2313
|
+
# Replace type variables that stayed unsubstituted with `Object`.
|
|
2314
|
+
#
|
|
2315
|
+
# A remaining single-letter placeholder (`U`, `T`, `Elem`) means the block
|
|
2316
|
+
# or argument that binds it was not analyzed, so no concrete type is known.
|
|
2317
|
+
#
|
|
2318
|
+
# @note module_function: defines #resolve_free_variables (visibility: private)
|
|
2319
|
+
# @param [String] type_str
|
|
2320
|
+
# @return [String]
|
|
2321
|
+
def resolve_free_variables(type_str)
|
|
2322
|
+
type_str.gsub(/\b(?:Elem|E|T|U)\b/, 'Object')
|
|
2293
2323
|
end
|
|
2294
2324
|
|
|
2295
2325
|
# Extract the inner generic args string from a receiver type like `Array<String>` or `Hash<Integer, String>`.
|
|
@@ -4,6 +4,7 @@ require 'docscribe/plugin'
|
|
|
4
4
|
require 'docscribe/infer'
|
|
5
5
|
require 'docscribe/inline_rewriter/source_helpers'
|
|
6
6
|
require 'docscribe/types/yard/validator'
|
|
7
|
+
require 'docscribe/types/yard/repair'
|
|
7
8
|
require 'docscribe/validator/type_mismatch_validator'
|
|
8
9
|
require 'docscribe/validator/generic_compatibility'
|
|
9
10
|
|
|
@@ -1101,13 +1102,20 @@ module Docscribe
|
|
|
1101
1102
|
# @return [void]
|
|
1102
1103
|
def handle_existing_param(pname, param_line, lines, reasons, ctx)
|
|
1103
1104
|
yard_type = ctx[:info][:param_types][pname]
|
|
1104
|
-
if invalid_yard_type?(yard_type)
|
|
1105
|
+
if warn_invalid_yard_check?(ctx) && invalid_yard_type?(yard_type)
|
|
1105
1106
|
handle_invalid_param(pname, param_line, yard_type, lines, reasons)
|
|
1106
1107
|
elsif param_needs_update?(ctx)
|
|
1107
1108
|
collect_updated_param(param_line, pname, lines, reasons, ctx)
|
|
1108
1109
|
end
|
|
1109
1110
|
end
|
|
1110
1111
|
|
|
1112
|
+
# Emit an `@param` line, repairing the type when a safe repair exists.
|
|
1113
|
+
#
|
|
1114
|
+
# A broken type such as `[Sym bol]` is rewritten to `[Symbol]` instead
|
|
1115
|
+
# of being passed through untouched, so the doc is fixed rather than
|
|
1116
|
+
# merely reported. When no repair can be proven, the original line is
|
|
1117
|
+
# kept and the offense is reported for a human to resolve.
|
|
1118
|
+
#
|
|
1111
1119
|
# @note module_function: defines #handle_invalid_param (visibility: private)
|
|
1112
1120
|
# @param [String] pname
|
|
1113
1121
|
# @param [String] param_line
|
|
@@ -1115,7 +1123,20 @@ module Docscribe
|
|
|
1115
1123
|
# @param [Array<String>] lines
|
|
1116
1124
|
# @param [Array<Hash<Symbol, Object>>] reasons
|
|
1117
1125
|
# @return [void]
|
|
1118
|
-
def handle_invalid_param(pname, param_line, yard_type, lines, reasons)
|
|
1126
|
+
def handle_invalid_param(pname, param_line, yard_type, lines, reasons) # rubocop:disable Metrics/MethodLength
|
|
1127
|
+
repaired = Docscribe::Types::Yard::Repair.repair(yard_type)
|
|
1128
|
+
|
|
1129
|
+
if repaired
|
|
1130
|
+
lines << "#{replace_param_type(param_line, repaired)}\n"
|
|
1131
|
+
reasons << {
|
|
1132
|
+
type: :invalid_type,
|
|
1133
|
+
message: "invalid YARD type [#{yard_type}] for @param #{pname} (repaired to [#{repaired}])",
|
|
1134
|
+
source: 'syntax',
|
|
1135
|
+
extra: { param: pname, repaired_type: repaired }
|
|
1136
|
+
}
|
|
1137
|
+
return
|
|
1138
|
+
end
|
|
1139
|
+
|
|
1119
1140
|
lines << "#{param_line}\n"
|
|
1120
1141
|
reasons << {
|
|
1121
1142
|
type: :invalid_type,
|
|
@@ -1125,6 +1146,20 @@ module Docscribe
|
|
|
1125
1146
|
}
|
|
1126
1147
|
end
|
|
1127
1148
|
|
|
1149
|
+
# Replace the bracketed type in an `@param` line.
|
|
1150
|
+
#
|
|
1151
|
+
# `param_line` reaches here already rebuilt from the AST, so it no
|
|
1152
|
+
# longer carries the original broken type text; the replacement is done
|
|
1153
|
+
# on whatever bracket content is present.
|
|
1154
|
+
#
|
|
1155
|
+
# @note module_function: defines #replace_param_type (visibility: private)
|
|
1156
|
+
# @param [String] param_line
|
|
1157
|
+
# @param [String] new_type
|
|
1158
|
+
# @return [String]
|
|
1159
|
+
def replace_param_type(param_line, new_type)
|
|
1160
|
+
param_line.sub(/\[.*?\]/, "[#{new_type}]")
|
|
1161
|
+
end
|
|
1162
|
+
|
|
1128
1163
|
# @note module_function: defines #param_needs_update? (visibility: private)
|
|
1129
1164
|
# @param [Hash<Symbol, Object>] ctx
|
|
1130
1165
|
# @return [Boolean]
|
|
@@ -1137,17 +1172,34 @@ module Docscribe
|
|
|
1137
1172
|
# Called from both param (above) and return (below) validation, so no
|
|
1138
1173
|
# waterfall placement satisfies the ordering cop — exempt.
|
|
1139
1174
|
#
|
|
1175
|
+
# A blank type means "no type given" and is not an error here, but for
|
|
1176
|
+
# `@param [<literal>] name` the bracket content is the whole type, and a
|
|
1177
|
+
# bare literal (empty, `:sym`, `42`, `,`) carries no type information.
|
|
1178
|
+
#
|
|
1140
1179
|
# @note module_function: defines #invalid_yard_type? (visibility: private)
|
|
1141
1180
|
# @param [String?] type_str
|
|
1142
1181
|
# @return [Boolean]
|
|
1143
1182
|
def invalid_yard_type?(type_str) # rubocop:disable SortedMethodsByCall/Waterfall
|
|
1144
|
-
return false if type_str.nil?
|
|
1183
|
+
return false if type_str.nil?
|
|
1184
|
+
return true if literal_only_yard_type?(type_str)
|
|
1145
1185
|
return true if type_str.match?(/\d/)
|
|
1146
1186
|
return true if type_str.match?(/[^\x00-\x7F]/)
|
|
1147
1187
|
|
|
1148
1188
|
!Types::Yard::Validator.valid?(type_str)
|
|
1149
1189
|
end
|
|
1150
1190
|
|
|
1191
|
+
# Whether a YARD type string is a bare literal instead of a type name.
|
|
1192
|
+
#
|
|
1193
|
+
# @note module_function: defines #literal_only_yard_type? (visibility: private)
|
|
1194
|
+
# @param [String] type_str
|
|
1195
|
+
# @return [Boolean]
|
|
1196
|
+
def literal_only_yard_type?(type_str)
|
|
1197
|
+
stripped = type_str.strip
|
|
1198
|
+
return true if stripped.empty?
|
|
1199
|
+
|
|
1200
|
+
stripped.start_with?(':') || stripped.match?(/\A\d+\z/) || !stripped.match?(/\w/)
|
|
1201
|
+
end
|
|
1202
|
+
|
|
1151
1203
|
# Whether param validation should run via inferred/external types.
|
|
1152
1204
|
#
|
|
1153
1205
|
# @note module_function: defines #should_validate_param? (visibility: private)
|
|
@@ -2033,10 +2085,24 @@ module Docscribe
|
|
|
2033
2085
|
def invalid_yard_return?(ctx)
|
|
2034
2086
|
yard = ctx[:info][:return_type]
|
|
2035
2087
|
return false unless yard
|
|
2088
|
+
return false unless warn_invalid_yard_check?(ctx)
|
|
2036
2089
|
|
|
2037
2090
|
invalid_yard_type?(yard)
|
|
2038
2091
|
end
|
|
2039
2092
|
|
|
2093
|
+
# Whether syntactically broken YARD types should be reported.
|
|
2094
|
+
#
|
|
2095
|
+
# Gated by `warn_invalid_yard` (default true), not by `validate_types`:
|
|
2096
|
+
# syntax validity does not depend on inferred or external types. Both the
|
|
2097
|
+
# param branch and the return branch consult this first.
|
|
2098
|
+
#
|
|
2099
|
+
# @note module_function: defines #warn_invalid_yard_check? (visibility: private)
|
|
2100
|
+
# @param [Hash<Symbol, Object>] ctx
|
|
2101
|
+
# @return [Boolean]
|
|
2102
|
+
def warn_invalid_yard_check?(ctx)
|
|
2103
|
+
ctx[:config].respond_to?(:warn_invalid_yard?) && ctx[:config].warn_invalid_yard?
|
|
2104
|
+
end
|
|
2105
|
+
|
|
2040
2106
|
# Record invalid return type.
|
|
2041
2107
|
#
|
|
2042
2108
|
# @note module_function: defines #record_invalid_return (visibility: private)
|
|
@@ -791,7 +791,7 @@ module Docscribe
|
|
|
791
791
|
# @private
|
|
792
792
|
# @param [Hash] options kwargs with insertion, config, rewriter, buffer, strategy, changes, file, doc params
|
|
793
793
|
# @return [void]
|
|
794
|
-
def apply_method_insertion!(**options)
|
|
794
|
+
def apply_method_insertion!(**options) # rubocop:disable Metrics/AbcSize
|
|
795
795
|
insertion = options[:insertion]
|
|
796
796
|
config = options[:config]
|
|
797
797
|
return unless method_insertion_allowed?(insertion, config)
|
|
@@ -799,6 +799,7 @@ module Docscribe
|
|
|
799
799
|
anchor_bol_range, = method_bol_ranges(options[:buffer], insertion)
|
|
800
800
|
params = build_method_insertion_params(insertion, config, options[:signature_provider],
|
|
801
801
|
options[:core_rbs_provider], options[:method_override])
|
|
802
|
+
seed_declared_param_types!(options[:buffer], insertion, params, config, options[:strategy])
|
|
802
803
|
extract_existing_descriptions!(options[:buffer], insertion, params, options[:strategy], config)
|
|
803
804
|
doc = DocBuilder.build(insertion, **params) # steep:ignore
|
|
804
805
|
dispatch_method_insertion_by_strategy!(anchor_bol_range, options, params, doc)
|
|
@@ -937,6 +938,108 @@ module Docscribe
|
|
|
937
938
|
DocBuilder.build_param_types_from_node(insertion.node, external_sig: external_sig, config: config)
|
|
938
939
|
end
|
|
939
940
|
|
|
941
|
+
# Fill param types from `@param` tags already present in the source.
|
|
942
|
+
#
|
|
943
|
+
# A declared `@param` is only a fallback: it is a human comment and may lie,
|
|
944
|
+
# so it applies solely where inference left `Object`/`untyped`. Without it a
|
|
945
|
+
# param like `tag_order` stays `Object`, collapsing
|
|
946
|
+
# `map { |t| t.strip }.each_with_index.to_h` to `Hash<Object, ...>`.
|
|
947
|
+
#
|
|
948
|
+
# Safe mode only: aggressive mode deliberately re-infers param types over
|
|
949
|
+
# declared ones, and `validate_types` needs the declared type kept separate
|
|
950
|
+
# so it can report a mismatch.
|
|
951
|
+
#
|
|
952
|
+
# @private
|
|
953
|
+
# @param [Parser::Source::Buffer] buffer the source buffer
|
|
954
|
+
# @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion
|
|
955
|
+
# @param [Hash<Symbol, Object>] params insertion params
|
|
956
|
+
# @param [Docscribe::Config] config the active configuration
|
|
957
|
+
# @param [Symbol] strategy :safe or :aggressive rewrite mode
|
|
958
|
+
# @return [void]
|
|
959
|
+
def seed_declared_param_types!(buffer, insertion, params, config, strategy) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
|
|
960
|
+
return if strategy == :aggressive || config.validate_types?
|
|
961
|
+
|
|
962
|
+
declared = DocBuilder.parse_existing_doc_tags(
|
|
963
|
+
method_doc_comment_info(buffer, insertion)&.dig(:doc_lines) || []
|
|
964
|
+
)[:param_types]
|
|
965
|
+
|
|
966
|
+
# Invalid YARD types must reach the invalid-type fixer untouched.
|
|
967
|
+
declared = (declared || {}).select { |_name, type| valid_yard_type?(type) }
|
|
968
|
+
return if declared.empty?
|
|
969
|
+
|
|
970
|
+
current = params[:param_types] || {}
|
|
971
|
+
params[:param_types] = current.merge(declared) { |_name, inferred, decl| merge_param_type(inferred, decl) }
|
|
972
|
+
end
|
|
973
|
+
|
|
974
|
+
# Combine an inferred param type with a declared `@param` type.
|
|
975
|
+
#
|
|
976
|
+
# The declared type fills gaps and adds generic detail (`Array` ->
|
|
977
|
+
# `Array<String>`), but the AST wins a real conflict because it reflects
|
|
978
|
+
# what the code does, while a `@param` tag is a human comment that can lie.
|
|
979
|
+
#
|
|
980
|
+
# @private
|
|
981
|
+
# @param [String, nil] inferred type derived from the AST
|
|
982
|
+
# @param [String] declared type from the `@param` tag
|
|
983
|
+
# @return [String, nil]
|
|
984
|
+
def merge_param_type(inferred, declared)
|
|
985
|
+
return declared if inferred.nil? || unknown_type?(inferred)
|
|
986
|
+
return inferred if unknown_type?(declared)
|
|
987
|
+
return inferred unless same_base_type?(inferred, declared)
|
|
988
|
+
|
|
989
|
+
type_arity(declared) > type_arity(inferred) ? declared : inferred
|
|
990
|
+
end
|
|
991
|
+
|
|
992
|
+
# Whether two types name the same base type, ignoring generic arguments.
|
|
993
|
+
#
|
|
994
|
+
# @private
|
|
995
|
+
# @param [String] left first type
|
|
996
|
+
# @param [String] right second type
|
|
997
|
+
# @return [Boolean]
|
|
998
|
+
def same_base_type?(left, right)
|
|
999
|
+
base_type_name(left) == base_type_name(right)
|
|
1000
|
+
end
|
|
1001
|
+
|
|
1002
|
+
# Number of generic arguments carried by a type.
|
|
1003
|
+
#
|
|
1004
|
+
# @private
|
|
1005
|
+
# @param [String] type type string
|
|
1006
|
+
# @return [Integer]
|
|
1007
|
+
def type_arity(type)
|
|
1008
|
+
base_type_name(type) == type.to_s.strip ? 0 : 1
|
|
1009
|
+
end
|
|
1010
|
+
|
|
1011
|
+
# Base name of a type, with any generic arguments stripped.
|
|
1012
|
+
#
|
|
1013
|
+
# @private
|
|
1014
|
+
# @param [String] type type string
|
|
1015
|
+
# @return [String]
|
|
1016
|
+
def base_type_name(type)
|
|
1017
|
+
type.to_s.split('<', 2).first.to_s.strip
|
|
1018
|
+
end
|
|
1019
|
+
|
|
1020
|
+
# Whether a param type carries no usable information.
|
|
1021
|
+
#
|
|
1022
|
+
# @private
|
|
1023
|
+
# @param [String, nil] type param type string
|
|
1024
|
+
# @return [Boolean]
|
|
1025
|
+
def unknown_type?(type)
|
|
1026
|
+
type.nil? || %w[Object untyped nil].include?(type)
|
|
1027
|
+
end
|
|
1028
|
+
|
|
1029
|
+
# Whether a declared `@param` type is valid YARD and safe to reuse for inference.
|
|
1030
|
+
#
|
|
1031
|
+
# @private
|
|
1032
|
+
# @param [String, nil] type declared YARD type string
|
|
1033
|
+
# @raise [StandardError] when the YARD type validator fails on odd syntax
|
|
1034
|
+
# @return [Boolean]
|
|
1035
|
+
def valid_yard_type?(type)
|
|
1036
|
+
return false if type.nil? || type.strip.empty?
|
|
1037
|
+
|
|
1038
|
+
Docscribe::Types::Yard::Validator.valid?(type)
|
|
1039
|
+
rescue StandardError
|
|
1040
|
+
false
|
|
1041
|
+
end
|
|
1042
|
+
|
|
940
1043
|
# Apply method insertion aggressive
|
|
941
1044
|
#
|
|
942
1045
|
# @private
|
|
@@ -31,7 +31,7 @@ module Docscribe
|
|
|
31
31
|
# @param [Boolean] daemonize redirect stdin/stdout/stderr to /dev/null
|
|
32
32
|
# @param [Integer] timeout max seconds to wait for readiness
|
|
33
33
|
# @return [void]
|
|
34
|
-
def ensure_running!(config_path: nil, daemonize: false, timeout:
|
|
34
|
+
def ensure_running!(config_path: nil, daemonize: false, timeout: 15)
|
|
35
35
|
return if running?(config_path)
|
|
36
36
|
|
|
37
37
|
check_platform_support!
|
|
@@ -53,7 +53,7 @@ module Docscribe
|
|
|
53
53
|
# @param [Boolean] raise_on_timeout
|
|
54
54
|
# @raise [StandardError]
|
|
55
55
|
# @return [Boolean]
|
|
56
|
-
def wait_for_ready(config_path: nil, timeout:
|
|
56
|
+
def wait_for_ready(config_path: nil, timeout: 15, raise_on_timeout: true) # rubocop:disable SortedMethodsByCall/Waterfall
|
|
57
57
|
deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
|
|
58
58
|
loop do
|
|
59
59
|
return true if running?(config_path)
|
|
@@ -177,15 +177,17 @@ module Docscribe
|
|
|
177
177
|
# Uses MD5 (deterministic across processes) instead of String#hash
|
|
178
178
|
# (which varies per Ruby process due to random seeding).
|
|
179
179
|
# When a config_path is given, its path + mtime are included in the hash
|
|
180
|
-
# so different configs get different daemons
|
|
180
|
+
# so different configs get different daemons, and the config's directory
|
|
181
|
+
# replaces the working directory as the project root.
|
|
181
182
|
# Environment files (Gemfile.lock, rbs_collection.lock.yaml) are also
|
|
182
183
|
# included so daemon is invalidated when gems or RBS types change.
|
|
183
184
|
#
|
|
184
185
|
# @param [String?] config_path optional config path to differentiate
|
|
185
186
|
# @return [String]
|
|
186
187
|
def socket_path(config_path = nil)
|
|
187
|
-
|
|
188
|
-
seed
|
|
188
|
+
root = project_root(config_path)
|
|
189
|
+
seed = +root
|
|
190
|
+
seed << ":#{env_hash(root)}"
|
|
189
191
|
if config_path
|
|
190
192
|
resolved = File.expand_path(config_path)
|
|
191
193
|
mtime = File.exist?(resolved) ? File.mtime(resolved).to_f : 0.0
|
|
@@ -194,46 +196,65 @@ module Docscribe
|
|
|
194
196
|
"#{SOCKET_DIR}/docscribe-#{Digest::MD5.hexdigest(seed)}.sock"
|
|
195
197
|
end
|
|
196
198
|
|
|
199
|
+
# Directory that environment-file lookups resolve against.
|
|
200
|
+
#
|
|
201
|
+
# When a config path is given, its directory is the project root so a
|
|
202
|
+
# client started from a subdirectory reuses the same daemon. Without a
|
|
203
|
+
# config path this falls back to the working directory.
|
|
204
|
+
#
|
|
205
|
+
# @param [String?] config_path optional config path
|
|
206
|
+
# @return [String] absolute project root path
|
|
207
|
+
def project_root(config_path = nil)
|
|
208
|
+
return File.expand_path(Dir.pwd) unless config_path
|
|
209
|
+
|
|
210
|
+
File.expand_path(File.dirname(config_path))
|
|
211
|
+
end
|
|
212
|
+
|
|
197
213
|
# Hash of environment files that affect analysis results.
|
|
198
214
|
# When any of these change, the daemon is invalidated (new socket path).
|
|
199
215
|
# Includes Gemfile.lock, rbs_collection.lock.yaml, docscribe.yml and all sig/**/*.rbs.
|
|
200
216
|
#
|
|
217
|
+
# @param [String] root directory containing the environment files
|
|
201
218
|
# @return [String]
|
|
202
|
-
def env_hash
|
|
203
|
-
parts = ENV_FILES.map { |file| env_file_mtime(file) }
|
|
204
|
-
parts.concat(sig_env_parts)
|
|
219
|
+
def env_hash(root = File.expand_path(Dir.pwd))
|
|
220
|
+
parts = ENV_FILES.map { |file| env_file_mtime(file, root) }
|
|
221
|
+
parts.concat(sig_env_parts(root))
|
|
205
222
|
Digest::MD5.hexdigest(parts.join(':'))
|
|
206
223
|
end
|
|
207
224
|
|
|
208
225
|
# Hash of RBS signature files for cache invalidation inside daemon.
|
|
209
226
|
# Used by Daemon#rewrite_file to detect sig changes without requiring a new socket.
|
|
210
227
|
#
|
|
228
|
+
# @param [String] root directory containing the sig files
|
|
211
229
|
# @return [String]
|
|
212
|
-
def sig_hash
|
|
213
|
-
files = sig_files
|
|
230
|
+
def sig_hash(root = File.expand_path(Dir.pwd))
|
|
231
|
+
files = sig_files(root)
|
|
214
232
|
parts = files.map { |p| "#{p}:#{File.mtime(p).to_f}" }
|
|
215
233
|
parts << "count:#{files.size}"
|
|
216
234
|
Digest::MD5.hexdigest(parts.join('|'))
|
|
217
235
|
end
|
|
218
236
|
|
|
219
237
|
# @param [String] file
|
|
238
|
+
# @param [String] root directory containing the file
|
|
220
239
|
# @return [String]
|
|
221
|
-
def env_file_mtime(file)
|
|
222
|
-
path = File.join(
|
|
240
|
+
def env_file_mtime(file, root = File.expand_path(Dir.pwd))
|
|
241
|
+
path = File.join(root, file)
|
|
223
242
|
File.exist?(path) ? File.mtime(path).to_f.to_s : '0'
|
|
224
243
|
end
|
|
225
244
|
|
|
245
|
+
# @param [String] root directory containing the sig files
|
|
226
246
|
# @return [Array<String>]
|
|
227
|
-
def sig_env_parts
|
|
228
|
-
files = sig_files
|
|
247
|
+
def sig_env_parts(root = File.expand_path(Dir.pwd))
|
|
248
|
+
files = sig_files(root)
|
|
229
249
|
mtimes = files.map { |p| File.mtime(p).to_f.to_s }
|
|
230
250
|
mtimes << files.size.to_s
|
|
231
251
|
mtimes
|
|
232
252
|
end
|
|
233
253
|
|
|
254
|
+
# @param [String] root directory containing the sig files
|
|
234
255
|
# @return [Array<String>]
|
|
235
|
-
def sig_files
|
|
236
|
-
Dir.glob(File.join(
|
|
256
|
+
def sig_files(root = File.expand_path(Dir.pwd))
|
|
257
|
+
Dir.glob(File.join(root, SIG_RBS_GLOB)).sort
|
|
237
258
|
end
|
|
238
259
|
|
|
239
260
|
public :read_pid, :pid_path, :socket_path
|
|
@@ -429,7 +429,8 @@ module Docscribe
|
|
|
429
429
|
# @param [Array<String>] dirs
|
|
430
430
|
# @return [Array<String>]
|
|
431
431
|
def sig_rbs_files(dirs)
|
|
432
|
-
|
|
432
|
+
root = config_root
|
|
433
|
+
dirs.flat_map { |dir| Dir.glob(File.expand_path(File.join(dir, '**', '*.rbs'), root)) }.uniq.sort
|
|
433
434
|
end
|
|
434
435
|
|
|
435
436
|
# Resolve sig dirs from config, falling back to defaults.
|
|
@@ -447,6 +448,14 @@ module Docscribe
|
|
|
447
448
|
['sig']
|
|
448
449
|
end
|
|
449
450
|
|
|
451
|
+
# Config root shared by the daemon's config-derived path lookups.
|
|
452
|
+
#
|
|
453
|
+
# @private
|
|
454
|
+
# @return [String]
|
|
455
|
+
def config_root
|
|
456
|
+
@config&.config_root || File.expand_path(Dir.pwd)
|
|
457
|
+
end
|
|
458
|
+
|
|
450
459
|
# Handle update_types request (used by RubyMine plugin).
|
|
451
460
|
#
|
|
452
461
|
# @private
|
|
@@ -21,13 +21,16 @@ module Docscribe
|
|
|
21
21
|
# @param [Array<String>] collection_dirs RBS collection directories
|
|
22
22
|
# @param [Boolean] collapse_generics whether generic container types
|
|
23
23
|
# @param [Boolean] collapse_object_generics collapse Object generics flag
|
|
24
|
+
# @param [String] config_root directory holding `rbs_collection.lock.yaml`
|
|
24
25
|
# @return [void]
|
|
25
|
-
def initialize(sig_dirs:, collection_dirs: [], collapse_generics: false, collapse_object_generics: false
|
|
26
|
+
def initialize(sig_dirs:, collection_dirs: [], collapse_generics: false, collapse_object_generics: false,
|
|
27
|
+
config_root: Dir.pwd)
|
|
26
28
|
require 'rbs'
|
|
27
29
|
@sig_dirs = Array(sig_dirs).map(&:to_s)
|
|
28
30
|
@collection_dirs = Array(collection_dirs).map(&:to_s)
|
|
29
31
|
@collapse_generics = !!collapse_generics
|
|
30
32
|
@collapse_object_generics = !!collapse_object_generics
|
|
33
|
+
@config_root = config_root
|
|
31
34
|
@env = nil
|
|
32
35
|
@builder = nil
|
|
33
36
|
@warned = false
|
|
@@ -223,7 +226,7 @@ module Docscribe
|
|
|
223
226
|
# @return [void]
|
|
224
227
|
# @return [nil] if StandardError
|
|
225
228
|
def load_stdlib_libraries!(loader)
|
|
226
|
-
lock_path = File.join(
|
|
229
|
+
lock_path = File.join(@config_root, 'rbs_collection.lock.yaml')
|
|
227
230
|
return unless File.exist?(lock_path)
|
|
228
231
|
|
|
229
232
|
lock = YAML.safe_load_file(lock_path) # steep:ignore
|
|
@@ -72,7 +72,7 @@ module Docscribe
|
|
|
72
72
|
# "Unexpected type_node" STDERR noise unless DOCSCRIBE_RBS_DEBUG=1.
|
|
73
73
|
#
|
|
74
74
|
# @private
|
|
75
|
-
# @param [
|
|
75
|
+
# @param [RBS::Prototype::RBI] parser RBI parser instance
|
|
76
76
|
# @param [String] source source text to parse
|
|
77
77
|
# @return [void]
|
|
78
78
|
def parse(parser, source)
|
|
@@ -81,7 +81,7 @@ module Docscribe
|
|
|
81
81
|
def parse_primary
|
|
82
82
|
skip_space
|
|
83
83
|
case peek
|
|
84
|
-
when '(' then parse_tuple
|
|
84
|
+
when '(', '[' then parse_tuple
|
|
85
85
|
when '{' then parse_hash_map
|
|
86
86
|
when '#' then parse_duck_type
|
|
87
87
|
else
|
|
@@ -131,12 +131,16 @@ module Docscribe
|
|
|
131
131
|
|
|
132
132
|
# @private
|
|
133
133
|
# @return [Array<Docscribe::Types::Yard::node>]
|
|
134
|
-
def parse_generic_args
|
|
134
|
+
def parse_generic_args # rubocop:disable Metrics/MethodLength
|
|
135
135
|
args = [] #: Array[untyped]
|
|
136
136
|
skip_space
|
|
137
137
|
while peek && peek != '>'
|
|
138
|
+
before = @i
|
|
138
139
|
args << parse_generic_arg
|
|
139
140
|
skip_space
|
|
141
|
+
# A branch that consumed nothing would otherwise loop forever.
|
|
142
|
+
break if @i == before
|
|
143
|
+
|
|
140
144
|
next unless peek == ','
|
|
141
145
|
|
|
142
146
|
@i += 1
|
|
@@ -148,13 +152,14 @@ module Docscribe
|
|
|
148
152
|
# @private
|
|
149
153
|
# @return [Docscribe::Types::Yard::Tuple]
|
|
150
154
|
def parse_tuple
|
|
155
|
+
close = peek == '[' ? ']' : ')'
|
|
151
156
|
@i += 1
|
|
152
157
|
types = [] #: Array[untyped]
|
|
153
|
-
while peek && peek !=
|
|
158
|
+
while peek && peek != close
|
|
154
159
|
types << parse_tuple_element
|
|
155
160
|
@i += 1 and skip_space if peek == ','
|
|
156
161
|
end
|
|
157
|
-
@i += 1 if peek ==
|
|
162
|
+
@i += 1 if peek == close
|
|
158
163
|
Tuple.new(types: types)
|
|
159
164
|
end
|
|
160
165
|
|