schema-model 0.6.11 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0604e96e9d70ef3b47b7581ef0c6c43005960af46dde776565700abf86482ad5
-  data.tar.gz: cdfdbf20d77cfd81521df44308083b1134062c19e041752a2a194ee05c420c4d
+  metadata.gz: 274769a5b3652ece9a8c2583a8867310882800377563f7e5e8eb387a219ea4a3
+  data.tar.gz: f42a01e476eeb0101df7e5fbaa8bb9fde390637016876ed749a1f1f850d0ae0e
 SHA512:
-  metadata.gz: 590a840b90865bc31c4c75c0f34f10135c9d410532c6585d64afa20e39f712262bb43794cea9414877eb8df3602567cf057deb75867d9436eea0315a313aea15
-  data.tar.gz: 0d9b8ee1ba799df269f396c68692e9210f90bde87192f3f121809a42db99647630b12c5624ed108ff58079a661a1f51b6547e876797dc32a0a887ebb7bcbfc41
+  metadata.gz: cef6b96d50da9c84ac9b80afd6c74f6f941668eecea8d7d6dd5260e3e73b0163f7906deb86af4f7bca141efbdccd3fffa2d12d6955fa7986ccc889c89c472194
+  data.tar.gz: 4372f3250e704cc8569411659663fc946ab3f87b2ea7a6255aca7966dde8dbcff8e2ef8eec50ece7aa3bba5f4ebc01ea352219f79c743db32974663f807e5440

