propel_api 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fda016a4637d6921f4cbd7c1739aa12b652453b68f2bf00e627adda7a0384086
-  data.tar.gz: bee75517d7fee3d5f04536be44f5dba602bc5525076814a87e7b6f743a467913
+  metadata.gz: 224fb8718c35e1b5d828201c8256a39eeedc0cc6f9ad096ac874f34c9a726c25
+  data.tar.gz: 6902529de75450cd89415ea357891100f2c2a2d4cc6c57ba6679257e693aaab3
 SHA512:
-  metadata.gz: a19fc6c6f6c4d12773081adc7a856d7f4fcb1977c56cb3686334d8e316bb29ef540829f0f25adcd61ae6285f10a010691f063b0003bad463bc8b8624afd05974
-  data.tar.gz: 65349f86faa2e171c64b20d6699f90dc56649ae1b8c888f64ac8c3b76f147bbd301689ac79a0032c71cc134e3d1c3e380f0f5a1fbb7a35c46ea0adaebd63fb44
+  metadata.gz: dcd7b7a650de42cf4d0f19e51e777535e399c7f01dd0947e6ecb97854504a2e1a79abfa0341f7bb2dae4dc128cc9261b0c42060c5218aa6129c465920eeb6546
+  data.tar.gz: 5ee7eace1077821dbb23b93f719d3544447e8a72d5ba0541df8712d55b6294054d2f335aaa4d8bad43e60ea4b69d7737733e4e63bc722bde3ad5fbd2b85a1418

data/CHANGELOG.md

@@ -10,19 +10,72 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Planned Features
 - GraphQL adapter support
 
-## [0.2.0] - 2025-09-02
+## [0.3.0] - 2025-01-15
+
+### 🎉 Major Features Added
+- **Full Polymorphic Association Support**: Complete implementation of polymorphic relationships in API resources
+  - New `--parents` command-line option for specifying valid parent models
+  - Automatic generation of correct fixtures, tests, and API parameters
+  - Support for quote-free polymorphic syntax: `field_name:polymorphic`
+  - Enhanced fixture generation using Rails' `fixture_name (ModelName)` syntax
+
+### ⚠️ Breaking Changes
+- **Generator Syntax Change**: Tenancy associations are not automatically created you must pass organization:references and/or agency:references and configure the tenancy in the PropelApi configurations, any automated workflows or CI/CD that generate resources assuming the organization and/or agency references will be auto-injected will break with generator calls. 
+- **Required --parents Option**: Polymorphic resources now require `--parents field_name:Parent1,Parent2` for proper test generation
+- **Fixture Format Change**: Polymorphic fixtures now use `field_name: fixture_name (ParentClass)` instead of hardcoded IDs
+- **Test Template Updates**: All test templates now include polymorphic-aware parameter generation
+
+### 🔧 Generator Improvements
+- **Enhanced Resource Generator**: 
+  - Added polymorphic syntax conversion (`field_name:polymorphic` → `field_name:references{polymorphic}`)
+  - Improved argument processing to handle polymorphic parent specifications
+  - Fixed migration generation to use processed attributes instead of raw ARGV
+- **Smart Fixture References**: 
+  - Automatic fixture name resolution (e.g., uses `marketing_agency` instead of `one` for Agency models)
+  - Dynamic parent type selection for varied test data
+  - Proper Rails fixture syntax for polymorphic associations
+
+### 🧪 Test Generation Enhancements
+- **Model Tests**: 
+  - Polymorphic association validation with proper parent type checking
+  - Automatic setup of polymorphic parent variables (`@field_name`)
+  - Correct assertions for polymorphic relationships
+- **Controller Tests**: 
+  - Automatic inclusion of both `field_name_id` and `field_name_type` in test parameters
+  - Proper polymorphic parent setup in test fixtures
+- **Integration Tests**: 
+  - Enhanced error handling tests with polymorphic parameter support
+  - Multi-tenancy isolation tests work correctly with polymorphic associations
+  - Comprehensive API workflow testing
+
+### 🏗️ Architecture Improvements
+- **Named Base Enhancements**: 
+  - New `polymorphic_associations` helper method
+  - Enhanced `polymorphic_parent_for_fixture` with fixture name resolution
+  - Improved parent type parsing and validation
+- **Template System**: 
+  - All ERB templates now polymorphic-aware
+  - Consistent handling of polymorphic vs. regular references
+  - Better error handling and edge case management
+
+### 🐛 Bug Fixes
+- **Migration Constraints**: Fixed polymorphic migrations to use `polymorphic: true` instead of incorrect `foreign_key: true`
+- **Fixture Loading**: Resolved issues with hardcoded IDs causing fixture loading failures
+- **Test Isolation**: Fixed multi-tenancy tests failing due to missing polymorphic associations
+- **API Parameter Generation**: Corrected missing `_type` parameters in generated API calls
+
+## [0.2.1] - 2025-01-14
+
+### Fixed
+- **Critical Pagy pagination bug**: Fixed `NoMethodError: undefined method 'items' for Pagy` 
+  - API controller templates now use correct `pagy.limit` instead of non-existent `pagy.items`
+  - Fixes pagination metadata generation in API responses
+  - Affects all generated API controllers with pagination
+- **Dependency update**: Improved compatibility with PropelFacets 0.2.1
+  - API controllers now work correctly with fixed `for_organization` scope installation
+  - Resolves `NoMethodError` when using generated controllers in fresh Rails installations
 
