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,85 +1,75 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module FieldStruct
4
- # Name → type-class map with optional parent fallback.
5
- #
6
- # Holds the resolution table that maps symbolic type names (`:string`,
7
- # `:integer`, …) to the {Types} classes that implement them. A namespace
8
- # can build its own registry parented to the base ({FieldStruct.types})
9
- # to extend or override the default set without mutating it.
4
+ # Maps type names (Symbols) to type classes, with an optional parent to fall back to.
10
5
  class Registry
11
- # @return [Registry, nil] the parent registry, or +nil+ for an unparented one
6
+ # @return [FieldStruct::Registry, nil]
12
7
  attr_reader :parent
13
8
 
14
- # @param parent [Registry, nil] the registry to fall back to when a name
15
- # isn't found locally
9
+ # @param parent [FieldStruct::Registry, nil]
16
10
  def initialize(parent = nil)
17
11
  @parent = parent
18
- @types = {}
12
+ @entries = {}
19
13
  end
20
14
 
21
- # Register a type class — or an alias to an already-registered name.
15
+ # Registers a type class, or an alias to an already registered name.
16
+ # An alias is resolved now, so re-registering its target later does not move it.
22
17
  #
23
- # registry.register(:integer, MyInteger) # type class
24
- # registry.register(:decimal, :big_decimal) # alias (resolved now)
25
- #
26
- # Aliases are eagerly resolved through {#lookup}, so the alias target
27
- # must already be registered (locally or in a parent). A later
28
- # registration of the same name overwrites silently — this is the
29
- # mechanism that lets a namespace registry shadow a parent's type.
30
- #
31
- # @param name [Symbol, String] the name to register
32
- # @param target [Class, Symbol] a type class, or an existing registered name
18
+ # @param name [Symbol, String]
19
+ # @param target [Class, Symbol, String] a type class, or the name to alias
33
20
  # @return [self]
34
- # @raise [KeyError] when +target+ is a Symbol that isn't registered yet
21
+ # @raise [KeyError] when an alias target is unknown
35
22
  def register(name, target)
36
- type_class = target.is_a?(::Symbol) ? lookup(target) : target
37
- @types[name.to_sym] = type_class
23
+ @entries[name.to_sym] = target.is_a?(Class) ? target : lookup(target)
38
24
  self
39
25
  end
40
26
 
41
- # Resolve a name to its type class, walking the parent chain.
42
- #
43
27
  # @param name [Symbol, String]
44
- # @return [Class] the type class
45
- # @raise [KeyError] when the name isn't registered locally or via the parent chain
28
+ # @return [Class]
29
+ # @raise [KeyError] when no registry in the chain knows the name
46
30
  def lookup(name)
47
31
  key = name.to_sym
48
- return @types[key] if @types.key?(key)
49
- return @parent.lookup(key) if @parent
32
+ return @entries[key] if @entries.key?(key)
33
+ return @parent.lookup(key) if @parent&.key?(key)
34
+
35
+ raise KeyError, "no FieldStruct type registered for #{key.inspect}#{Suggestion.clause(key, names)}"
36
+ end
50
37
 
51
- raise ::KeyError, "no FieldStruct type registered for #{name.inspect}"
38
+ # Every name resolvable here, own first, then the parent's, each once.
39
+ # @api private
40
+ #
41
+ # @return [Array<Symbol>]
42
+ def names
43
+ (@entries.keys + (@parent ? @parent.names : [])).uniq
52
44
  end
53
45
 
54
- # Whether the name resolves to anything (locally or via the parent chain).
46
+ # The first name (in chain order) whose type has the same short class name as +klass+, e.g. +:string+ for String.
47
+ # @api private
55
48
  #
49
+ # @param klass [Class] a class given as a type that is not one
50
+ # @return [Symbol, nil]
51
+ def name_for_lookalike(klass)
52
+ short = klass.name.to_s.split('::').last
53
+ return nil if short.nil? || short.empty?
54
+
55
+ names.find { |name| lookup(name).name.to_s.split('::').last == short }
56
+ end
57
+
56
58
  # @param name [Symbol, String]
57
- # @return [Boolean]
59
+ # @return [Boolean] whether this registry or an ancestor knows the name
58
60
  def key?(name)
59
61
  key = name.to_sym
60
- return true if @types.key?(key)
61
-
62
- !@parent.nil? && @parent.key?(key)
62
+ @entries.key?(key) || (@parent ? @parent.key?(key) : false)
63
63
  end
64
64
 
65
- # Every distinct type class resolvable through this registry, including
66
- # those inherited from the parent chain. Local entries come first;
67
- # duplicates (e.g. an alias pointing at an already-listed class, or a
68
- # parent class also registered locally) are removed.
69
- #
70
- # @return [Array<Class>] deduplicated, local-first
65
+ # @return [Array<Class>] distinct classes resolvable here: own first, then the parent's
71
66
  def type_classes
