schema-model 0.6.11 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0604e96e9d70ef3b47b7581ef0c6c43005960af46dde776565700abf86482ad5
-  data.tar.gz: cdfdbf20d77cfd81521df44308083b1134062c19e041752a2a194ee05c420c4d
+  metadata.gz: 53c13ff970f92e81b387ef19cb957afed64e77ec42ff63998a2d73fd2c383849
+  data.tar.gz: fe073187e725a642bc9e38a43798d99c5388bfad239e709c6d0d8be1c8cf699a
 SHA512:
-  metadata.gz: 590a840b90865bc31c4c75c0f34f10135c9d410532c6585d64afa20e39f712262bb43794cea9414877eb8df3602567cf057deb75867d9436eea0315a313aea15
-  data.tar.gz: 0d9b8ee1ba799df269f396c68692e9210f90bde87192f3f121809a42db99647630b12c5624ed108ff58079a661a1f51b6547e876797dc32a0a887ebb7bcbfc41
+  metadata.gz: 8186811e01c702fd082948daccc4ec5f0aaf67afefe15c0ca4200557e0b7397178eb0dcdb4ad1c44500d7284b8da31d6f607f4ae8f5652b3bff3fd66512cc0cd
+  data.tar.gz: 4d8b2fc23e68a4209571ce131b893dfa250ad85cf61f37fae48a47098d1fb4cda6730171c32a3c86dfb406f55cafea10a28ff3b65b8b1e33870801c4cfc39c3d

data/.github/workflows/ci.yml

@@ -0,0 +1,93 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  # release-please PRs change only these files. Their runs are triggered by
+  # github-actions[bot], which GitHub holds for approval until they expire as
+  # failures; release.yml runs this workflow before publishing anyway. A PR is
+  # skipped only if every file it changes is listed here.
+  pull_request:
+    paths-ignore:
+      - CHANGELOG.md
+      - .release-please-manifest.json
+      - lib/schema/version.rb
+  workflow_call:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  lint:
+    name: RuboCop
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: ruby/setup-ruby@14594264cd68ce8a2345dd349bc3d138a4ef85c8 # v1.327.0
+        with:
+          ruby-version: '4.0'
+          bundler-cache: true
+      - run: bundle exec rubocop --format github
+
+  # Runs on the Ruby in .ruby-version, the version Gemfile.lock is resolved against
+  test:
+    name: Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: ruby/setup-ruby@14594264cd68ce8a2345dd349bc3d138a4ef85c8 # v1.327.0
+        with:
+          # no ruby-version: setup-ruby reads .ruby-version
+          bundler-cache: true
+      - run: bundle exec rspec
+      # feeds the coverage badge
+      - name: Upload coverage report
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: coverage
+          path: coverage/
+          # .last_run.json (read by the badge job) is a dotfile; upload-artifact skips those by default
+          include-hidden-files: true
+          retention-days: 14
+
+  # Publishes coverage.svg and branches.svg to the orphan `badges` branch; the README badges point at them.
+  # Skipped when called from release.yml (github.workflow is the caller's name there).
+  coverage-badge:
+    if: github.workflow == 'CI' && github.event_name == 'push' && github.ref == 'refs/heads/master'
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: ruby/setup-ruby@14594264cd68ce8a2345dd349bc3d138a4ef85c8 # v1.327.0
+        with:
+          ruby-version: '4.0'
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: coverage
+          path: coverage/
+      - run: |
+          ruby script/coverage_badge.rb coverage/.last_run.json "$RUNNER_TEMP/coverage.svg"
+          ruby script/coverage_badge.rb coverage/.last_run.json "$RUNNER_TEMP/branches.svg" branch
+      - name: Push badge to badges branch
+        run: |
+          git config user.name 'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+          if git fetch --depth=1 origin badges; then
+            git switch badges
+          else
+            git switch --orphan badges
+          fi
+          cp "$RUNNER_TEMP/coverage.svg" "$RUNNER_TEMP/branches.svg" .
+          git add coverage.svg branches.svg
+          git diff --cached --quiet || git commit -m "coverage badge for ${GITHUB_SHA::7}"
+          git push origin badges

data/.github/workflows/release.yml

