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
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 1ebdb327e4ca03c28fdf761a124ac8e69ebfe053ff6415e7b09f76b95316e4d8
4
- data.tar.gz: 2728f46e3b638b3a5a602bd2a3094a82663f9ec92e4de32e0b393c4d6fa1d62e
3
+ metadata.gz: 02cc3b3e1caf64e1065d794d12fea26ac7ed803b63c885a1f504135260ded56f
4
+ data.tar.gz: 1f81800a6a3e1ed0a23ff1208f11f32fdc6e19f056b327dbd7c595c3dc6bdd2d
5
5
  SHA512:
6
- metadata.gz: 770377dc647aeba20b93759308fee46dcf5a52d0bd51324f65779a769415e0adc57bce23a3dae18814519c9d96d3ef520ede07b50173cde18dcf7819c246898c
7
- data.tar.gz: 4beb8782870e63c29f2f0d204d5f771ac70337a26663af8e808ac470c02023ddb94bbe0822dc744d968a1532dd00fba3d0bc48b46d1b28e9ff0634bcec5c202b
6
+ metadata.gz: 9547d189893eefca7ea0896f2823331709e94e0f9e4ba370234f08b0ec03a340df879ada14dfe4da6e41cd5aad04bb1c9ea0620bfb7ba095d08a7345d8e87b14
7
+ data.tar.gz: 5df7b25530165495ba2c0c26d730f670c5d8be36e911b0ffc10eb27dc31fb0d41c81dea9eca476c20a6f2140900e82ba838024864d45f777e37bb927e95e09e6
@@ -0,0 +1,13 @@
1
+ {
2
+ "name": "field-struct",
3
+ "owner": {
4
+ "name": "Adrian Madrid"
5
+ },
6
+ "plugins": [
7
+ {
8
+ "name": "field-struct",
9
+ "source": "./",
10
+ "description": "Skill for defining, debugging and typing Ruby models built with the field_struct gem."
11
+ }
12
+ ]
13
+ }
@@ -0,0 +1,9 @@
1
+ {
2
+ "name": "field-struct",
3
+ "description": "Skill for defining, debugging and typing Ruby models built with the field_struct gem.",
4
+ "author": {
5
+ "name": "Adrian Madrid"
6
+ },
7
+ "license": "MIT",
8
+ "skills": "./skills"
9
+ }
data/AGENTS.md CHANGED
@@ -1,58 +1,51 @@
1
- # Working with the field_struct gem
1
+ # AGENTS.md
2
2
 
3
- This repo provides **FieldStruct** — a Ruby gem for typed POROs (declared fields with
4
- coercion and validation). This file routes AI coding agents to the right docs and the
5
- things most often gotten wrong. (For *contributing to the gem itself*, see
6
- `CLAUDE.md`.)
3
+ Guide for coding agents using the `field_struct` gem. Short on purpose; the details live in the files below.
7
4
 
8
5
  ## Read these
9
6
 