-### BREAKING CHANGES
-- **Security-first API architecture**: Complete redesign of tenancy validation flow
-  - Invalid tenancy context (organization_id, agency_id) now returns 403 Forbidden instead of 422 Unprocessable Entity
-  - Security validation occurs before business validation (prevents information disclosure)
-  - Error response structure changed from `{"errors": {...}}` to `{"error": "...", "message": "...", "code": "..."}`
-- **Controller generation format**: Generated controllers now use foreign key format in permitted_params
-  - `permitted_params :organization` → `permitted_params :organization_id`
-  - Ensures proper strong parameter filtering for security validation
-- **Configuration dependency**: `agency_tenancy` configuration moved to PropelAuthentication
-  - Remove `PropelApi.configuration.agency_tenancy` from config files
-  - Agency tenancy now controlled entirely by PropelAuthentication
+## [0.2.0] - 2025-09-02
 
 ### Added
 - **Organization-level multi-tenancy security** - Complete data isolation between organizations
@@ -31,19 +84,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `for_organization(org_id)` scope added to ApplicationRecord base class
   - Cross-organization data access completely blocked (show, update, delete return 404)
   - New records automatically assigned to authenticated user's organization
-  - Comprehensive security test suite covering all attack vectors
+  - Comprehensive security test suite with 12 tests covering all attack vectors
   - Zero impact on existing single-tenant applications
-- **Configurable auto-assignment**: Integration with PropelAuthentication tenancy configuration
-  - Respects `require_organization_id` and `require_user_id` settings from PropelAuthentication
-  - Helper methods: `require_organization_id?`, `require_user_id?` for configuration access
-- **Enhanced security validation**: Comprehensive unauthorized access protection
-  - Organization access validation with detailed error codes
-  - User assignment validation for admin delegation scenarios  
-  - Agency access validation with proper user permission checking
-- **Conditional test generation**: Tests now adapt behavior based on PropelAuthentication configuration
-  - Auto-assignment mode: Tests expect 201 Created with proper context assignment
-  - Strict mode: Tests expect 422 Unprocessable Entity when required fields missing
-  - Security tests: Tests expect 403 Forbidden for unauthorized access attempts
 
 ### Fixed
 - **Authentication namespace conflict resolved** - Renamed authentication concern to prevent module name collision
