field_struct 0.15.0 → 1.0.0.pre1
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/.claude-plugin/marketplace.json +13 -0
- data/.claude-plugin/plugin.json +9 -0
- data/AGENTS.md +47 -54
- data/CHANGELOG.md +53 -640
- data/LICENSE.txt +21 -0
- data/README.md +33 -628
- data/USAGE.md +771 -715
- data/docs/getting_started.md +139 -325
- data/lib/field_struct/base.rb +241 -1149
- data/lib/field_struct/class_macros.rb +163 -0
- data/lib/field_struct/describer.rb +167 -0
- data/lib/field_struct/errors.rb +182 -62
- data/lib/field_struct/exceptions.rb +40 -0
- data/lib/field_struct/field.rb +69 -135
- data/lib/field_struct/field_builder.rb +110 -0
- data/lib/field_struct/field_checks.rb +50 -0
- data/lib/field_struct/introspection.rb +199 -0
- data/lib/field_struct/json_codec.rb +240 -0
- data/lib/field_struct/metadata.rb +65 -260
- data/lib/field_struct/model_name.rb +27 -27
- data/lib/field_struct/option_checker.rb +121 -0
- data/lib/field_struct/partial.rb +49 -0
- data/lib/field_struct/presence.rb +45 -0
- data/lib/field_struct/rbs.rb +151 -271
- data/lib/field_struct/registered_option.rb +113 -0
- data/lib/field_struct/registry.rb +40 -50
- data/lib/field_struct/restrictions.rb +90 -0
- data/lib/field_struct/scaffold.rb +274 -301
- data/lib/field_struct/suggestion.rb +33 -0
- data/lib/field_struct/types/array.rb +147 -126
- data/lib/field_struct/types/base.rb +113 -124
- data/lib/field_struct/types/big_decimal.rb +59 -55
- data/lib/field_struct/types/binary.rb +18 -25
- data/lib/field_struct/types/boolean.rb +74 -97
- data/lib/field_struct/types/builtin.rb +32 -0
- data/lib/field_struct/types/date.rb +23 -137
- data/lib/field_struct/types/datetime.rb +30 -139
- data/lib/field_struct/types/element_options.rb +51 -0
- data/lib/field_struct/types/email.rb +27 -38
- data/lib/field_struct/types/float.rb +58 -56
- data/lib/field_struct/types/format_presets.rb +30 -0
- data/lib/field_struct/types/hash.rb +144 -0
- data/lib/field_struct/types/immutable_string.rb +16 -9
- data/lib/field_struct/types/integer.rb +74 -102
- data/lib/field_struct/types/nested.rb +57 -58
- data/lib/field_struct/types/preset_resolver.rb +9 -24
- data/lib/field_struct/types/rfc3339_format.rb +70 -153
- data/lib/field_struct/types/string.rb +48 -46
- data/lib/field_struct/types/symbol.rb +23 -20
- data/lib/field_struct/types/temporal.rb +232 -0
- data/lib/field_struct/types/time.rb +32 -145
- data/lib/field_struct/types/union.rb +111 -65
- data/lib/field_struct/types/union_pick.rb +139 -0
- data/lib/field_struct/types/url.rb +24 -35
- data/lib/field_struct/types/uuid.rb +24 -35
- data/lib/field_struct/types/value.rb +14 -9
- data/lib/field_struct/types/zone.rb +118 -0
- data/lib/field_struct/version.rb +3 -3
- data/lib/field_struct.rb +102 -122
- data/sig/field_struct.rbs +1180 -2300
- data/sig/manifest.yaml +6 -0
- data/skills/field-struct/SKILL.md +73 -159
- metadata +37 -28
- data/CODE_OF_CONDUCT.md +0 -132
- data/UPGRADING.md +0 -743
- data/lib/field_struct/error.rb +0 -48
- data/lib/field_struct/types/temporal_parser.rb +0 -93
- data/lib/field_struct/types/time_format_resolver.rb +0 -54
- data/lib/field_struct/types/zone_option.rb +0 -267
|
@@ -1,331 +1,304 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
3
|
module FieldStruct
|
|
4
|
-
#
|
|
5
|
-
#
|
|
6
|
-
# The goal is a *working prototype* you then refine by hand — the generator
|
|
7
|
-
# is deliberately conservative about types and never guesses past the
|
|
8
|
-
# evidence. Pass a single object to seed the shape, or an array of
|
|
9
|
-
# same-shape objects to gather more signal (empty fields get resolved from
|
|
10
|
-
# other samples, presence drives required/optional, and small repeated
|
|
11
|
-
# vocabularies surface as enum candidates). A single object is just the
|
|
12
|
-
# one-sample case of the same engine.
|
|
13
|
-
#
|
|
14
|
-
# FieldStruct::Scaffold.from_json(<<~JSON, class_name: 'User')
|
|
15
|
-
# {"name": "Al", "age": 30, "active": true}
|
|
16
|
-
# JSON
|
|
17
|
-
# # class User < FieldStruct::Base
|
|
18
|
-
# # required :name, :string
|
|
19
|
-
# # required :age, :integer
|
|
20
|
-
# # required :active, :boolean
|
|
21
|
-
# # end
|
|
22
|
-
#
|
|
23
|
-
# Inference rules (conservative on purpose):
|
|
24
|
-
#
|
|
25
|
-
# * JSON object → a nested FieldStruct class (emitted before its parent).
|
|
26
|
-
# * JSON array → +:array, of: <element type>+ (element class for arrays of objects).
|
|
27
|
-
# * JSON +true+/+false+ → +:boolean+; integer → +:integer+; real → +:float+.
|
|
28
|
-
# * JSON string → +:string+ — *including numeric-looking strings* (an
|
|
29
|
-
# +authorization_code+ must not become an Integer). Hints like "maybe
|
|
30
|
-
# :big_decimal" are emitted as trailing comments, not committed types.
|
|
31
|
-
# * required when present and non-blank across *every* sample; else optional.
|
|
32
|
-
#
|
|
33
|
-
# The developer adds enums, descriptions, formats, and final scalar types;
|
|
34
|
-
# the comments point at where.
|
|
4
|
+
# Starter source for FieldStruct classes, guessed from JSON examples. A prototype to refine: risky guesses are
|
|
5
|
+
# reported as trailing comments instead of being committed to.
|
|
35
6
|
module Scaffold
|
|
36
|
-
#
|
|
37
|
-
# @return [
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
7
|
+
# Ruby keywords; a JSON key that sanitizes to one gets a +_field+ suffix.
|
|
8
|
+
# @return [::Array<::String>]
|
|
9
|
+
KEYWORDS = %w[
|
|
10
|
+
alias and begin BEGIN break case class def defined? do else elsif end END ensure false for if in module next nil
|
|
11
|
+
not or redo rescue retry return self super then true undef unless until when while yield __FILE__ __LINE__ __ENCODING__
|
|
12
|
+
].freeze
|
|
13
|
+
|
|
14
|
+
# Core class names a generated class must not reopen.
|
|
15
|
+
# @return [::Array<::String>]
|
|
16
|
+
CORE_NAMES = %w[
|
|
17
|
+
Array BigDecimal Class Comparable Data Date DateTime Dir File Float Hash Integer IO Kernel Method Module Numeric
|
|
18
|
+
Object Proc Range Regexp Set String Struct Symbol Time
|
|
19
|
+
].freeze
|
|
20
|
+
|
|
21
|
+
# Matches a numeric-looking string.
|
|
22
|
+
# @return [::Regexp]
|
|
23
|
+
NUMERIC = /\A-?\d+(?:\.\d+)?\z/
|
|
24
|
+
# Most distinct values an enum-like String field can have.
|
|
25
|
+
# @return [::Integer]
|
|
41
26
|
ENUM_MAX_DISTINCT = 6
|
|
42
|
-
#
|
|
43
|
-
#
|
|
44
|
-
|
|
45
|
-
# @return [Array<String>]
|
|
46
|
-
RESERVED = (%w[
|
|
47
|
-
BEGIN END alias and begin break case class def defined? do else elsif end
|
|
48
|
-
ensure false for if in module next nil not or redo rescue retry return self
|
|
49
|
-
super then true undef unless until when while yield __FILE__ __LINE__
|
|
50
|
-
] + Base::RESERVED_FIELD_NAMES.map(&:to_s)).uniq.freeze
|
|
51
|
-
|
|
52
|
-
# Generate FieldStruct class source from JSON example(s).
|
|
53
|
-
#
|
|
54
|
-
# @param input [String, Hash{Object=>Object, nil}, Array<Hash{Object=>Object, nil}>] a JSON string (object or array
|
|
55
|
-
# root), a parsed Hash, or an Array of same-shape Hashes
|
|
56
|
-
# @param class_name [String] the root class name
|
|
57
|
-
# @return [String] Ruby source defining the class and any nested classes
|
|
58
|
-
# @raise [ArgumentError] for an empty set or non-object samples
|
|
59
|
-
def self.from_json(input, class_name: 'Generated')
|
|
60
|
-
samples = normalize(input)
|
|
61
|
-
raise ArgumentError, 'no samples to scaffold from' if samples.empty?
|
|
62
|
-
raise ArgumentError, 'every sample must be a JSON object' unless samples.all?(::Hash)
|
|
63
|
-
|
|
64
|
-
classes = []
|
|
65
|
-
emit_object(class_name, samples, classes, [])
|
|
66
|
-
"#{classes.join("\n\n")}\n"
|
|
67
|
-
end
|
|
27
|
+
# Fewest values a String field needs before it is called enum-like.
|
|
28
|
+
# @return [::Integer]
|
|
29
|
+
ENUM_MIN_VALUES = 3
|
|
68
30
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
31
|
+
class << self
|
|
32
|
+
# Builds starter source for one class (plus helper classes) from one example or an array of same-shape examples.
|
|
33
|
+
#
|
|
34
|
+
# @param input [String, Hash{String=>Object, nil}, Array<Hash{String=>Object, nil}>] a JSON String, or already-parsed data
|
|
35
|
+
# @param class_name [String] the name of the top class
|
|
36
|
+
# @return [String] Ruby source ending with a newline
|
|
37
|
+
# @raise [ArgumentError] for input that is not an object or an array of objects, or an empty array
|
|
38
|
+
def from_json(input, class_name: 'Generated')
|
|
39
|
+
parsed = input.is_a?(::String) ? parse(input) : input
|
|
40
|
+
samples = samples_from(parsed)
|
|
41
|
+
generator = Generator.new(class_name)
|
|
42
|
+
generator.build(class_name, samples)
|
|
43
|
+
generator.sources.join("\n")
|
|
79
44
|
end
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
# @param classes [Array<String>] class sources emitted so far (appended to)
|
|
90
|
-
# @param used [Array<String>] class names taken so far (appended to)
|
|
91
|
-
# @return [String]
|
|
92
|
-
def self.emit_object(class_name, samples, classes, used)
|
|
93
|
-
name = unique_name(class_name, used)
|
|
94
|
-
total = samples.length
|
|
95
|
-
mappings = {}
|
|
96
|
-
attrs = []
|
|
97
|
-
lines = ordered_keys(samples).map do |key|
|
|
98
|
-
# Two keys can normalize to one name ("fooBar"/"foo_bar"); suffix the
|
|
99
|
-
# later one so neither value is lost.
|
|
100
|
-
attr = unique_name(safe_attr(key), attrs)
|
|
101
|
-
mappings[attr] = key unless attr == key
|
|
102
|
-
field_line(attr, observe(samples, key), total, classes, used)
|
|
45
|
+
|
|
46
|
+
private
|
|
47
|
+
|
|
48
|
+
# Parses with Oj, and reports a parse error by position only: Oj's own message quotes the input (FS-I5).
|
|
49
|
+
def parse(text)
|
|
50
|
+
Oj.load(text, mode: :strict)
|
|
51
|
+
rescue Oj::ParseError, EncodingError => e
|
|
52
|
+
position = e.message[/line \d+, column \d+/]
|
|
53
|
+
raise FieldStruct::Error, "Scaffold.from_json: input is not valid JSON#{" (#{position})" if position}"
|
|
103
54
|
end
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
{present: present.length, values: present.map { |sample| sample[key] }}
|
|
116
|
-
end
|
|
117
|
-
private_class_method :observe
|
|
118
|
-
|
|
119
|
-
# @param attr [String] the attribute name
|
|
120
|
-
# @param obs [Hash{Symbol=>Integer, Array<Object, nil>}] from {.observe}
|
|
121
|
-
# @param total [Integer] the sample count
|
|
122
|
-
# @param classes [Array<String>] class sources emitted so far
|
|
123
|
-
# @param used [Array<String>] class names taken so far
|
|
124
|
-
# @return [String] the indented DSL line
|
|
125
|
-
def self.field_line(attr, obs, total, classes, used)
|
|
126
|
-
values = obs[:values]
|
|
127
|
-
non_nil = values.compact
|
|
128
|
-
missing = values.count(&:nil?) + values.count { |v| blank_string?(v) }
|
|
129
|
-
required = obs[:present] == total && missing.zero?
|
|
130
|
-
avail = availability_comment(obs[:present], total, missing)
|
|
131
|
-
|
|
132
|
-
type_part, hint = type_for(attr, non_nil, classes, used)
|
|
133
|
-
decorate("#{required ? "required" : "optional"} :#{attr}, #{type_part}", avail, hint)
|
|
134
|
-
end
|
|
135
|
-
private_class_method :field_line
|
|
136
|
-
|
|
137
|
-
# @param attr [String] the attribute name
|
|
138
|
-
# @param non_nil [Array<Object>] the attribute's non-nil sample values
|
|
139
|
-
# @param classes [Array<String>] class sources emitted so far
|
|
140
|
-
# @param used [Array<String>] class names taken so far
|
|
141
|
-
# @return [Array(String, String)] +[type_part, comment_hint]+
|
|
142
|
-
def self.type_for(attr, non_nil, classes, used)
|
|
143
|
-
if non_nil.any?(::Hash)
|
|
144
|
-
[emit_object(class_name_for(attr), non_nil.grep(::Hash), classes, used), nil]
|
|
145
|
-
elsif non_nil.any?(::Array)
|
|
146
|
-
of_part, hint = array_element(attr, non_nil.grep(::Array).flatten(1), classes, used)
|
|
147
|
-
[":array, of: #{of_part}", hint]
|
|
148
|
-
else
|
|
149
|
-
sym, hint = infer_scalar(non_nil)
|
|
150
|
-
[":#{sym}", hint]
|
|
55
|
+
|
|
56
|
+
def samples_from(parsed)
|
|
57
|
+
samples = case parsed
|
|
58
|
+
when ::Hash then [parsed]
|
|
59
|
+
when ::Array then parsed
|
|
60
|
+
else raise ::ArgumentError, "expected a JSON object or array of objects, got #{parsed.class}"
|
|
61
|
+
end
|
|
62
|
+
raise ::ArgumentError, 'no samples to scaffold from' if samples.empty?
|
|
63
|
+
raise ::ArgumentError, 'every sample must be a JSON object' unless samples.all?(::Hash)
|
|
64
|
+
|
|
65
|
+
samples.map { |sample| sample.transform_keys(&:to_s) }
|
|
151
66
|
end
|
|
152
67
|
end
|
|
153
|
-
private_class_method :type_for
|
|
154
|
-
|
|
155
|
-
# @param attr [String] the attribute name
|
|
156
|
-
# @param elements [Array<Object, nil>] every element of the attribute's arrays
|
|
157
|
-
# @param classes [Array<String>] class sources emitted so far
|
|
158
|
-
# @param used [Array<String>] class names taken so far
|
|
159
|
-
# @return [Array(String, String)] +of:+ value and a comment hint
|
|
160
|
-
def self.array_element(attr, elements, classes, used)
|
|
161
|
-
non_nil = elements.compact
|
|
162
|
-
return [':value', 'empty array(s) in samples — element type unknown'] if non_nil.empty?
|
|
163
|
-
return [emit_object(class_name_for(singularize(attr)), non_nil.grep(::Hash), classes, used), nil] \
|
|
164
|
-
if non_nil.any?(::Hash)
|
|
165
|
-
|
|
166
|
-
sym, hint = infer_scalar(non_nil)
|
|
167
|
-
[":#{sym}", hint]
|
|
168
|
-
end
|
|
169
|
-
private_class_method :array_element
|
|
170
68
|
|
|
171
|
-
#
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
69
|
+
# INTERNAL: walks the samples and emits one class source per object shape.
|
|
70
|
+
class Generator
|
|
71
|
+
# @return [Array<String>] class sources, children before parents, each ending with a newline
|
|
72
|
+
attr_reader :sources
|
|
175
73
|
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
74
|
+
# @param top_name [::String] the top-level class name, kept free of collisions
|
|
75
|
+
def initialize(top_name)
|
|
76
|
+
@taken = CORE_NAMES + [top_name]
|
|
77
|
+
@sources = []
|
|
78
|
+
end
|
|
181
79
|
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
80
|
+
# @param name [String] the class name
|
|
81
|
+
# @param samples [::Array<::Hash{::String=>::Object}>] String-keyed objects
|
|
82
|
+
# @return [::Array<::String>] the sources so far
|
|
83
|
+
def build(name, samples)
|
|
84
|
+
names = Names.new
|
|
85
|
+
lines = []
|
|
86
|
+
mapping = {}
|
|
87
|
+
keys_of(samples).each do |key|
|
|
88
|
+
field_name = names.field_name(key)
|
|
89
|
+
mapping[field_name] = key unless field_name == key
|
|
90
|
+
lines << field_line(field_name, key, samples)
|
|
91
|
+
end
|
|
92
|
+
@sources << render(name, lines, mapping)
|
|
93
|
+
end
|
|
185
94
|
|
|
186
|
-
|
|
187
|
-
# @return [Array(Symbol, String)] +:string+ and a comment hint
|
|
188
|
-
def self.string_inference(values)
|
|
189
|
-
non_empty = values.reject { |s| blank_string?(s) }
|
|
190
|
-
return [:string, 'always empty in samples — type unknown'] if non_empty.empty?
|
|
95
|
+
private
|
|
191
96
|
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
return [:string, %(numeric-looking (e.g. "#{non_empty.first}") — #{suggestion}? or keep :string if an id/code)]
|
|
97
|
+
def keys_of(samples)
|
|
98
|
+
samples.flat_map(&:keys).uniq
|
|
195
99
|
end
|
|
196
100
|
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
101
|
+
def render(name, lines, mapping)
|
|
102
|
+
body = lines.empty? ? [' # (no fields detected in samples)'] : lines
|
|
103
|
+
body += ['', " serialize :json, #{mapping.map { |field, key| "#{field}: #{key.inspect}" }.join(', ')}"] unless mapping.empty?
|
|
104
|
+
"class #{name} < FieldStruct::Base\n#{body.join("\n")}\nend\n"
|
|
200
105
|
end
|
|
201
106
|
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
def self.scalar_kind(value)
|
|
209
|
-
case value
|
|
210
|
-
when true, false then :boolean
|
|
211
|
-
when ::Integer then :integer
|
|
212
|
-
when ::Float then :float
|
|
213
|
-
when ::String then :string
|
|
214
|
-
else :other
|
|
107
|
+
def field_line(field_name, key, samples)
|
|
108
|
+
stat = Stat.new(key, samples)
|
|
109
|
+
type, notes = type_for(stat, key)
|
|
110
|
+
parts = (stat.availability + notes).compact
|
|
111
|
+
line = " #{stat.required? ? 'required' : 'optional'} :#{field_name}, #{type}"
|
|
112
|
+
parts.empty? ? line : "#{line} # #{parts.join('; ')}"
|
|
215
113
|
end
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
unless mappings.empty?
|
|
229
|
-
body << ''
|
|
230
|
-
body << " serialize :json, #{mappings.map { |attr, key| "#{attr}: #{key.inspect}" }.join(", ")}"
|
|
114
|
+
|
|
115
|
+
# @return [Array(String, Array<String>)] the type expression and the hint parts
|
|
116
|
+
def type_for(stat, key)
|
|
117
|
+
kinds = stat.kinds
|
|
118
|
+
return [':string', [stat.always_null_hint]] if kinds.empty?
|
|
119
|
+
return [':value', ["mixed types in samples (#{kinds.join(', ')}) — review"]] if stat.mixed?
|
|
120
|
+
|
|
121
|
+
case stat.kind
|
|
122
|
+
when :object then [build_child(key, stat.values), []]
|
|
123
|
+
when :array then array_type(stat, key)
|
|
124
|
+
else [":#{stat.kind}", stat.string_hints]
|
|
125
|
+
end
|
|
231
126
|
end
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
# empty ones are dropped
|
|
239
|
-
# @return [String] the indented line, with a +#+ comment when any part remains
|
|
240
|
-
def self.decorate(declaration, *comment_parts)
|
|
241
|
-
parts = comment_parts.compact.reject(&:empty?)
|
|
242
|
-
line = " #{declaration}"
|
|
243
|
-
parts.empty? ? line : "#{line} # #{parts.join("; ")}"
|
|
244
|
-
end
|
|
245
|
-
private_class_method :decorate
|
|
246
|
-
|
|
247
|
-
# @param present [Integer] samples holding the key
|
|
248
|
-
# @param total [Integer] the sample count
|
|
249
|
-
# @param missing [Integer] nil or blank values among them
|
|
250
|
-
# @return [String, nil]
|
|
251
|
-
def self.availability_comment(present, total, missing)
|
|
252
|
-
return "present #{present}/#{total}" if present < total
|
|
253
|
-
# Only note partial emptiness; when every sample is empty the scalar
|
|
254
|
-
# hint ("always empty — type unknown") already says so.
|
|
255
|
-
return "empty/null in #{missing}/#{total}" if missing.positive? && missing < total
|
|
256
|
-
|
|
257
|
-
nil
|
|
258
|
-
end
|
|
259
|
-
private_class_method :availability_comment
|
|
260
|
-
|
|
261
|
-
# First-seen union of keys across all samples.
|
|
262
|
-
#
|
|
263
|
-
# @param samples [Array<Hash{Object=>Object, nil}>]
|
|
264
|
-
# @return [Array<Object>]
|
|
265
|
-
def self.ordered_keys(samples)
|
|
266
|
-
samples.each_with_object([]) do |sample, keys|
|
|
267
|
-
sample.each_key { |key| keys << key unless keys.include?(key) }
|
|
127
|
+
|
|
128
|
+
def array_type(stat, key)
|
|
129
|
+
elements = stat.values.flatten(1)
|
|
130
|
+
return [':array, of: :value', ['empty array(s) in samples — element type unknown']] if elements.empty?
|
|
131
|
+
|
|
132
|
+
[":array, of: #{element_type(elements, key)}", []]
|
|
268
133
|
end
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
name = "#{base}#{suffix}"
|
|
134
|
+
|
|
135
|
+
def element_type(elements, key)
|
|
136
|
+
stat = Stat.of_values(elements)
|
|
137
|
+
return ':string' if stat.kinds.empty?
|
|
138
|
+
return ':value' if stat.mixed?
|
|
139
|
+
|
|
140
|
+
case stat.kind
|
|
141
|
+
when :object then build_child(singular(key), stat.values)
|
|
142
|
+
when :array then ':value'
|
|
143
|
+
else ":#{stat.kind}"
|
|
144
|
+
end
|
|
281
145
|
end
|
|
282
|
-
used << name
|
|
283
|
-
name
|
|
284
|
-
end
|
|
285
|
-
private_class_method :unique_name
|
|
286
|
-
|
|
287
|
-
# @param key [String] an attribute name
|
|
288
|
-
# @return [String] a constant-safe class name
|
|
289
|
-
def self.class_name_for(key)
|
|
290
|
-
name = camelize(key)
|
|
291
|
-
name = "N#{name}" unless name.match?(/\A[A-Z]/)
|
|
292
|
-
name
|
|
293
|
-
end
|
|
294
|
-
private_class_method :class_name_for
|
|
295
146
|
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
147
|
+
def build_child(key, samples)
|
|
148
|
+
name = class_name_for(key)
|
|
149
|
+
build(name, samples.map { |sample| sample.transform_keys(&:to_s) })
|
|
150
|
+
name
|
|
151
|
+
end
|
|
152
|
+
|
|
153
|
+
def singular(key)
|
|
154
|
+
key.length > 1 && key.end_with?('s') ? key[0...-1] : key
|
|
155
|
+
end
|
|
156
|
+
|
|
157
|
+
def class_name_for(key)
|
|
158
|
+
base = Names.words(key).map { |word| word[0].upcase + word[1..] }.join
|
|
159
|
+
base = "N#{base}" unless base.match?(/\A[A-Z]/)
|
|
160
|
+
name = base
|
|
161
|
+
counter = 2
|
|
162
|
+
while @taken.include?(name)
|
|
163
|
+
name = "#{base}#{counter}"
|
|
164
|
+
counter += 1
|
|
165
|
+
end
|
|
166
|
+
@taken << name
|
|
167
|
+
name
|
|
168
|
+
end
|
|
310
169
|
end
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
170
|
+
|
|
171
|
+
# INTERNAL: what the samples say about one key.
|
|
172
|
+
class Stat
|
|
173
|
+
# @return [Array<Object>] the non-null values, in sample order
|
|
174
|
+
attr_reader :values
|
|
175
|
+
|
|
176
|
+
# @param values [::Array<::Object>] non-null sample values
|
|
177
|
+
# @return [FieldStruct::Scaffold::Stat]
|
|
178
|
+
def self.of_values(values)
|
|
179
|
+
new(nil, [], values)
|
|
180
|
+
end
|
|
181
|
+
|
|
182
|
+
# @param key [::String, nil] the key to read from each sample
|
|
183
|
+
# @param samples [::Array<::Hash{::String=>::Object}>] String-keyed objects
|
|
184
|
+
# @param values [::Array<::Object>, nil] values to use instead of reading the samples
|
|
185
|
+
def initialize(key, samples, values = nil)
|
|
186
|
+
@total = samples.size
|
|
187
|
+
@present = key ? samples.count { |sample| sample.key?(key) } : 0
|
|
188
|
+
all = values || samples.filter_map { |sample| [sample[key]] if sample.key?(key) }.flatten(1)
|
|
189
|
+
@all = all
|
|
190
|
+
@values = all.compact
|
|
191
|
+
end
|
|
192
|
+
|
|
193
|
+
def required?
|
|
194
|
+
@present == @total && @all.none? { |value| blank?(value) }
|
|
195
|
+
end
|
|
196
|
+
|
|
197
|
+
# The distinct non-null kinds, in order of first appearance.
|
|
198
|
+
#
|
|
199
|
+
# @return [::Array<::Symbol>]
|
|
200
|
+
def kinds
|
|
201
|
+
@kinds ||= @values.map { |value| kind_of(value) }.uniq
|
|
202
|
+
end
|
|
203
|
+
|
|
204
|
+
def mixed?
|
|
205
|
+
kind.nil?
|
|
206
|
+
end
|
|
207
|
+
|
|
208
|
+
# The single kind the values agree on (integers and floats merge to float), or nil when they disagree.
|
|
209
|
+
#
|
|
210
|
+
# @return [::Symbol, nil]
|
|
211
|
+
def kind
|
|
212
|
+
return (kinds.size == 1 ? kinds.first : nil) unless (kinds - %i[integer float]).empty? && kinds.size == 2
|
|
213
|
+
|
|
214
|
+
:float
|
|
215
|
+
end
|
|
216
|
+
|
|
217
|
+
# @return [::Array<::String>] hint parts about missing or empty values
|
|
218
|
+
def availability
|
|
219
|
+
blanks = @all.count { |value| blank?(value) }
|
|
220
|
+
if @present < @total then ["present #{@present}/#{@total}"]
|
|
221
|
+
elsif blanks.positive? && blanks < @total then ["empty/null in #{blanks}/#{@total}"]
|
|
222
|
+
else []
|
|
223
|
+
end
|
|
224
|
+
end
|
|
225
|
+
|
|
226
|
+
# @return [::String]
|
|
227
|
+
def always_null_hint
|
|
228
|
+
'always null/absent in samples — type unknown'
|
|
229
|
+
end
|
|
230
|
+
|
|
231
|
+
# Hints for a String field: numeric-looking, enum-like, or always blank.
|
|
232
|
+
#
|
|
233
|
+
# @return [::Array<::String>]
|
|
234
|
+
def string_hints
|
|
235
|
+
return [] unless kind == :string
|
|
236
|
+
|
|
237
|
+
filled = @values.reject { |value| blank?(value) }
|
|
238
|
+
return ['always empty in samples — type unknown'] if filled.empty?
|
|
239
|
+
return [numeric_hint(filled)] if filled.all? { |value| value.match?(NUMERIC) }
|
|
240
|
+
|
|
241
|
+
enum_hint(filled)
|
|
242
|
+
end
|
|
243
|
+
|
|
244
|
+
private
|
|
245
|
+
|
|
246
|
+
def numeric_hint(filled)
|
|
247
|
+
guess = filled.any? { |value| value.include?('.') } ? ':big_decimal?' : ':integer?'
|
|
248
|
+
"numeric-looking (e.g. #{filled.first.inspect}) — #{guess} or keep :string if an id/code"
|
|
249
|
+
end
|
|
250
|
+
|
|
251
|
+
def enum_hint(filled)
|
|
252
|
+
distinct = filled.uniq
|
|
253
|
+
return [] unless filled.size >= ENUM_MIN_VALUES && distinct.size < filled.size && distinct.size <= ENUM_MAX_DISTINCT
|
|
254
|
+
|
|
255
|
+
["values: #{distinct.inspect} — enum?"]
|
|
256
|
+
end
|
|
257
|
+
|
|
258
|
+
def blank?(value)
|
|
259
|
+
value.nil? || (value.is_a?(::String) && value.strip.empty?) || (value.is_a?(::Array) && value.empty?)
|
|
260
|
+
end
|
|
261
|
+
|
|
262
|
+
def kind_of(value)
|
|
263
|
+
case value
|
|
264
|
+
when true, false then :boolean
|
|
265
|
+
when ::Integer then :integer
|
|
266
|
+
when ::Numeric then :float
|
|
267
|
+
when ::String then :string
|
|
268
|
+
when ::Hash then :object
|
|
269
|
+
else :array
|
|
270
|
+
end
|
|
271
|
+
end
|
|
321
272
|
end
|
|
322
|
-
private_class_method :safe_attr
|
|
323
273
|
|
|
324
|
-
#
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
274
|
+
# INTERNAL: turns JSON keys into distinct, legal field names (FS-B136).
|
|
275
|
+
class Names
|
|
276
|
+
# @param key [String]
|
|
277
|
+
# @return [Array<String>] lowercase words of the key
|
|
278
|
+
def self.words(key)
|
|
279
|
+
spaced = key.gsub(/(?<=[A-Z])(?=[A-Z][a-z])/, ' ').gsub(/(?<=[a-z\d])(?=[A-Z])/, ' ')
|
|
280
|
+
spaced.split(/[^A-Za-z0-9]+/).reject(&:empty?)
|
|
281
|
+
end
|
|
282
|
+
|
|
283
|
+
def initialize
|
|
284
|
+
@used = []
|
|
285
|
+
end
|
|
286
|
+
|
|
287
|
+
# @param key [String] the JSON key
|
|
288
|
+
# @return [String] a field name no earlier key received
|
|
289
|
+
def field_name(key)
|
|
290
|
+
base = self.class.words(key).join('_').downcase
|
|
291
|
+
base = "field_#{base}" if base.empty? || base.match?(/\A\d/)
|
|
292
|
+
base = "#{base}_field" if KEYWORDS.include?(base) || FieldStruct::Base::RESERVED_FIELD_NAMES.include?(base.to_sym)
|
|
293
|
+
name = base
|
|
294
|
+
counter = 2
|
|
295
|
+
while @used.include?(name)
|
|
296
|
+
name = "#{base}#{counter}"
|
|
297
|
+
counter += 1
|
|
298
|
+
end
|
|
299
|
+
@used << name
|
|
300
|
+
name
|
|
301
|
+
end
|
|
328
302
|
end
|
|
329
|
-
private_class_method :blank_string?
|
|
330
303
|
end
|
|
331
304
|
end
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'did_you_mean'
|
|
4
|
+
|
|
5
|
+
module FieldStruct
|
|
6
|
+
# Builds the "did you mean" part of a declaration message, shared by field_struct and actionable-rb.
|
|
7
|
+
# @api private
|
|
8
|
+
module Suggestion
|
|
9
|
+
# The likeliest candidates for a misspelled word, at most two, best first.
|
|
10
|
+
#
|
|
11
|
+
# @param word [Symbol, String] what was written
|
|
12
|
+
# @param candidates [Array<Symbol, String>] what could have been meant
|
|
13
|
+
# @return [Array<String>] the picks, empty when nothing is close
|
|
14
|
+
def self.picks(word, candidates)
|
|
15
|
+
dictionary = candidates.map(&:to_s).uniq
|
|
16
|
+
DidYouMean::SpellChecker.new(dictionary: dictionary).correct(word.to_s).first(2)
|
|
17
|
+
end
|
|
18
|
+
|
|
19
|
+
# The picks for +word+ as a trailing clause, e.g. +" (did you mean :string?)"+.
|
|
20
|
+
#
|
|
21
|
+
# @param word [Symbol, String] what was written
|
|
22
|
+
# @param candidates [Array<Symbol, String>] what could have been meant
|
|
23
|
+
# @param sigil [String] written before each pick: +":"+ for Symbols, +""+ for option keys
|
|
24
|
+
# @param suffix [String] written after each pick, e.g. +":"+ for an option key
|
|
25
|
+
# @return [String] the clause with its leading space, or +""+ when nothing is close
|
|
26
|
+
def self.clause(word, candidates, sigil: ':', suffix: '')
|
|
27
|
+
found = picks(word, candidates)
|
|
28
|
+
return '' if found.empty?
|
|
29
|
+
|
|
30
|
+
" (did you mean #{found.map { |pick| "#{sigil}#{pick}#{suffix}" }.join(' or ')}?)"
|
|
31
|
+
end
|
|
32
|
+
end
|
|
33
|
+
end
|