jpie 0.4.3 → 0.4.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17c72f6974e3f671d772c5acec6ccd40541e06c36797603b4e0625b2235834f2
-  data.tar.gz: 6e13c925f6c6605278a0f3544165c8c3f7c9c6feaf3f97c54265c033f0a498e5
+  metadata.gz: 47016b3f031cd5322fecf012737f1aaace980414f3ed27dd18f54e21e5c5b76b
+  data.tar.gz: 7f8164b1e49018f93838740dcf64d79c331608095e1aa6c58e6c3fbf756ce1b8
 SHA512:
-  metadata.gz: 8a9d2f4a6505c5bd7e94798fd63c382150b4170f8cd610548439161bec82dc9bfc07807468e32cc50d980018e7bc5625724db509742a97281e32dfb069acbe47
-  data.tar.gz: 8e1eb70f4967a8d83c25583b234172a6fd9e9767ef1ea816a2fe5b6dc447f7bd11a68e67cab7e27851eee342395e616249d32033680cdc83050d896bd5726ec9
+  metadata.gz: 81b14fd2264f3a2b930deec1f9328fea96c6b89e8fd0a2ef60379ec245789503304f013c442ff6e23b1eee304a8e3d34c064b8535a51edcbcf505b108f63acff
+  data.tar.gz: aad90976a22a42d6dcc038edfb0a28ef5f2a4923cf7a8d5083ad6d9c55198c93c59aab7b94cce408057597219f50f4f8ecad18651f7a774821d5906601be55e9

data/.cursor/rules/dependencies.mdc

@@ -0,0 +1,19 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Dependency Management
+
+## Requirements
+- Keep dependencies minimal and justified
+- Document new dependencies in README.md
+- Keep development dependencies in Gemfile
+- Ensure compatibility with Ruby 3.4+
+- Only support Rails 8+ features
+- Use modern gem versions
+
+## Compatibility Requirements
+- Maintain Ruby 3.4+ compatibility
+- Support Rails 8+ integration
+- Follow JSON:API specification strictly

data/.cursor/rules/examples.mdc