data/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  lint:
+    name: RuboCop
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: true
+
+      - name: Run RuboCop
+        run: bundle exec rubocop --format github
+
+  test:
+    name: Tests (Ruby ${{ matrix.ruby }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ['3.2', '3.3', '3.4']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby ${{ matrix.ruby }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Run tests
+        run: bundle exec rspec
+
+      - name: Upload coverage to Codecov
+        if: matrix.ruby == '3.4'
+        uses: codecov/codecov-action@v4
+        with:
+          files: coverage/coverage.xml
+          fail_ci_if_error: false
+          verbose: true
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

data/.rubocop.yml

@@ -1,11 +1,73 @@
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - 'bin/**/*'
+    - 'vendor/**/*'
+    - 'coverage/**/*'
+
+# Relaxed metrics for existing codebase
+Metrics/MethodLength:
+  Max: 35
+
+Metrics/AbcSize:
+  Max: 40
+
+Metrics/ClassLength:
+  Max: 200
+
+Metrics/ModuleLength:
+  Max: 200
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+Metrics/PerceivedComplexity:
+  Max: 15
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - '*.gemspec'
+
+# Style preferences
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  EnforcedStyle: always
+
+Layout/LineLength:
+  Max: 130
+  Exclude:
+    - 'spec/**/*'
+
+# File naming - allow hyphenated gem name
 Naming/FileName:
+  Exclude:
+    - 'lib/schema-model.rb'
+
+# Gemspec settings
+Gemspec/RequiredRubyVersion:
   Enabled: false
-Metrics/LineLength:
-  Max: 120
-Metrics/ModuleLength:
-  Max: 120
-Metrics/MethodLength:
-  Max: 20
-AllCops:
+
+# DSL methods following ActiveRecord conventions (has_one, has_many)
+Naming/PredicatePrefix:
   Exclude:
-    - 'spec/**/*_spec.rb'
+    - 'lib/schema/associations/has_one.rb'
+    - 'lib/schema/associations/has_many.rb'
+    - 'lib/schema/associations/schema_creator.rb'
+
+# Dynamic eval is used for metaprogramming in this DSL gem
+Style/DocumentDynamicEvalDefinition:
+  Enabled: false
+
+# Short parameter names acceptable in simple setters
+Naming/MethodParameterName:
+  AllowedNames:
+    - v
+
+# Boolean parameters acceptable in internal methods
+Style/OptionalBooleanParameter:
+  Enabled: false

data/ARCHITECTURE.md

@@ -0,0 +1,135 @@
+# Architecture
+
+This document describes the internal architecture of the `schema-model` gem.
+
+## Overview
+
+The gem transforms hash data into strongly-typed Ruby objects with parsing, validation, and nested associations. The core flow is:
+
+```
+Hash Data → from_hash() → Parser Methods → Schema Instance
+                              ↓
+                      parsing_errors (if invalid)
+```
+
+## Module Hierarchy
+
+```
+Schema::All (convenience bundle)
+    ├── Schema::Model (core attribute system)
+    ├── Schema::Associations::HasOne
+    ├── Schema::Associations::HasMany
+    ├── Schema::Parsers::Common
+    ├── Schema::Parsers::American
+    ├── Schema::Parsers::Array
+    ├── Schema::Parsers::Hash
+    ├── Schema::Parsers::Json
+    └── Schema::ActiveModelValidations
+```
+
+## Core Components
+
+### Schema::Model (`lib/schema/model.rb`)
+
+The foundation module providing:
+
+- **`attribute(name, type, options)`**: Defines schema fields. Each call:
+  1. Adds field metadata to the class's `schema` hash via `add_value_to_class_method`
+  2. Generates getter, setter, and `<name>_was_set?` methods
+  3. Setter invokes `parse_<type>` method automatically
+
+- **`from_hash(data, skip_fields)`**: Class method that creates instance and calls `update_attributes`
+
+- **`update_attributes(data, skip_fields)`**: Iterates hash keys, matches against schema, invokes setters
+
+- **`as_json` / `to_hash`**: Serialization back to hash format
+
+### Schema::Parsers::Common (`lib/schema/parsers/common.rb`)
+
+Base parser methods for fundamental types:
+- `parse_integer`, `parse_float`, `parse_string`, `parse_string_or_nil`
+- `parse_boolean`, `parse_time`, `parse_date`
+
+Each parser:
+1. Accepts `(field_name, parsing_errors, value)`
+2. Returns converted value or nil
+3. Adds to `parsing_errors` on failure (never raises)
+
+Additional parsers extend these: `Parsers::American` (date formats), `Parsers::Array`, `Parsers::Hash`, `Parsers::Json`.
+
+### Schema::Associations (`lib/schema/associations/`)
+
+**HasOne** and **HasMany** define nested relationships:
+
+```ruby
+has_one(:profile) { attribute :bio, :string }
+has_many(:posts) { attribute :title, :string }
+```
+
+Both use **SchemaCreator** (`schema_creator.rb`) to:
+1. Determine which class to instantiate (static or dynamic)
+2. Call `from_hash` on the nested class
+3. Propagate parsing errors to parent
+
+**DynamicTypes** enables polymorphic associations:
+
+```ruby
+has_many(:items, type_field: :kind) do
+  add_type('widget') { attribute :size, :integer }
+  add_type('gadget') { attribute :power, :float }
+  default_type { } # fallback
+end
+```
+
+The `type_field` option tells SchemaCreator which data key determines the subclass.
+
+### Schema::Utils (`lib/schema/utils.rb`)
+
+Utility methods for:
+- `classify_name`: String → ClassName conversion
+- `create_schema_class`: Dynamically creates nested schema classes
+- `add_association_class`: Wires up association with proper modules
+- `add_attribute_default_methods` / `add_association_default_methods`: Default value handling
+
+### Error Handling
+
+Two error storage mechanisms:
+
+1. **Schema::Errors** (`lib/schema/errors.rb`): Simple hash-based storage, used standalone
+
+2. **ActiveModel::Errors**: When `Schema::ActiveModelValidations` is included, `parsing_errors` returns `ActiveModel::Errors` instance
+
+Parsing errors are distinct from validation errors:
+- **Parsing errors**: Type conversion failures (string "abc" → integer)
+- **Validation errors**: Business rule failures (via `validates` DSL)
+
+Methods `parsed!` and `valid!` raise `ParsingException`/`ValidationException` respectively.
+
+### Inheritance Helper Integration
+
+The gem uses `inheritance-helper` for schema inheritance. Key method:
+- `add_value_to_class_method(:schema, name => options)`: Accumulates schema definitions across class hierarchy
+
+This allows schema classes to inherit attributes from parent classes.
+
+## Data Flow Example
+
+```ruby
+class OrderSchema
+  include Schema::All
+  attribute :total, :float
+  has_one(:customer) { attribute :name, :string }
+end
+
+order = OrderSchema.from_hash({
+  total: "99.50",
+  customer: { name: "Alice" }
+})
+```
+
+1. `from_hash` calls `new.update_attributes(data)`
+2. `update_attributes` iterates keys, finds `:total` in schema
+3. Calls `self.total = "99.50"` → invokes `parse_float`
+4. For `:customer`, recognizes association, delegates to SchemaCreator
+5. SchemaCreator calls `OrderSchema::SchemaHasOneCustomer.from_hash({name: "Alice"})`
+6. Returns populated `OrderSchema` instance

data/CLAUDE.md

@@ -0,0 +1,74 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build and Test Commands
+
+```bash
+# Install dependencies
+bundle install
+
+# Run all tests
+bundle exec rspec
+
+# Run a single test file
+bundle exec rspec spec/schema/model_spec.rb
+
+# Run a specific test by line number
+bundle exec rspec spec/schema/model_spec.rb:42
+
+# Run linter
+bundle exec rubocop
+
+# Auto-fix linter issues
+bundle exec rubocop -A
+```
+
+## Architecture
+
+This is a Ruby gem (`schema-model`) for data transformation, validation, and type safety. It transforms hash data into strongly-typed model objects.
+
+### Core Module Structure
+
+- **Schema::Model** (`lib/schema/model.rb`) - Foundation module providing `attribute` definitions, `from_hash` class method, and attribute accessors.
+
+- **Schema::All** (`lib/schema/all.rb`) - Convenience module bundling Model + Associations + Parsers + ActiveModel validations. This is the typical include.
+
+- **Schema::Parsers** - Type parsers in `lib/schema/parsers/`:
+  - `Common` - integer, string, float, time, date, boolean
+  - `American` - american_date, american_time (MM/DD/YYYY format)
+  - `Array` - array with optional separator and data_type
+  - `Hash` - hash/dictionary values
+  - `Json` - JSON string parsing
+
+- **Schema::Associations** - `HasOne` and `HasMany` for nested relationships. `DynamicTypes` enables polymorphic associations via `type_field`/`add_type`.
+
+- **Schema::Arrays** (`lib/schema/arrays.rb`) - Convert models to/from flat arrays for CSV support.
+
+- **Schema::ArrayHeaders** (`lib/schema/array_headers.rb`) - Map CSV headers to schema attributes.
+
+### Key Patterns
+
+**Attribute Definition**: Each `attribute` call generates getter, setter, and `<name>_was_set?` predicate. Setter invokes type-specific parser.
+
+**Parsing Errors**: Stored in `parsing_errors`. Parsers add errors for invalid values rather than raising exceptions. With ActiveModelValidations, use `parsed?`/`parsed!`.
+
+**Schema Inheritance**: Uses `inheritance-helper` gem. Schema definitions accumulate via `add_value_to_class_method(:schema, ...)`.
+
+**Dynamic Types**: For polymorphic associations, use `type_field` option with `add_type` blocks. Supports `external_type_field`, `type_ignorecase`, and `default_type`.
+
+## Code Commits
+
+Format using angular formatting:
+```
+<type>(<scope>): <short summary>
+```
+- **type**: build|ci|docs|feat|fix|perf|refactor|test
+- **scope**: The feature or component of the service we're working on
+- **summary**: Summary in present tense. Not capitalized. No period at the end.
+
+## Documentation Maintenance
+
+When modifying the codebase, keep documentation in sync:
+- **ARCHITECTURE.md** - Update when adding/removing classes, changing component relationships, or altering data flow patterns
+- **README.md** - Update when adding new features, changing public APIs, or modifying usage examples

data/Gemfile

@@ -7,11 +7,11 @@ gem 'inheritance-helper'
 group :development do
   gem 'activemodel'
   gem 'csv'
-  gem 'rake'
   gem 'rubocop'
 end
 
 group :spec do
   gem 'rspec'
   gem 'simplecov'
+  gem 'simplecov-cobertura'
 end

data/Gemfile.lock

@@ -1,62 +1,62 @@
 GEM
   remote: http://rubygems.org/
   specs:
-    activemodel (8.0.2)
-      activesupport (= 8.0.2)
-    activesupport (8.0.2)
+    activemodel (8.1.2)
+      activesupport (= 8.1.2)
+    activesupport (8.1.2)
       base64
-      benchmark (>= 0.3)
       bigdecimal
       concurrent-ruby (~> 1.0, >= 1.3.1)
       connection_pool (>= 2.2.5)
       drb
       i18n (>= 1.6, < 2)
+      json
       logger (>= 1.4.2)
       minitest (>= 5.1)
       securerandom (>= 0.3)
       tzinfo (~> 2.0, >= 2.0.5)
       uri (>= 0.13.1)
     ast (2.4.3)
-    base64 (0.2.0)
-    benchmark (0.4.0)
-    bigdecimal (3.1.9)
-    concurrent-ruby (1.3.5)
-    connection_pool (2.5.0)
-    csv (3.3.3)
-    diff-lcs (1.6.1)
+    base64 (0.3.0)
+    bigdecimal (4.0.1)
+    concurrent-ruby (1.3.6)
+    connection_pool (3.0.2)
+    csv (3.3.5)
+    diff-lcs (1.6.2)
     docile (1.4.1)
-    drb (2.2.1)
-    i18n (1.14.7)
+    drb (2.2.3)
+    i18n (1.14.8)
       concurrent-ruby (~> 1.0)
     inheritance-helper (0.2.5)
-    json (2.10.2)
-    language_server-protocol (3.17.0.4)
+    json (2.18.0)
+    language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
-    minitest (5.25.5)
-    parallel (1.26.3)
-    parser (3.3.7.4)
+    minitest (6.0.1)
+      prism (~> 1.5)
+    parallel (1.27.0)
+    parser (3.3.10.1)
       ast (~> 2.4.1)
       racc
-    prism (1.4.0)
+    prism (1.9.0)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.2.1)
-    regexp_parser (2.10.0)
-    rspec (3.13.0)
+    regexp_parser (2.11.3)
+    rexml (3.4.4)
+    rspec (3.13.2)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.3)
+    rspec-core (3.13.6)
       rspec-support (~> 3.13.0)
-    rspec-expectations (3.13.3)
+    rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.2)
+    rspec-mocks (3.13.7)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.2)
-    rubocop (1.75.2)
+    rspec-support (3.13.7)
+    rubocop (1.84.0)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -64,26 +64,29 @@ GEM
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.44.0, < 2.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.44.0)
+    rubocop-ast (1.49.0)
       parser (>= 3.3.7.2)
-      prism (~> 1.4)
+      prism (~> 1.7)
     ruby-progressbar (1.13.0)
     securerandom (0.4.1)
     simplecov (0.22.0)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
-    simplecov-html (0.13.1)
+    simplecov-cobertura (3.1.0)
+      rexml
+      simplecov (~> 0.19)
+    simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    unicode-display_width (3.1.4)
-      unicode-emoji (~> 4.0, >= 4.0.4)
-    unicode-emoji (4.0.4)
-    uri (1.0.3)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    uri (1.1.1)
 
 PLATFORMS
   arm64-darwin-24
@@ -93,10 +96,10 @@ DEPENDENCIES
   activemodel
   csv
   inheritance-helper
-  rake
   rspec
   rubocop
   simplecov
+  simplecov-cobertura
 
 BUNDLED WITH
    2.6.2