@@ -0,0 +1,93 @@
+name: Release
+
+# release-please keeps a release PR open that bumps lib/schema/version.rb
+# and CHANGELOG.md from conventional commits. Merging it tags the release,
+# creates the GitHub release and publishes the gem to RubyGems.
+# Run it manually (workflow_dispatch) to retry publishing the current version.
+on:
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # release commits, tags and GitHub releases
+      issues: write # release labels
+      pull-requests: write # the release PR
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+      version: ${{ steps.release.outputs.version }}
+      pr_branch: ${{ steps.release.outputs.pr && fromJSON(steps.release.outputs.pr).headBranchName || '' }}
+    steps:
+      - uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0
+        id: release
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  # The release PR is opened with GITHUB_TOKEN, which doesn't trigger CI on it,
+  # so run the suite here before anything is published.
+  ci:
+    needs: release-please
+    if: needs.release-please.outputs.release_created == 'true' || github.event_name == 'workflow_dispatch'
+    uses: ./.github/workflows/ci.yml
+    # ceiling for the called workflow: its coverage-badge job declares contents: write
+    # (skipped when called from here); lint/test still run with ci.yml's top-level contents: read
+    permissions:
+      contents: write
+
+  publish:
+    needs: [release-please, ci]
+    runs-on: ubuntu-latest
+    environment:
+      name: rubygems
+      url: https://rubygems.org/gems/schema-model
+    permissions:
+      contents: write # attach the gem to the GitHub release
+      id-token: write # RubyGems trusted publishing (OIDC)
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          # the new tag on release; the dispatched commit on a manual retry
+          ref: ${{ needs.release-please.outputs.tag_name || github.sha }}
+          persist-credentials: false
+      - uses: ruby/setup-ruby@14594264cd68ce8a2345dd349bc3d138a4ef85c8 # v1.327.0
+        with:
+          ruby-version: '4.0'
+
+      - name: Read version
+        run: |
+          version=$(ruby -e 'puts Gem::Specification.load("schema-model.gemspec").version')
+          echo "VERSION=$version" >> "$GITHUB_ENV"
+          echo "TAG=v$version" >> "$GITHUB_ENV"
+
+      - name: Build gem
+        run: gem build schema-model.gemspec
+
+      - uses: rubygems/configure-rubygems-credentials@dc5a8d8553e6ee01fc26761a49e99e733d17954a # v2.1.0
+
+      # A version that's already on RubyGems is skipped, so a manual retry can finish a
+      # partially published release.
+      - name: Push gem
+        run: |
+          if curl -sf "https://rubygems.org/api/v2/rubygems/schema-model/versions/$VERSION.json" > /dev/null; then
+            echo "schema-model $VERSION is already published"
+          else
+            gem push "schema-model-$VERSION.gem"
+          fi
+
+      - name: Attach gem to GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release upload "$TAG" "schema-model-$VERSION.gem" --repo "$GITHUB_REPOSITORY" --clobber

data/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.7.1"
+}

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/.ruby-version

@@ -1 +1 @@
-3.4.2
+ruby-4.0.7

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/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [0.7.1](https://github.com/dougyouch/schema/compare/v0.7.0...v0.7.1) (2026-10-04)
+
+
+### Bug Fixes
+
+* **specs:** replace deprecated SimpleCov API calls ([dadae4a](https://github.com/dougyouch/schema/commit/dadae4aa2d0246e964fdb160e1b505187e3fadc6))
+* **specs:** wrap trailing hash literals in braces per Style/HashAsLastArrayItem ([cf8f18a](https://github.com/dougyouch/schema/commit/cf8f18af5b7c472298c7c0cbd7b6176356b476fc))

data/CLAUDE.md

@@ -0,0 +1,83 @@
+# 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`.
+
+## CI
+
+`.github/workflows/ci.yml` runs RuboCop and the specs on the `.ruby-version` Ruby. On pushes to `master`, it publishes `coverage.svg` (line) and `branches.svg` (branch) from `script/coverage_badge.rb` to the orphan `badges` branch for the README badges.
+
+## Releases
+
+Releases are automated by release-please (`.github/workflows/release.yml`). Conventional commits on `master` (`fix:` → patch, `feat:` → minor, `!`/`BREAKING CHANGE` → major) update an open release PR that bumps `lib/schema/version.rb` (`Schema::VERSION`, read by the gemspec) and `CHANGELOG.md`. Merging that PR tags `vX.Y.Z`, creates the GitHub release, and publishes the gem to RubyGems. Don't bump the version by hand.
+
+## 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
+- **CHANGELOG.md** - Generated by release-please from commit messages; don't edit by hand except to fix release notes

data/Gemfile

@@ -1,13 +1,12 @@
 # frozen_string_literal: true
 
-source 'http://rubygems.org'
+source 'https://rubygems.org'
 
 gem 'inheritance-helper'
 
 group :development do
   gem 'activemodel'
   gem 'csv'
-  gem 'rake'
   gem 'rubocop'
 end