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.
Files changed (70) hide show
  1. checksums.yaml +4 -4
  2. data/.claude-plugin/marketplace.json +13 -0
  3. data/.claude-plugin/plugin.json +9 -0
  4. data/AGENTS.md +47 -54
  5. data/CHANGELOG.md +53 -640
  6. data/LICENSE.txt +21 -0
  7. data/README.md +33 -628
  8. data/USAGE.md +771 -715
  9. data/docs/getting_started.md +139 -325
  10. data/lib/field_struct/base.rb +241 -1149
  11. data/lib/field_struct/class_macros.rb +163 -0
  12. data/lib/field_struct/describer.rb +167 -0
  13. data/lib/field_struct/errors.rb +182 -62
  14. data/lib/field_struct/exceptions.rb +40 -0
  15. data/lib/field_struct/field.rb +69 -135
  16. data/lib/field_struct/field_builder.rb +110 -0
  17. data/lib/field_struct/field_checks.rb +50 -0
  18. data/lib/field_struct/introspection.rb +199 -0
  19. data/lib/field_struct/json_codec.rb +240 -0
  20. data/lib/field_struct/metadata.rb +65 -260
  21. data/lib/field_struct/model_name.rb +27 -27
  22. data/lib/field_struct/option_checker.rb +121 -0
  23. data/lib/field_struct/partial.rb +49 -0
  24. data/lib/field_struct/presence.rb +45 -0
  25. data/lib/field_struct/rbs.rb +151 -271
  26. data/lib/field_struct/registered_option.rb +113 -0
  27. data/lib/field_struct/registry.rb +40 -50
  28. data/lib/field_struct/restrictions.rb +90 -0
  29. data/lib/field_struct/scaffold.rb +274 -301
  30. data/lib/field_struct/suggestion.rb +33 -0
  31. data/lib/field_struct/types/array.rb +147 -126
  32. data/lib/field_struct/types/base.rb +113 -124
  33. data/lib/field_struct/types/big_decimal.rb +59 -55
  34. data/lib/field_struct/types/binary.rb +18 -25
  35. data/lib/field_struct/types/boolean.rb +74 -97
  36. data/lib/field_struct/types/builtin.rb +32 -0
  37. data/lib/field_struct/types/date.rb +23 -137
  38. data/lib/field_struct/types/datetime.rb +30 -139
  39. data/lib/field_struct/types/element_options.rb +51 -0
  40. data/lib/field_struct/types/email.rb +27 -38
  41. data/lib/field_struct/types/float.rb +58 -56
  42. data/lib/field_struct/types/format_presets.rb +30 -0
  43. data/lib/field_struct/types/hash.rb +144 -0
  44. data/lib/field_struct/types/immutable_string.rb +16 -9
  45. data/lib/field_struct/types/integer.rb +74 -102
  46. data/lib/field_struct/types/nested.rb +57 -58
  47. data/lib/field_struct/types/preset_resolver.rb +9 -24
  48. data/lib/field_struct/types/rfc3339_format.rb +70 -153
  49. data/lib/field_struct/types/string.rb +48 -46
  50. data/lib/field_struct/types/symbol.rb +23 -20
  51. data/lib/field_struct/types/temporal.rb +232 -0
  52. data/lib/field_struct/types/time.rb +32 -145
  53. data/lib/field_struct/types/union.rb +111 -65
  54. data/lib/field_struct/types/union_pick.rb +139 -0
  55. data/lib/field_struct/types/url.rb +24 -35
  56. data/lib/field_struct/types/uuid.rb +24 -35
  57. data/lib/field_struct/types/value.rb +14 -9
  58. data/lib/field_struct/types/zone.rb +118 -0
  59. data/lib/field_struct/version.rb +3 -3
  60. data/lib/field_struct.rb +102 -122
  61. data/sig/field_struct.rbs +1180 -2300
  62. data/sig/manifest.yaml +6 -0
  63. data/skills/field-struct/SKILL.md +73 -159
  64. metadata +37 -28
  65. data/CODE_OF_CONDUCT.md +0 -132
  66. data/UPGRADING.md +0 -743
  67. data/lib/field_struct/error.rb +0 -48
  68. data/lib/field_struct/types/temporal_parser.rb +0 -93
  69. data/lib/field_struct/types/time_format_resolver.rb +0 -54
  70. 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