@@ -0,0 +1,16 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Example Guidelines
+
+- Examples must only include required code
+- Examples must not include any unrelated or superfluous code
+- Examples must be a single markdown file
+- Examples must use the `http` code blocks for examples
+- Examples must only include the minimum number of examples
+- Examples must never include migrations
+- Examples must not include a features section or similar
+- Examples must include an introduction to the example
+- Examples live in /examples/*.md

data/.cursor/rules/git.mdc

@@ -0,0 +1,14 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Git Commit Guidelines
+
+- Write clear, descriptive commit messages
+- Keep commits focused and atomic
+- Run and pass tests before committing
+- Update documentation in the same commit as code changes
+- Ignore spec/examples.txt and other files listed in .gitignore
+- Include Ruby/Rails version requirements in relevant commits
+- Update tests in the same commit as code changes

data/.cursor/rules/project_structure.mdc

@@ -0,0 +1,30 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Project Information
+- Project Name: jpie
+- Description: Ruby gem for JSON:API implementation
+
+# Project Structure
+
+## Core Structure
+- Keep core functionality in lib/jpie/
+- Place tests in spec/jpie/
+- Use proper namespacing (JPie module)
+- Follow Ruby gem best practices
+
+## Protected Files
+- Do not update spec/jpie/database.rb unless absolutely necessary
+- Do not update spec/jpie/resources.rb unless absolutely necessary
+
+## Documentation
+- Keep README.md up to date with installation and usage instructions
+- Include example usage in documentation
+
+## Development Process
+- Always read the .aiconfig file
+- Always implement code slowly and methodically
+- Always test as you go
+- Always make sure rubocop passes

data/.cursor/rules/publish_gem.mdc

@@ -0,0 +1,73 @@
+# Publish JPie Gem
+
+This rule helps publish a new version of the JPie gem.
+
+## Requirements
+# Publish JPie Gem
+
+This rule helps publish a new version of the JPie gem.
+
+## Requirements
+
+1. You must have publishing rights on RubyGems.org
+2. You must have 2FA enabled on RubyGems.org
+3. The version must be updated in `lib/jpie/version.rb`
+4. The changelog must be updated in `CHANGELOG.md`
+
+## Steps
+
+1. First, ensure the version and changelog are updated and committed
+2. Build the gem
+3. Get OTP code from user
+4. Push to RubyGems with OTP
+5. Update bundle
+6. Tag the release
+7. Push tags
+
+## Example Chat
+
+Human: Publish new version of JPie gem
+
+Assistant: I will help you publish the gem. First, let me check if the version and changelog are updated.
+[Checks version and changelog]
+
+Now I will build the gem:
+> gem build jpie.gemspec
+
+The gem has been built. To publish it, I will need your OTP code from RubyGems.org.
+What is your OTP code?
+
+Human: 123456
+
+Assistant: Thanks! I will now push the gem with your OTP:
+> gem push jpie-x.y.z.gem --otp 123456
+
+Great! The gem has been published. Now I will:
+1. Update the bundle
+> bundle update jpie
+
+2. Tag the release
+> git tag -a vx.y.z -m "Version x.y.z"
+
+3. Push the tags
+> git push origin --tags
+
+The gem has been successfully published and all post-publish steps are complete!
+
+## Automation
+
+```bash
+# Build the gem
+gem build jpie.gemspec
+
+# Push to RubyGems (OTP will be requested via chat)
+gem push jpie-*.gem --otp ${OTP_CODE}
+
+# Update bundle
+bundle update jpie
+
+# Tag and push
+VERSION=$(ruby -r ./lib/jpie/version.rb -e "puts JPie::VERSION")
+git tag -a v${VERSION} -m "Version ${VERSION}"
+git push origin --tags
+```

data/.cursor/rules/security.mdc

@@ -0,0 +1,14 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Security Guidelines
+
+- Never commit sensitive data or credentials
+- Use environment variables for configuration
+- Follow secure coding practices
+- Keep dependencies up to date
+- Follow Rails 8+ security best practices
+- Use Ruby 3.4+ security features
+- Implement proper input validation

data/.cursor/rules/style.mdc

@@ -0,0 +1,15 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Style Guidelines
+
+## Ruby Style
+- Follow Ruby style guide and RuboCop rules defined in .rubocop.yml
+- Prefer rubocop autocorrect
+- Always pass rubocop before committing to git
+- Use `{data:}` rather than `{data: data}`
+- Only use code comments when absolutely necessary
+- Keep any code comments short and concise
+- Don't update .rubocop.yml unless absolutely necessary

data/.cursor/rules/testing.mdc

@@ -0,0 +1,16 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Testing Guidelines
+
+- Write RSpec tests for all new features
+- Maintain test coverage for all public methods
+- Use meaningful test descriptions
+- Follow the existing test structure in spec/
+- Test both success and error cases
+- Use modern RSpec features and syntax
+- Don't reduce test coverage (line, file, branch, or other)
+- Only care about coverage reduction when running all specs
+- Do not add any functionality for new features to existing tests unless absolutely necessary

data/PUBLISHING.md

@@ -0,0 +1,111 @@
+# Publishing JPie
+
+This guide explains how to publish new versions of the JPie gem to RubyGems.org.
+
+## Prerequisites
+
+1. Ensure you have a RubyGems.org account
+2. Ensure you have ownership/publishing rights to the gem
+3. Configure your local credentials:
+   ```bash
+   gem signin
+   ```
+
+## Publishing Process
+
+### 1. Update Version
+
+Update the version number in `lib/jpie/version.rb`:
+
+```ruby
+module JPie
+  VERSION = "x.y.z"  # Use semantic versioning
+end
+```
+
+### 2. Update Changelog
+
+Update `CHANGELOG.md` with the changes in the new version:
+
+```markdown
+## [x.y.z] - YYYY-MM-DD
+
+### Added
+- New features
+
+### Changed
+- Changes in existing functionality
+
+### Deprecated
+- Soon-to-be removed features
+
+### Removed
+- Removed features
+
+### Fixed
+- Bug fixes
+
+### Security
+- Security fixes
+```
+
+### 3. Build the Gem
+
+```bash
+gem build jpie.gemspec
+```
+
+This will create a file named `jpie-x.y.z.gem`.
+
+### 4. Test the Gem Locally (Optional)
+
+```bash
+# In a test project
+gem install ../path/to/jpie-x.y.z.gem
+```
+
+### 5. Push to RubyGems
+
+```bash
+gem push jpie-x.y.z.gem
+```
+
+### 6. Tag the Release
+
+```bash
+git add lib/jpie/version.rb CHANGELOG.md
+git commit -m "Release version x.y.z"
+git tag -a vx.y.z -m "Version x.y.z"
+git push origin main --tags
+```
+
+## Versioning Guidelines
+
+Follow [Semantic Versioning](https://semver.org/):
+
+- MAJOR version (x) - incompatible API changes
+- MINOR version (y) - add functionality in a backward compatible manner
+- PATCH version (z) - backward compatible bug fixes
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Authentication Failed**
+   ```bash
+   gem signin  # Re-authenticate with RubyGems
+   ```
+
+2. **Gem Name Conflict**
+   - Ensure the version number is unique
+   - Check if the gem name is available on RubyGems.org
+
+3. **Build Errors**
+   - Ensure all dependencies are correctly specified in the gemspec
+   - Verify the gem builds locally before pushing
+
+### Getting Help
+
+- [RubyGems Guides](https://guides.rubygems.org/)
+- [Semantic Versioning](https://semver.org/)
+- Open an issue in the JPie repository 

data/examples/rspec_testing.md

@@ -0,0 +1,130 @@
+# Testing JPie Resources with RSpec
+
+This guide demonstrates how to use JPie's RSpec matchers and helpers to test your JSON:API resources.
+
+## Setup
+
+Add to your `spec/rails_helper.rb` or `spec/spec_helper.rb`:
+
+```ruby
+require 'jpie/rspec'
+JPie::RSpec.configure!
+```
+
+## Example Usage
+
+Given a basic resource setup:
+
+```ruby
+# app/models/book.rb
+class Book < ApplicationRecord
+  belongs_to :author
+  has_many :reviews
+  
+  def reading_time_minutes
+    (content.split.length / 200.0).ceil
+  end
+end
+
+# app/resources/book_resource.rb
+class BookResource < JPie::Resource
+  type :books
+  
+  attribute :title
+  meta_attribute :reading_time
+  relationship :author
+  relationship :reviews
+  
+  def reading_time
+    { minutes: object.reading_time_minutes }
+  end
+end
+```
+
+Here's how to test it:
+
+```ruby
+# spec/resources/book_resource_spec.rb
+RSpec.describe BookResource, type: :resource do
+  let(:author) { create(:author) }
+  let(:book) { create(:book, author: author) }
+  let(:resource) { described_class.new(model: book) }
+
+  # Test resource structure
+  it { is_expected.to have_type(:books) }
+  it { is_expected.to have_attribute(:title) }
+  it { is_expected.to have_meta_attribute(:reading_time) }
+  it { is_expected.to have_relationship(:author) }
+  it { is_expected.to have_relationship(:reviews) }
+
+  # Test meta values
+  it 'has correct reading time' do
+    expect(resource).to have_meta_value(:reading_time).including(
+      minutes: book.reading_time_minutes
+    )
+  end
+
+  # Test relationship linkage
+  it 'has correct author linkage' do
+    expect(resource).to have_relationship_linkage(:author).with_id(author.id.to_s)
+  end
+end
+
+# spec/requests/books_controller_spec.rb
+RSpec.describe BooksController, type: :request do
+  let!(:books) { create_list(:book, 10) }
+
+  describe 'GET /books' do
+    it 'handles pagination and includes' do
+      get '/books', params: { 
+        page: 1, 
+        per_page: 5,
+        include: 'author,reviews'
+      }
+      
+      # Test pagination
+      expect(response).to be_paginated
+      expect(response).to have_page_size(5)
+      expect(response).to have_pagination_links.including(:first, :last, :next)
+
+      # Test includes
+      expect(response).to include_related(:author)
+      expect(response).to include_related(:reviews)
+    end
+  end
+end
+```
+
+## Helper Methods
+
+```ruby
+# Build without saving
+book = build_jpie_resource(:books, { title: 'Test Book' })
+
+# Create with relationships
+author = create_jpie_resource(:authors, { name: 'Author' })
+book = create_jpie_resource(:books, { title: 'Test Book' }, { author: author })
+
+# Clean up
+cleanup_jpie_resources([book, author])
+```
+
+## Best Practices
+
+1. Always clean up your test resources using `cleanup_jpie_resources`
+2. Test both the presence of attributes/relationships and their values
+3. Group your tests logically by resource features (attributes, relationships, meta)
+4. Test pagination with different page sizes and page numbers
+5. Test relationship includes with various combinations
+6. Test meta fields with both simple and complex values
+7. Use factories (like FactoryBot) to create test data
+8. Test edge cases and validations specific to your resource configuration
+
+## Common Gotchas
+
+- Remember that `have_attribute` and `have_relationship` check both the presence of the method and the attribute/relationship in the resource's configuration
+- The cleanup helper will only destroy persisted resources
+- When testing relationships, make sure to test both the relationship configuration and the actual related resources
+- Meta field values should match exactly, including nested structures
+- Pagination tests should verify both the metadata and the actual number of records returned
+- When testing includes, verify both the presence of the included data and its structure 

data/lib/jpie/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JPie
-  VERSION = '0.4.3'
+  VERSION = '0.4.5'
 end

data/lib/jpie.rb

@@ -3,14 +3,14 @@
 require 'active_support'
 require 'active_support/core_ext'
 require 'jpie/version'
+require_relative 'jpie/resource'
+require_relative 'jpie/errors'
 
 module JPie
-  autoload :Resource, 'jpie/resource'
   autoload :Serializer, 'jpie/serializer'
   autoload :Deserializer, 'jpie/deserializer'
   autoload :Controller, 'jpie/controller'
   autoload :Configuration, 'jpie/configuration'
-  autoload :Errors, 'jpie/errors'
   autoload :Routing, 'jpie/routing'
 
   class << self

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: jpie
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.4.5
 platform: ruby
 authors:
 - Emil Kampp
 bindir: exe
 cert_chain: []
-date: 2025-05-26 00:00:00.000000000 Z
+date: 2025-05-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -169,11 +169,19 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".cursorrules"
+- ".cursor/rules/dependencies.mdc"
+- ".cursor/rules/examples.mdc"
+- ".cursor/rules/git.mdc"
+- ".cursor/rules/project_structure.mdc"
+- ".cursor/rules/publish_gem.mdc"
+- ".cursor/rules/security.mdc"
+- ".cursor/rules/style.mdc"
+- ".cursor/rules/testing.mdc"
 - ".overcommit.yml"
 - ".rubocop.yml"
 - CHANGELOG.md
 - LICENSE.txt
+- PUBLISHING.md
 - README.md
 - Rakefile
 - examples/basic_example.md
@@ -182,6 +190,7 @@ files:
 - examples/relationships.md
 - examples/resource_attribute_configuration.md
 - examples/resource_meta_configuration.md
+- examples/rspec_testing.md
 - examples/single_table_inheritance.md
 - jpie.gemspec
 - lib/jpie.rb

data/.cursorrules

@@ -1,82 +0,0 @@
-# AI Assistant Configuration
-# This file contains rules and guidelines for AI assistants working on the jpie project
-
-# Follow these code style guidelines
-- Follow Ruby style guide and RuboCop rules defined in .rubocop.yml
-- Prefer rubocop autocorrect 
-- Always pass rubocop before committing to git
-- Use `{data:}` rather than `{data: data}`
-- Only use code comments when abasolutely necessary
-- Keep any code comments short and concise
-- Don't update the .rubocop.yml unless it's absolutely necessarry
-
-# Documentation requirements
-- Keep README.md up to date with installation and usage instructions
-- Include example usage in documentation
-
-# Testing guidelines
-- Write RSpec tests for all new features
-- Maintain test coverage for all public methods
-- Use meaningful test descriptions
-- Follow the existing test structure in spec/
-- Test both success and error cases
-- Use modern RSpec features and syntax
-- Don't reduce test coverage (line, file, branch, or other)
-- Only care about coverge reduction when running all specs
-
-# Git commit guidelines
-- Write clear, descriptive commit messages
-- Keep commits focused and atomic
-- Run and pass tests before committing
-- Update documentation in the same commit as code changes
-- Ignore spec/examples.txt and other files listed in .gitignore
-- Include Ruby/Rails version requirements in relevant commits
-- Update tests in the same commit as code changes
-
-# Maintain the following project structure
-- Keep core functionality in lib/jpie/
-- Place tests in spec/jpie/
-- Use proper namespacing (JPie module)
-- Follow Ruby gem best practices
-- Do not update the spec/jpie/database.rb unless it's absolutely necessarry
-- Do not update the spec/jpie/resources.rb unless it's absolutely necessarry
-
-# Dependency management
-- Keep dependencies minimal and justified
-- Document new dependencies in README.md
-- Keep development dependencies in Gemfile
-- Ensure compatibility with Ruby 3.4+
-- Only support Rails 8+ features
-- Use modern gem versions
-
-# Security guidelines
-- Never commit sensitive data or credentials
-- Use environment variables for configuration
-- Follow secure coding practices
-- Keep dependencies up to date
-- Follow Rails 8+ security best practices
-- Use Ruby 3.4+ security features
-- Implement proper input validation
-
-# Compatibility requirements
-- Maintain Ruby 3.4+ compatibility
-- Support Rails 8+ integration
-- Follow JSON:API specification strictly
-
-# When implementing new features or refactoring
-- Always read the .aiconfig file 
-- Always implement code slowly and methodically 
-- Always test as you go
-- Always make sure rubocop passes
-- Do not add any functionality for the new feature to existing tests unless absolutely necessarry.
-
-# Examples
-- The examples must _only_ include _required_ code
-- The examples must not include any unrelated or supurflous code
-- Examples must be a single markdown file
-- Examples must use the `http` code blocks for its exampels
-- Examples must only include the minium number of examples
-- Examples must never include migrations.
-- Examples must not include a features section or similar
-- Examples must include an introduction to the example
-- Examples live in /examples/*.md