@@ -53,14 +95,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Updated PropelFacets and Graphiti API controller templates
   - Improved method visibility: `authenticate_user`, `current_user`, and `extract_jwt_token` are now public methods
   - Enhanced flexibility for custom authentication scenarios (email notifications, audit logging, token refresh)
-- **Attribute introspection**: Fixed foreign key detection for User and other models with associations
-  - Database column introspection now properly generates foreign key format for permitted_params
-  - Association detection preserved for model relationship generation
-  - JSON field handling improved with proper `field: {}` syntax for nested objects
-- **Test data generation**: Enhanced User model test data generation
-  - Unique email and username generation to prevent fixture conflicts
-  - Proper field names for User model tests (email_address, username, password vs generic title)
-  - Model-specific test data patterns for comprehensive validation coverage
 
 ### Security
 - **Multi-tenant data isolation** - Zero-trust organization scoping prevents data leaks
@@ -71,17 +105,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Database-level enforcement via ActiveRecord scopes
 
 ### Improved
-- **Multi-step security validation**: Three-phase validation for robust security
-  1. Security validation (403 for unauthorized access) 
-  2. Auto-assignment (based on configuration)
-  3. Final validation (422 for missing required fields)
 - **Authentication concern API design** - Better method organization and access patterns
   - `authenticate_user` - Public method for `before_action` callbacks
   - `current_user` - Public method for accessing authenticated user  
   - `current_organization_id` - Public method for accessing organization context
   - `extract_jwt_token` - Public method for custom authentication scenarios
   - Clean separation between public API and internal implementation
-- **Template reliability**: Attribute detection using generator attributes instead of database queries during generation
 
 ## [0.1.4] - 2025-08-15
 

data/README.md