- # Scaffolds FieldStruct class source from one or more JSON example objects.
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
- # Matches an integer- or decimal-looking string (kept as +:string+, only hinted).
37
- # @return [Regexp]
38
- NUMERIC_STRING = /\A-?\d+(?:\.\d+)?\z/
39
- # Most distinct repeated string values before a field is flagged as an enum candidate.
40
- # @return [Integer]
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
- # Names a scaffolded attribute can't take (suffixed with +_field+): Ruby
43
- # keywords, plus {Base::RESERVED_FIELD_NAMES}, which +field+ refuses.
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
- # @param input [String, Hash{Object=>Object, nil}, Array<Hash{Object=>Object, nil}>]
70
- # @return [Array<Object>] the sample set (a lone object becomes a set of
71
- # one); {.from_json} checks every element is a Hash
72
- def self.normalize(input)
73
- data = input.is_a?(::String) ? Oj.load(input, mode: :strict) : input
74
- case data
75
- when ::Array then data
76
- when ::Hash then [data]
77
- else
78
- raise ArgumentError, "expected a JSON object or array of objects, got #{data.class}"
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
- end
81
- private_class_method :normalize
82
-
83
- # Build the class for +samples+ as +class_name+, appending nested classes
84
- # to +classes+ first (post-order, so references resolve), and return the
85
- # (deduplicated) class name used.
86
- #
87
- # @param class_name [String] the name wanted
88
- # @param samples [Array<Hash{Object=>Object, nil}>]
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
- classes << build_class(name, mappings, lines)
105
- name
106
- end
107
- private_class_method :emit_object
108
-
109
- # @param samples [Array<Hash{Object=>Object, nil}>]
110
- # @param key [Object] a sample key
111
- # @return [Hash{Symbol=>Integer, Array<Object, nil>}] +{ present: Integer, values: Array }+
112
- # for +key+ across samples
113
- def self.observe(samples, key)
114
- present = samples.select { |sample| sample.key?(key) }
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
- # @param values [Array<Object>] non-nil scalar sample values
172
- # @return [Array(Symbol, String)] inferred scalar type and a comment hint
173
- def self.infer_scalar(values)
174
- return [:string, 'always null/absent in samples — type unknown'] if values.empty?
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
- kinds = values.map { |v| scalar_kind(v) }.uniq
177
- return [:boolean, nil] if kinds == [:boolean]
178
- return [:integer, nil] if kinds == [:integer]
179
- return [:float, nil] if (kinds - %i[integer float]).empty?
180
- return string_inference(values) if kinds == [:string]
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
- [:value, "mixed types in samples (#{kinds.join(", ")}) — review"]
183
- end
184
- private_class_method :infer_scalar
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
- # @param values [Array<String>]
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
- if non_empty.all? { |s| s.match?(NUMERIC_STRING) }
193
- suggestion = non_empty.any? { |s| s.include?('.') } ? ':big_decimal' : ':integer'
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
- distinct = non_empty.uniq
198
- if non_empty.length >= 3 && distinct.length < non_empty.length && distinct.length <= ENUM_MAX_DISTINCT
199
- return [:string, "values: #{distinct.inspect} — enum?"]
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
- [:string, nil]
203
- end
204
- private_class_method :string_inference
205
-
206
- # @param value [Object]
207
- # @return [Symbol] +:boolean+, +:integer+, +:float+, +:string+ or +:other+
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
- end
217
- private_class_method :scalar_kind
218
-
219
- # +serialize+ refuses undeclared fields, so the mapping goes after them.
220
- #
221
- # @param name [String] the class name
222
- # @param mappings [Hash{String=>Object}] attribute name → original sample key
223
- # @param lines [Array<String>] the field lines
224
- # @return [String] the class source
225
- def self.build_class(name, mappings, lines)
226
- body = lines.dup
227
- body << ' # (no fields detected in samples)' if body.empty?
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
- "class #{name} < FieldStruct::Base\n#{body.join("\n")}\nend"
233
- end
234
- private_class_method :build_class
235
-
236
- # @param declaration [String] the DSL call, without indentation
237
- # @param comment_parts [String, nil] trailing-comment fragments; nil and
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
- end
270
- private_class_method :ordered_keys
271
-
272
- # @param base [String] the name wanted
273
- # @param used [Array<String>] names taken so far (appended to)
274
- # @return [String] +base+, or +base+ with a numeric suffix
275
- def self.unique_name(base, used)
276
- name = base
277
- suffix = 1
278
- while used.include?(name)
279
- suffix += 1
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
- # @param str [String]
297
- # @return [String]
298
- def self.camelize(str)
299
- str.to_s.split(/[^a-zA-Z0-9]+/).reject(&:empty?).map { |part| part[0].upcase + (part[1..] || '') }.join
300
- end
301
- private_class_method :camelize
302
-
303
- # Naive: strip one trailing "s". Good enough for a prototype name; the
304
- # developer renames as needed.
305
- #
306
- # @param str [String]
307
- # @return [String]
308
- def self.singularize(str)
309
- str.end_with?('s') && str.length > 1 ? str[0..-2] : str
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
- private_class_method :singularize
312
-
313
- # @param key [Object] a sample key
314
- # @return [String] a snake_case attribute name that +field+ accepts
315
- def self.safe_attr(key)
316
- attr = key.to_s.gsub(/([a-z\d])([A-Z])/, '\1_\2').gsub(/[^a-zA-Z0-9]+/, '_').downcase
317
- attr = attr.sub(/\A_+/, '').sub(/_+\z/, '')
318
- attr = "field_#{attr}" if attr.empty? || attr.match?(/\A\d/)
319
- attr = "#{attr}_field" if RESERVED.include?(attr)
320
- attr
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
- # @param value [Object, nil]
325
- # @return [Boolean]
326
- def self.blank_string?(value)
327
- value.is_a?(::String) && value.strip.empty?
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