10
- - **[`docs/getting_started.md`](docs/getting_started.md)** — how to use it in a repo
11
- (general Ruby + Rails): a task→API map, an error→fix table, and a worked example.
12
- - **[`USAGE.md`](USAGE.md)** — dense reference: every type, option, and macro.
13
- - **[`README.md`](README.md)** — feature overview.
14
- - **[`UPGRADING.md`](UPGRADING.md)** — moving to a newer version: symptom, Find, fix.
15
- - `skills/field-struct/SKILL.md` — the bundled Claude Code skill.
16
-
17
- ## The six gotchas
18
-
19
- 1. **Setters are permissive** — `user.age = "30"` is valid (the type coerces). Don't "fix" it.
20
- 2. **`required` ≠ non-nil at runtime** — an invalid instance can hold `nil`. Gate on `valid?`.
21
- 3. **Whitespace-only strings count as missing** for `:string` and its subtypes.
22
- 4. **`:array` needs `of:`; `:union` needs `of: [...]`** (≥2 members).
23
- 5. **Option scoping**: `format:`→string/date-ish, `enum:`→string/symbol, `in:`→numeric/temporal, `round:`→float/decimal, `base:`→integer, `strict:`→string-shaped/integer, `zone:`→time/datetime, `values:`→boolean, `element:`→array (a Hash of the element type's options); `sensitive:` works on any type. A misapplied known option raises at class load and names the types it applies to; an *unknown* option passes through onto the Field untouched (kept for downstream tooling). You don't have to memorize this table — ask the type (next section).
24
- 6. **`valid?` is computed on assignment, not on read.** Mutating a nested struct or an array element in place doesn't refresh the parent's errors. Assign the field again (or use `with`) to re-validate. See [USAGE](USAGE.md#validity-is-computed-on-assignment-shallow-valid-staleness).
25
-
26
- ## Upgrading
27
-
28
- Moving a project to a newer field_struct? [`UPGRADING.md`](UPGRADING.md) lists every
29
- visible change since 0.10 with a symptom, a Find command, and a fix. Procedure:
30
-
31
- 1. Read your old version from `Gemfile.lock` (`field_struct (x.y.z)`) and the target
32
- tag. Open `UPGRADING.md` (repo root, or `bundle show field_struct` after bumping)
33
- and read every section from the one after your old version to the target.
34
- 2. Bump the Gemfile tag. If the project uses **actionable** >= 1.6, field_struct
35
- must be >= 0.12 (its gemspec says so); if `oj` is pinned below 3.11.2, loosen it.
36
- `bundle update field_struct`.
37
- 3. Check `rg --pcre2-version` works in your shell. Run the Find of every entry
38
- the TL;DR lists as **silent**, from the project root, and read each hit using the
39
- entry's narrowing rule. Run the other entries' Finds only for code the suite
40
- doesn't reach; those changes raise or fail a spec.
41
- 4. Apply the matching **Fix** to each real hit. Don't change behaviour you weren't
42
- asked to — e.g. keep a renamed reserved field's wire name with `serialize :json`.
43
- 5. Run the full suite. Match each failure against UPGRADING.md's symptom index and
44
- fix it; if nothing matches, follow its "If something else breaks" section.
45
- 6. If the project generates RBS with `FieldStruct::RBS.generate`, or with a task that
46
- wraps it (`rg -n 'FieldStruct::RBS' lib Rakefile`), regenerate it and run Steep if
47
- the project does.
48
- 7. Report: old → new version, each entry that applied (file:line, fix), each Find
49
- with no hits, and anything left unexplained.
50
-
51
- ## Fast paths
52
-
53
- - Bootstrap a model from a JSON sample: `FieldStruct::Scaffold.from_json(json)`.
54
- - See a model's shape without reading source: `pp Klass.metadata.to_h` (structured), or `puts Klass.describe` (readable — fields, types, and what each accepts).
55
- - Ask a type what options it accepts (name, value shape, presets): `FieldStruct.types.lookup(:date).option_schema`.
56
- - Type your models for Steep/Solargraph: `FieldStruct::RBS.generate(Klass)`.
57
- - "Update" an immutable or frozen instance: `record.with(field: value)` returns a changed copy.
58
- - Payment/API input: `unknown_attributes :raise` on every struct that reads it, `strict: true` on money and id fields, `sensitive: true` on card data. See [USAGE](USAGE.md#payment-and-api-boundaries-unknown_attributes-raise).
7
+ - [USAGE.md](USAGE.md): the reference. Every type, option and macro, with examples. Read it once before writing a model.
8
+ - [docs/getting_started.md](docs/getting_started.md): task-to-API map, what each error means and how to fix it, common mistakes, Rails.
9
+ - [README.md](README.md): overview and the type and option tables.
10
+ - [skills/field-struct/SKILL.md](skills/field-struct/SKILL.md): the same guidance as a Claude Code skill.
11
+
12
+ ## A model in four lines
13
+
14
+ ```ruby
15
+ class Plant < FieldStruct::Base
16
+ required :species, :string
17
+ optional :leaves, :integer, in: 1..5000
18
+ end
19
+ ```
20
+
21
+ ## Gotchas
22
+
23
+ 1. **Setters are permissive.** A bad value is stored as given and recorded in `errors`. Nothing raises unless the class
24
+ says `coercion_policy :raise`. Always check `valid?`.
25
+ 2. **`required` doesn't mean non-nil.** It means `valid?` fails when the value is missing. An unset required field reads
26
+ as `nil`.
27
+ 3. **Whitespace-only strings, empty arrays and empty hashes are missing** for `required` (not for `:binary` or `:value`).
28
+ 4. **`of:` is required** on `:array`, `:hash` and `:union`. A missing one raises at declaration.
29
+ 5. **Options are scoped to types.** `round:` is for numbers, `format:` for strings and dates, `enum:` for strings and
30
+ symbols. Options for array elements go in `element: {...}`.
31
+ 6. **Cross-field rules go to `errors[:base]`**, from a `validate` method or block.
32
+ 7. **JSON goes through Oj.** Use `to_json`, `as_json` and `from_json`; don't use `JSON.generate` on a struct.
33
+ 8. **Unknown keys are ignored** by default. Use `unknown_attributes :raise` to fail on them.
34
+ 9. **Messages never echo the value**, only its class. `inspect` does show values unless the field is `sensitive: true`.
35
+ 10. **Validity goes stale.** It's computed on assignment. Mutating a nested object in place doesn't refresh the parent.
36
+ 11. **Copy with `with(**changes)`.** It takes keywords, returns a new object, and is the way to "change" an
37
+ `immutable!` or `frozen!` one.
38
+
39
+ ## Working on this gem
40
+
41
+ ```
42
+ bundle exec rake # specs and RuboCop (fast)
43
+ bundle exec rake release:check # adds doctests, signature checks, the docs check and the YARD build
44
+ bundle exec rake sigs:generate # after changing any YARD comment: regenerate sig/field_struct.rbs and commit it
45
+ ```
46
+
47
+ Public methods need short YARD comments with types. Inside `FieldStruct::Types`, write stdlib names with a leading `::`
48
+ (`::String`, `::Hash{::Symbol=>::Object}`). The signature file is generated, never edited by hand.
49
+ A change to `lib/` needs a CHANGELOG entry under `[Unreleased]`. The docs check fails when a public method or a field
50
+ option isn't named in code on USAGE.md and the site reference; a method that is public only for the gem's own use gets
51
+ `# @api private` instead.