@@ -49,13 +49,16 @@ After installation, you can remove the gem from your Gemfile. All functionality
 
 ```bash
 # Basic resource with PropelFacets
-rails generate propel_api User name:string email:string role:string
+rails generate propel_api:resource User name:string email:string role:string
 
 # Resource with associations
-rails generate propel_api Article title:string content:text user:references category:references
+rails generate propel_api:resource Article title:string content:text user:references category:references
 
-# Polymorphic associations
-rails generate propel_api Comment content:text commentable:references
+# 🎉 NEW: Polymorphic associations (v0.3.0)
+rails generate propel_api:resource Comment content:text commentable:references{polymorphic} --parents commentable:Post,Video,Product
+
+# Polymorphic with tenancy
+rails generate propel_api:resource Review rating:integer comment:text review_parent:polymorphic --parents review_parent:Product,Agency
 
 # With Graphiti adapter
 rails generate propel_api Product name:string price:decimal --adapter=graphiti
@@ -70,6 +73,238 @@ This generates:
 - **Fixtures** with realistic test data
 - **Seeds** with Faker-generated sample data
 
+## 🎉 Polymorphic Association Support (v0.3.0)
+
+PropelApi now provides comprehensive support for polymorphic associations with automatic test generation and intelligent fixture management.
+
+### Quick Start with Polymorphic Resources
+
+```bash
+# Generate a Comment that can belong to Posts, Videos, or Products
+rails generate propel_api:resource Comment body:text commentable:references{polymorphic} --parents commentable:Post,Video,Product
+
+# Generate a Review with full tenancy support
+rails generate propel_api:resource Review rating:integer comment:text review_parent:references{polymorphic} --parents reviewable:Product,Agency
+```
+
+### Key Features
+
+#### ✨ Simple, Intuitive Syntax
+- Additional support `field_name:polymorphic` instead of Rails' verbose `field_name:references{polymorphic}`
+- No need for complex quote escaping or nested syntax
+
+#### 🎯 Smart Parent Specification
+- `--parents field_name:Parent1,Parent2,Parent3` defines valid parent models
+- Automatically generates varied test data using different parent types
+- Validates parent models exist in your application
+
+#### 🧪 Complete Test Coverage
+- **Model Tests**: Proper polymorphic association validation and parent type checking
+- **Controller Tests**: Automatic inclusion of both `_id` and `_type` parameters
+- **Integration Tests**: Full API workflow testing with polymorphic data
+- **Fixtures**: Uses Rails' clean `fixture_name (ModelName)` syntax
+
+#### 🔧 Generated Code Quality
+```ruby
+# Generated Model
+class Comment < ApplicationRecord
+  belongs_to :commentable, polymorphic: true
+  # ... other associations and validations
+end
+
+# Generated Migration  
+def change
+  create_table :comments do |t|
+    t.text :body
+    t.references :commentable, polymorphic: true, null: false
+    # ... other fields
+  end
+end
+
+# Generated Fixtures (clean Rails syntax)
+one:
+  commentable: one (Post)
+  body: "Great post!"
+
+two:
+  commentable: featured_video (Video)
+  body: "Amazing video content!"
+```
+
+#### 🚀 API-Ready Controllers
+Controllers automatically include proper parameter handling:
+```ruby
+class Api::V1::CommentsController < Api::V1::ApiController
+  permitted_params :body, :commentable_id, :commentable_type
+end
+```
+
+### Breaking Changes from v0.2.x
+
+⚠️ **Migration Required**: The polymorphic syntax and test generation has been completely rewritten for better reliability and Rails compatibility.
+
+- **Old**: `rails generate propel_api:resource Comment body:text commentable:references{polymorphic}`
+- **New**: `rails generate propel_api:resource Comment body:text commentable:polymorphic --parents commentable:Post,Video`
+
+The new approach provides:
+- More reliable test generation
+- Better fixture management
+- Cleaner, more maintainable code
+- Full Rails compatibility
+
+## 🚀 API Explorer for Development
+
+PropelApi includes a comprehensive test application with multiple API resources perfect for development and testing. The dummy app provides a fully functional API with authentication, multi-tenancy, and polymorphic associations.
+
+### Quick Start with the Test API
+
+```bash
+# Navigate to the test application
+cd test/dummy
+
+# Set up the database
+rails db:setup
+
+# Start the development server
+rails server
+
+# Your API is now running at http://localhost:3000
+```
+
+### Available API Endpoints
+
+The dummy app provides these fully functional endpoints:
+
+#### Authentication
+- `POST /api/v1/signup` - User registration
+- `POST /api/v1/login` - User authentication  
+- `GET /api/v1/me` - Current user info
+- `DELETE /api/v1/logout` - Logout
+- `POST /api/v1/reset` - Password reset request
+- `PATCH /api/v1/reset` - Password reset update
+
+#### Core Resources
+- `GET|POST /api/v1/users` - User management
+- `GET|POST /api/v1/organizations` - Organization management
+- `GET|POST|PATCH|DELETE /api/v1/products` - Product CRUD
+- `GET|POST|PATCH|DELETE /api/v1/comments` - Comment CRUD
+- `GET|POST|PATCH|DELETE /api/v1/attachments` - File attachments
+- `GET|POST|PATCH|DELETE /api/v1/reviews` - Reviews (polymorphic!)
+
+### Setting Up API Explorer Tools
+
+#### Option 1: Postman Collection
+
+Create a Postman collection with these base settings:
+
+```json
+{
+  "info": {
+    "name": "PropelApi Development",
+    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
+  },
+  "variable": [
+    {
+      "key": "base_url",
+      "value": "http://localhost:3000/api/v1",
+      "type": "string"
+    },
+    {
+      "key": "auth_token",
+      "value": "",
+      "type": "string"
+    }
+  ]
+}
+```
+
+#### Option 2: Insomnia Workspace
+
+1. Create a new workspace in Insomnia
+2. Set base URL: `http://localhost:3000/api/v1`
+3. Create environment variables:
+   - `base_url`: `http://localhost:3000/api/v1`
+   - `auth_token`: (will be populated after login)
+
+#### Option 3: cURL Scripts
+
+```bash
+# Login and get token
+TOKEN=$(curl -s -X POST http://localhost:3000/api/v1/login \
+  -H "Content-Type: application/json" \
+  -d '{"data": {"email_address": "test@example.com", "password": "password123"}}' \
+  | jq -r '.token')
+
+# Use token for authenticated requests
+curl -H "Authorization: Bearer $TOKEN" \
+     -H "Content-Type: application/json" \
+     http://localhost:3000/api/v1/me
+```
+
+### API Response Format
+
+All PropelApi endpoints follow consistent JSON:API-inspired formatting:
+
+```json
+{
+  "data": {
+    "id": 1,
+    "name": "Example Product",
+    "price": 99.99,
+    "organization": {
+      "id": 1,
+      "name": "Test Organization"
+    }
+  },
+  "meta": {
+    "total": 1,
+    "page": 1,
+    "limit": 25
+  }
+}
+```
+
+### Testing Polymorphic Associations
+
+The Reviews resource demonstrates polymorphic associations:
+
+```bash
+# Create a review for a product
+curl -X POST http://localhost:3000/api/v1/reviews \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "data": {
+      "rating": 5,
+      "comment": "Great product!",
+      "reviewable_id": 1,
+      "reviewable_type": "Product"
+    }
+  }'
+
+# Create a review for an agency
+curl -X POST http://localhost:3000/api/v1/reviews \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "data": {
+      "rating": 4,
+      "comment": "Good service!",
+      "reviewable_id": 1,
+      "reviewable_type": "Agency"
+    }
+  }'
+```
+
+### Development Tips
+
+1. **Seed Data**: Run `rails db:seed` to populate with realistic test data
+2. **Test User**: Default login is `test@example.com` / `password123`
+3. **Admin User**: Admin login is `admin@example.com` / `password123`
+4. **Multi-tenancy**: All resources are scoped to organizations automatically
+5. **Error Handling**: All endpoints return consistent error formats
+6. **Validation**: Try invalid data to see validation error responses
+
 ### Generate Controllers for Existing Models
 
 ```bash

data/lib/generators/propel_api/core/named_base.rb

@@ -93,7 +93,7 @@ module PropelApi
           attributes << attr_data
         end
       end
-      
+
       # Look for basic validations that might indicate attributes
       # Exclude association names (they're already handled above as foreign keys)
       # NOTE: Only add validated attributes if they weren't already detected by schema introspection
@@ -514,5 +514,96 @@ module PropelApi
       
       content
     end
+
+    # Helper methods for templates to detect tenancy attributes
+    # These are shared between ResourceGenerator and ControllerGenerator
+    def has_organization_reference?
+      return false unless defined?(@attributes) && @attributes
+      @attributes.any? { |attr| attr.name == 'organization' && attr.type == :references }
+    end
+
+    def has_agency_reference?
+      return false unless defined?(@attributes) && @attributes
+      @attributes.any? { |attr| attr.name == 'agency' && attr.type == :references }
+    end
+
+    # Polymorphic associations helper methods
+    def polymorphic_parent_types
+      @polymorphic_parent_types ||= parse_polymorphic_parent_types
+    end
+
+    def polymorphic_associations
+      return [] unless defined?(@attributes) && @attributes
+      
+      @polymorphic_associations ||= begin
+        polymorphic_attrs = @attributes.select { |attr| attr.type == :references && attr.respond_to?(:polymorphic?) && attr.polymorphic? }
+        
+        polymorphic_attrs.map do |attr|
+          parent_types = polymorphic_parent_types[attr.name.to_s] || discover_available_models.first(1)
+          
+          # Create one association entry per polymorphic field with all parent types
+          {
+            field_name: attr.name,
+            id_field: "#{attr.name}_id",
+            type_field: "#{attr.name}_type",
+            parent_types: parent_types,
+            # For fixture generation, we'll use the first parent type for fixture "one", second for "two", etc.
+            primary_parent_type: parent_types.first,
+            primary_parent_table: parent_types.first.underscore.pluralize
+          }
+        end
+      end
+    end
+
+    # Helper method for fixture generation to get the appropriate parent type for each fixture
+    def polymorphic_parent_for_fixture(field_name, fixture_index)
+      poly_assoc = polymorphic_associations.find { |assoc| assoc[:field_name].to_s == field_name.to_s }
+      return nil unless poly_assoc
+      
+      parent_types = poly_assoc[:parent_types]
+      parent_type = parent_types[fixture_index % parent_types.length] || parent_types.first
+      
+      # Determine the fixture name based on parent type and fixture index
+      fixture_name = case parent_type.underscore
+      when 'agency'
+        ['marketing_agency', 'tech_agency', 'sales_agency'][fixture_index] || 'marketing_agency'
+      else
+        ['one', 'two', 'three'][fixture_index] || 'one'
+      end
+      
+      {
+        id_field: poly_assoc[:id_field],
+        type_field: poly_assoc[:type_field],
+        parent_type: parent_type,
+        parent_table: parent_type.underscore.pluralize,
+        fixture_name: fixture_name
+      }
+    end
+
+    private
+
+    def parse_polymorphic_parent_types
+      return {} unless defined?(options) && options[:parents]
+      
+      parsed_types = {}
+      options[:parents].each do |field_name, parent_list|
+        parsed_types[field_name] = parent_list.split(',').map(&:strip).map(&:camelize)
+      end
+      parsed_types
+    end
+
+    def discover_available_models
+      # Auto-discover available models from app/models directory
+      models_dir = File.join(destination_root, 'app/models')
+      return ['Post'] unless File.directory?(models_dir) # Fallback
+      
+      model_files = Dir[File.join(models_dir, '*.rb')]
+      model_files.map do |file|
+        File.basename(file, '.rb').camelize
+      end.reject do |model|
+        # Skip common non-domain models
+        %w[ApplicationRecord Concerns].include?(model)
+      end.sort
+    end
   end
 end 

data/lib/generators/propel_api/core/relationship_inferrer.rb

@@ -106,20 +106,13 @@ class RelationshipInferrer
   end
   
   def polymorphic_belongs_to(attribute)
-    # Extract the base name for polymorphic association
-    if attribute.name.to_s.end_with?('_parent')
-      # resource_parent -> resource
-      base_name = attribute.name.to_s.gsub(/_parent$/, '')
-    elsif attribute.name.to_s.end_with?('able')
-      # commentable -> commentable
-      base_name = attribute.name.to_s
-    else
-      base_name = attribute.name.to_s
-    end
+    # Keep the full attribute name for polymorphic associations
+    # Don't strip the '_parent' suffix - it's needed to match the schema columns
+    association_name = attribute.name.to_s
     
     # Polymorphic associations default to required (Rails convention)
     # Add 'optional: true' manually if optional behavior is needed
-    "belongs_to :#{base_name}, polymorphic: true"
+    "belongs_to :#{association_name}, polymorphic: true"
   end
   
 

data/lib/generators/propel_api/install/install_generator.rb

@@ -140,8 +140,8 @@ module PropelApi
 
     def add_propel_facets_gems
       add_gem_if_missing 'faker', '~> 3.5', 'Realistic seed data generation'
-      add_gem_if_missing 'pagy', '~> 9.0', 'Pagination for Propel Facets API'
-      add_gem_if_missing 'has_scope', '~> 0.8.0', 'Scope filtering for Propel Facets API'
+      add_gem_if_missing 'pagy', '~> 9.4', 'Pagination for Propel Facets API'
+      add_gem_if_missing 'has_scope', '~> 0.8.2', 'Scope filtering for Propel Facets API'
       add_gem_if_missing 'ransack', '~> 4.0', 'Advanced search for Propel Facets API'
       
       say "Don't forget to run: bundle install", :yellow