72
- own = @types.values
73
- (@parent ? own + @parent.type_classes : own).uniq
67
+ (@entries.values + (@parent ? @parent.type_classes : [])).uniq
74
68
  end
75
69
 
76
- # @return [String] one-line summary of the locally-registered names
77
- # (does not enumerate the parent chain), with a +parent+ marker
78
- # when the registry has one
70
+ # @return [String]
79
71
  def inspect
80
- parts = ["types=#{@types.keys.inspect}"]
81
- parts << 'parent' if @parent
82
- "#<#{FieldStruct.inspect_namespace}::Registry #{parts.join(" ")}>"
72
+ "#<#{FieldStruct.inspect_namespace}::Registry types=#{@entries.keys.inspect}#{' parent' if @parent}>"
83
73
  end
84
74
  end
85
75
  end
@@ -0,0 +1,90 @@
1
+ # frozen_string_literal: true
2
+
3
+ module FieldStruct
4
+ # The value checks a field's +format:+ (Regexp), +enum:+, +in:+ and +length:+ options describe.
5
+ module Restrictions
6
+ # The one message a broken restriction gives: the +length:+ message wins (FS-B37a), else +"is invalid"+.
7
+ #
8
+ # @param value [Object] an already coerced value
9
+ # @param options [Hash{Symbol=>Object}] the field's (or element's) options
10
+ # @return [String, nil] +nil+ when nothing is broken; +nil+ never breaks a restriction
11
+ def self.problem(value, options)
12
+ return nil if value.nil?
13
+
14
+ too = size_message(value, options)
15
+ too || ('is invalid' if format_broken?(value, options[:format]) || enum_broken?(value, options[:enum]) ||
16
+ range_broken?(value, options[:in]))
17
+ end
18
+
19
+ # The specific message for a value outside its +length:+ bounds (FS-B37a). It names the declared limit, never the value.
20
+ #
21
+ # @param value [String] an already coerced value
22
+ # @param bounds [Range, nil] the field's +length:+
23
+ # @return [String, nil] +nil+ when there is no bound or the value is within it
24
+ # +length:+ on a String, +max_items:+ on an Array (FS-B168), or nil.
25
+ def self.size_message(value, options)
26
+ return length_message(value, options[:length]) if value.is_a?(::String)
27
+
28
+ limit = options[:max_items]
29
+ "has too many items (maximum is #{limit})" if limit && value.is_a?(::Array) && value.size > limit
30
+ end
31
+
32
+ def self.length_message(value, bounds)
33
+ return nil if bounds.nil?
34
+
35
+ size = value.length
36
+ min = bounds.begin
37
+ return "is too short (minimum is #{min})" if min && size < min
38
+
39
+ max = length_max(bounds)
40
+ "is too long (maximum is #{max})" if max && size > max
41
+ end
42
+
43
+ # @param bounds [Range]
44
+ # @return [Boolean] whether each end is an Integer >= 0 or nil, at least one is set, and the Range is not empty
45
+ def self.usable_length?(bounds)
46
+ return false unless whole_ends?(bounds)
47
+
48
+ max = length_max(bounds)
49
+ bounds.begin.nil? || max.nil? || bounds.begin <= max
50
+ end
51
+
52
+ # @param bounds [Range]
53
+ # @return [Boolean] each end is an Integer >= 0 or nil, and at least one is set
54
+ def self.whole_ends?(bounds)
55
+ ends = [bounds.begin, bounds.end]
56
+ ends.all? { |n| n.nil? || (n.is_a?(::Integer) && n >= 0) } && ends.any?
57
+ end
58
+
59
+ # @param bounds [Range]
60
+ # @return [Integer, nil] the largest allowed length; an exclusive end allows one less
61
+ def self.length_max(bounds)
62
+ last = bounds.end
63
+ last && bounds.exclude_end? ? last - 1 : last
64
+ end
65
+
66
+ def self.format_broken?(value, format)
67
+ format.is_a?(::Regexp) && !format.match?(value.to_s)
68
+ end
69
+
70
+ def self.enum_broken?(value, enum)
71
+ !enum.nil? && !enum.include?(value)
72
+ end
73
+
74
+ def self.range_broken?(value, bounds)
75
+ return false if bounds.nil?
76
+
77
+ bounds.is_a?(::Range) ? !bounds.cover?(comparable(value, bounds)) : !bounds.include?(value)
78
+ end
79
+
80
+ # A DateTime compared with plain Date endpoints counts as its calendar date, so 15:00 on the last day is inside.
81
+ def self.comparable(value, range)
82
+ return value unless value.is_a?(::DateTime)
83
+
84
+ plain_date = ->(endpoint) { endpoint.is_a?(::Date) && !endpoint.is_a?(::DateTime) }
85
+ plain_date.call(range.begin) || plain_date.call(range.end) ? ::Date.new(value.year, value.mon, value.mday) : value
86
+ end
87
+
88
+ private_class_method :format_broken?, :enum_broken?, :range_broken?, :comparable, :length_max, :whole_ends?
89
+ end
90
+ end