propel_api 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 39e7f4915254a37e32cd3ceacaac8402a3c0f32768d0169345cf69fdb742d52d
+  data.tar.gz: 302f7022de04cd30f8c0efac85267a4e636c175169478600094a7f9c9100c465
+SHA512:
+  metadata.gz: f74c378babcf34e7077117ae21720335903589c58e4aeb68800b3abbfe8c621c323c1f0b69d12557e80e27b3c715c9aa5047a8b9c7389c834db884435e6e4cec
+  data.tar.gz: 6e93710aad4c65df5822e046239b1ea1a661dd44d7efdef050fd4fcfd734a216e4451150513df75d71f7d21748cabf83d9eb70eced4651270ff8bfa27f230e35

data/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Planned Features
+- GraphQL adapter support
+- API versioning migration tools
+- Advanced relationship inference patterns
+- Custom serialization adapter framework
+- Performance optimization tools
+
+## [0.1.0] - 2025-01-XX
+
+### Added
+- **Self-extracting generator gem architecture** - Install temporarily, extract code, remove dependency
+- **Rails generator system** with install and unpack commands
+- **Dual serialization adapter support** - PropelFacets and Graphiti
+- **Complete API resource generation** including:
+  - Models with smart association inference
+  - Controllers with full CRUD operations
+  - Migrations with proper constraints
+  - Routes with configurable namespacing/versioning
+  - Comprehensive test suite (model, controller, integration)
+  - Realistic seed data using Faker
+  - Test fixtures with sample data
+
+### Features
+- **Intelligent relationship inference** - Automatically detects and creates associations
+- **Polymorphic association support** - Handles `commentable:references` and `resource_parent:references` patterns
+- **Configurable API structure** - Customizable namespace and version patterns
+- **PropelFacets integration** - JSON facet system with inheritance and field selection
+- **Graphiti integration** - JSON:API compliant resources with automatic generation
+- **Production-ready features** - Pagination, filtering, authentication integration
+- **Comprehensive testing** - Full test coverage with realistic data
+- **Flexible unpack system** - Extract and customize any component
+
+### Configuration
+- PropelApi configuration system with adapter/namespace/version defaults
+- Command-line option support with priority hierarchy
+- Integration with Propel orchestration system
+
+### Dependencies
+- Rails 7.0+ support
+- Faker integration for realistic seed data
+- Pagy pagination for PropelFacets adapter
+- HasScope filtering for PropelFacets adapter
+- Graphiti ecosystem support for JSON:API adapter
+
+### Documentation
+- Complete installation and usage guide
+- Self-extracting architecture explanation
+- Adapter comparison and selection guide
+- Advanced relationship pattern examples
+- Production deployment considerations 

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Propel API Generator
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

data/README.md

@@ -0,0 +1,320 @@
+# PropelApi
+
+A comprehensive Rails generator that creates complete API resources with models, controllers, tests, and realistic seed data. Supports both PropelFacets (JSON Facet) and Graphiti serialization engines with **fixed route insertion** and proper indentation.
+
+## Installation
+
+PropelApi is designed as a **self-extracting generator gem**. You install it temporarily, run the generators to extract the code into your application, then remove the gem dependency.
+
+### Step 1: Add to Gemfile as a Path Gem
+
+```ruby
+# In your Gemfile
+gem 'propel_api', path: 'propel_api'
+```
+
+### Step 2: Bundle Install
+
+```bash
+bundle install
+```
+
+### Step 3: Unpack the Generator (Optional)
+
+If you want to customize the generator templates:
+
+```bash
+rails generate propel_api:unpack
+```
+
+This extracts the generator into `lib/generators/propel_api/` for customization.
+
+### Step 4: Install PropelApi
+
+```bash
+rails generate propel_api:install --adapter=propel_facets
+# or
+rails generate propel_api:install --adapter=graphiti
+```
+
+This installs the API controller base class with your chosen serialization adapter.
+
+### Step 5: Remove Gem Dependency (Optional)
+
+After installation, you can remove the gem from your Gemfile. All functionality remains in your application.
+
+## Usage
+
+### Generate Complete API Resources
+
+```bash
+# Basic resource with PropelFacets
+rails generate propel_api User name:string email:string role:string
+
+# Resource with associations
+rails generate propel_api Article title:string content:text user:references category:references
+
+# Polymorphic associations
+rails generate propel_api Comment content:text commentable:references
+
+# With Graphiti adapter
+rails generate propel_api Product name:string price:decimal --adapter=graphiti
+```
+
+This generates:
+- **Model** with associations and facets/resources
+- **Migration** with proper constraints
+- **Controller** with full CRUD operations
+- **Routes** with proper namespacing and **correct indentation**
+- **Tests** (model, controller, integration)
+- **Fixtures** with realistic test data
+- **Seeds** with Faker-generated sample data
+
+### Generate Controllers for Existing Models
+
+```bash
+# Auto-detect model attributes (with warning)
+rails generate propel_api:controller User
+
+# Explicitly auto-detect all attributes
+rails generate propel_api:controller User --all-attributes
+
+# Specify specific attributes
+rails generate propel_api:controller User name:string email:string
+
+# Custom namespace and version
+rails generate propel_api:controller User --namespace=admin_api --version=v2
+```
+
+### API Controller Usage
+
+#### PropelFacets Adapter
+```ruby
+class Api::V1::UsersController < Api::V1::ApiController
+  permitted_params :name, :email, :role
+  
+  connect_facet :short, actions: [:index]
+  connect_facet :details, actions: [:show, :create, :update]
+end
+```
+
+#### Graphiti Adapter  
+```ruby
+class Api::V1::UsersController < Api::V1::ApiController
+  self.resource = UserResource
+end
+```
+
+### Configuration Options
+
+Configure PropelApi defaults in `config/initializers/propel_api.rb`:
+
+```ruby
+PropelApi.configure do |config|
+  # Default serialization adapter: 'propel_facets' or 'graphiti'
+  config.adapter = 'propel_facets'
+  
+  # Default API namespace: 'api', 'admin_api', etc.
+  config.namespace = 'api'
+  
+  # Default API version: 'v1', 'v2', etc.
+  config.version = 'v1'
+end
+```
+
+## Features
+
+### ✅ Fixed Route Insertion
+- **Proper indentation** - Routes are inserted with correct spacing
+- **Namespace support** - Works with nested namespaces (api/v1)
+- **No duplicates** - Prevents duplicate route insertion
+- **Correct positioning** - Routes inserted in the right location
+
+### Automatic Resource Generation
+- **Smart associations** - Automatically infers relationships from field types
+- **Polymorphic support** - Handles `commentable:references` patterns  
+- **Proper constraints** - Makes organization required, others optional
+- **Realistic test data** - Uses Faker for meaningful sample data
+
+### Dual Serialization Support
+- **PropelFacets** - Flexible JSON views with inheritance and facet system
+- **Graphiti** - JSON:API compliant with automatic resource generation
+- **Adapter switching** - Change serialization strategy per project needs
+
+### Complete Test Coverage
+- **Model tests** - Validations, associations, business logic
+- **Controller tests** - CRUD operations, parameter handling
+- **Integration tests** - End-to-end API workflows  
+- **Fixtures** - Realistic test data for reliable testing
+
+### Production-Ready Features
+- **Pagination** - Built-in with Pagy (PropelFacets) or Graphiti
+- **Filtering** - HasScope integration for PropelFacets
+- **Authentication** - Ready for PropelAuth integration
+- **Error handling** - Proper JSON error responses
+
+## Self-Extracting Architecture
+
+PropelApi follows a self-extracting pattern that provides:
+
+- **No runtime dependencies** - all code lives in your application
+- **Full control** - modify any component after installation
+- **No black boxes** - transparent, readable Rails code  
+- **Easy maintenance** - standard Rails patterns throughout
+
+After installation, you can:
+- Remove the gem from your Gemfile
+- Customize all generated code
+- Maintain and extend functionality independently
+- Switch between PropelFacets and Graphiti adapters
+
+## Advanced Usage
+
+### Custom Namespaces and Versions
+```bash
+# Admin API with different namespace
+rails generate propel_api:install --namespace=admin_api --version=v2
+
+# No namespace/version
+rails generate propel_api:install --namespace=none --version=none
+```
+
+### Model Attribute Detection
+PropelApi provides intelligent attribute detection with security filtering:
+
+```bash
+# Manual attributes (no filtering)
+rails generate propel_api:controller User name:string email:string
+
+# Auto-detect with explicit flag
+rails generate propel_api:controller User --all-attributes
+
+# Auto-detect with warning (when no attributes specified)
+rails generate propel_api:controller User
+```
+
+**Security Filtering**: Sensitive attributes are automatically filtered:
+- Passwords, tokens, keys, secrets
+- Timestamps and Rails internals  
+- Large content fields
+- Binary data
+
+Customize filtering in `config/initializers/propel_api.rb`:
+```ruby
+PropelApi.attribute_filter.add_sensitive_pattern(/private_.*/)
+PropelApi.attribute_filter.add_excluded_pattern(/legacy_.*/)
+```
+
+### Relationship Patterns
+```bash
+# Standard belongs_to/has_many
+rails generate propel_api Article title:string user:references
+
+# Polymorphic associations (commentable -> Comment belongs_to :commentable, polymorphic: true)
+rails generate propel_api Comment content:text commentable:references
+
+# Resource parent pattern (resource_parent -> Attachment belongs_to :resource, polymorphic: true)  
+rails generate propel_api Attachment name:string resource_parent:references
+```
+
+### Route Generation Examples
+
+#### Nested Namespace (api/v1) 
+```ruby
+# Input routes.rb:
+Rails.application.routes.draw do
+  namespace :api do
+    namespace :v1 do
+      # Add your API routes here
+    end
+  end
+end
+
+# After: rails generate propel_api:controller User
+Rails.application.routes.draw do
+  namespace :api do
+    namespace :v1 do
+      resources :users  # ← Correctly indented with 4 spaces
+    end
+  end
+end
+```
+
+#### Single Namespace
+```ruby
+# After: rails generate propel_api:controller User --namespace=api --version=none
+Rails.application.routes.draw do
+  namespace :api do
+    resources :users  # ← Correctly indented with 2 spaces
+  end
+end
+```
+
+### Seed Data Generation
+```ruby
+# Generated seeds use Faker for realistic data
+User.create!([
+  { name: Faker::Name.name, email: Faker::Internet.email, role: 'admin' },
+  { name: Faker::Name.name, email: Faker::Internet.email, role: 'user' }
+])
+```
+
+## Dependencies
+
+### PropelFacets Adapter
+- `propel_facets` - JSON facet system (install separately)
+- `pagy` - Pagination  
+- `has_scope` - Filtering
+- `ransack` - Advanced search
+
+### Graphiti Adapter
+- `graphiti` - JSON:API resource framework
+- `graphiti-rails` - Rails integration
+- `vandal_ui` - Interactive API documentation
+
+## Route Insertion Technical Details
+
+PropelApi includes **completely fixed route insertion** that handles:
+
+### Indentation Rules
+- **Nested namespaces** (api/v1): 4 spaces for resources
+- **Single namespaces** (api): 2 spaces for resources  
+- **Rails route method**: Automatically adds 2 spaces to each line
+
+### Insertion Logic
+- Detects existing namespace structures
+- Inserts at correct position (after namespace opening)
+- Prevents duplicate routes
+- Maintains proper Rails formatting
+
+### Error Prevention
+- Validates route placement before insertion
+- Shows warnings for duplicate routes
+- Maintains file structure integrity
+
+## Documentation
+
+After installation:
+- API examples: `doc/api_controller_example.rb`
+- Configuration: `config/initializers/propel_api.rb`
+- Generated tests show usage patterns
+- Seed files demonstrate data creation
+
+## Development
+
+```bash
+# Run generator tests
+cd propel_api
+bundle exec rake test
+
+# Test route insertion specifically
+bundle exec ruby -Ilib:test test/generators/propel_api/route_insertion_test.rb
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## License
+
+The gem is available as open source under the [MIT License](https://opensource.org/licenses/MIT). 

data/Rakefile

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
+
+# Individual test tasks for better organization
+namespace :test do
+  Rake::TestTask.new(:generators) do |t|
+    t.libs << "test"
+    t.libs << "lib"
+    t.test_files = FileList["test/generators/**/*_test.rb"]
+    t.description = "Run generator tests"
+  end
+  
+  Rake::TestTask.new(:integration) do |t|
+    t.libs << "test"
+    t.libs << "lib"
+    t.test_files = FileList["test/integration/**/*_test.rb"]
+    t.description = "Run integration tests"
+  end
+end
+
+task default: :test 
+
+desc "Run all tests with verbose output"
+task :test_verbose do
+  ENV['VERBOSE'] = 'true'
+  Rake::Task[:test].invoke
+end 

data/lib/generators/propel_api/USAGE

@@ -0,0 +1,8 @@
+Description:
+    Explain the generator
+
+Example:
+    bin/rails generate propel_api Thing
+
+    This will create:
+        what/will/it/create

data/lib/generators/propel_api/controller/controller_generator.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require_relative '../core/named_base'
+require 'ostruct'
+
+##
+# PropelApi controller generator that creates API controllers, routes, and tests for existing models
+#
+# Usage:
+#   rails generate propel_api:controller User                    # Auto-introspect (with warning)
+#   rails generate propel_api:controller User --all-attributes   # Auto-introspect (explicit)
+#   rails generate propel_api:controller User name:string        # Use specified attributes
+#   rails generate propel_api:controller User --namespace=admin_api --version=v2
+#
+# Attribute Detection Priority:
+#   1. --all-attributes flag → Always introspect model attributes (with configurable filtering)
+#   2. Manual attributes → Use specified attributes (no filtering applied)
+#   3. No attributes + model exists → Auto-introspect with educational warning (with configurable filtering)
+#   4. No attributes + no model → Error (model must exist)
+#
+# Configurable Security Filtering:
+#   Filtering is controlled by PropelApi.attribute_filter in config/initializers/propel_api.rb
+#   - Sensitive patterns: passwords, tokens, keys, SSNs, etc.
+#   - Excluded patterns: timestamps, Rails internals, binary data
+#   - Large content patterns: descriptions, content, body text, etc.
+#   
+#   Customize for your project's naming conventions:
+#     PropelApi.attribute_filter.add_sensitive_pattern(/private_.*/)
+#     PropelApi.attribute_filter.add_excluded_pattern(/legacy_.*/)
+#   
+#   View current patterns: PropelApi.attribute_filter.filtering_summary
+#
+# This generator assumes the model already exists and creates:
+# - API controller with full CRUD operations
+# - Routes with proper namespacing
+# - Controller tests
+# - Integration tests
+#
+module PropelApi
+  class ControllerGenerator < PropelApi::NamedBase
+    source_root File.expand_path("../templates", __dir__)
+    
+    desc "Generate PropelApi controller, routes and tests for existing model"
+    
+    argument :attributes, type: :array, default: [], banner: "field:type field:type"
+
+    def validate_model_exists
+      # Ensure attributes are parsed before validation
+      parse_attributes_from_args
+      
+      # Only require model when auto-introspection is needed
+      model_file_exists = File.exist?(File.join(destination_root, "app/models/#{file_name}.rb"))
+      
+      if should_auto_introspect? && !model_file_exists
+        raise Thor::Error, "Model #{class_name} does not exist. Please create the model first or use 'rails generate propel_api #{class_name}' to create the complete resource."
+      end
+      
+      # Show educational warning when no explicit choice is made
+      if !options[:all_attributes] && (@attributes.nil? || @attributes.empty?) && model_file_exists
+        show_auto_introspection_warning
+      end      
+      # Validate attributes if not using introspection
+      validate_attributes_exist unless should_auto_introspect?
+    end
+
+    def create_controller
+      # Use shared method from Base class
+      create_propel_controller
+    end
+
+    def create_routes
+      # Use shared method from Base class
+      create_propel_routes
+    end
+
+    def create_tests
+      # Use shared method from Base class with controller and integration tests only
+      create_propel_tests(test_types: [:controller, :integration])
+    end
+
+    def show_completion_message
+      # Use shared completion message framework from Base class
+      generated_files = [
+        "🎮 Controller: app/controllers/#{controller_path}/#{controller_file_name}.rb",
+        "🧪 Controller Tests: test/controllers/#{controller_path}/#{controller_file_name}_test.rb",
+        "🧪 Integration Tests: test/integration/#{file_name}_api_test.rb"
+      ]
+      
+      next_steps = [
+        "Test your API: GET #{api_route_path}",
+        "Run tests: rails test test/controllers/#{controller_path}/#{controller_file_name}_test.rb",
+        "Run integration tests: rails test test/integration/#{file_name}_api_test.rb"
+      ]
+      
+      if @adapter == 'propel_facets'
+        next_steps << "Customize facets in: app/models/#{file_name}.rb"
+      end
+      
+      show_propel_completion_message(
+        resource_type: "Controller",
+        generated_files: generated_files,
+        next_steps: next_steps
+      )
+    end
+
+    private
+
+    def route_name
+      file_name.pluralize
+    end
+
+    # Controller generator helper methods
+    def attributes
+      if should_auto_introspect?
+        # Auto-introspection: either --all-attributes or no attributes specified
+        # Return introspected attributes as attribute-like objects for template compatibility
+        introspect_model_attributes.map do |attr|
+          OpenStruct.new(name: attr[:name], type: attr[:type])
+        end
+      else
+        # Manual attributes specified: use those
+        # Return cached parsed attributes, or parse them if not done yet
+        @parsed_attributes || parse_attributes_from_args
+      end
+    end
+
+    def permitted_param_names
+      if should_auto_introspect?
+        # Auto-introspection: either --all-attributes or no attributes specified
+        introspected_permitted_params
+      else
+        # Manual attributes specified: use those
+        attributes.map do |attr|
+          # Convert references to foreign key names for permitted params
+          if attr.type == :references
+            "#{attr.name}_id"
+          else
+            attr.name
+          end
+        end
+      end
+    end
+
+    def parse_attributes_from_args
+      return [] unless @attributes
+      
+      @parsed_attributes ||= @attributes.map do |attr_string|
+        # Parse "field:type" strings into attribute objects
+        if attr_string.include?(':')
+          name, type = attr_string.split(':', 2)
+          OpenStruct.new(name: name, type: type.to_sym)
+        else
+          # Default to string type if no type specified
+          OpenStruct.new(name: attr_string, type: :string)
+        end
+      end
+    end
+
+    def show_auto_introspection_warning
+      say "\n" + "="*70, :yellow
+      say "⚠️  No attributes specified - auto-detecting from #{class_name} model", :yellow
+      say "="*70, :yellow
+      
+      introspected_attrs = introspected_permitted_params
+      say "🔍 Detected attributes: #{introspected_attrs.join(', ')}", :cyan
+      
+      # Show filtering information
+      show_filtering_info
+      
+      say "\n💡 Best practice: Be explicit about your intent:", :green
+      say "   Auto-detect all: rails g propel_api:controller #{class_name} --all-attributes", :green
+      say "   Specify some:    rails g propel_api:controller #{class_name} name:string email:string", :green
+      say "="*70, :yellow
+      say ""
+    end
+
+    def show_filtering_info
+      say "\n⚠️  SECURITY NOTE:", :red
+      say "   Sensitive attributes are automatically filtered using configurable patterns.", :red
+      
+      # Try to show current filter configuration
+      begin
+        if defined?(PropelApi) && PropelApi.respond_to?(:attribute_filter)
+          filter = PropelApi.attribute_filter
+          total_patterns = filter.sensitive_patterns.size + filter.excluded_patterns.size + filter.large_content_patterns.size
+          say "   Active filtering patterns: #{total_patterns} (#{filter.sensitive_patterns.size} sensitive, #{filter.excluded_patterns.size} excluded, #{filter.large_content_patterns.size} large content)", :red
+          say "   📋 View patterns: PropelApi.attribute_filter.filtering_summary", :cyan
+          say "   🔧 Customize in: config/initializers/propel_api.rb", :cyan
+        else
+          say "   Using fallback patterns (configure in config/initializers/propel_api.rb)", :red
+        end
+      rescue => e
+        say "   Using fallback patterns (PropelApi configuration not available)", :red
+      end
+      
+      say "   🚨 Review filtering to ensure it matches your naming conventions!", :red
+    end
+
+    def should_auto_introspect?
+      # Auto-introspect when:
+      # 1. --all-attributes is explicitly passed (takes precedence over manual attributes)
+      # 2. No attributes specified AND model exists (auto-fallback with warning)
+      options[:all_attributes] || ((@attributes.nil? || @attributes.empty?) && model_exists?)
+    end
+
+    public
+  end
+end 

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'configuration_methods'
+require_relative 'path_generation_methods'
+
+##
+# Base class for all PropelApi generators
+# Provides shared configuration detection, validation, and path generation logic
+#
+module PropelApi
+  class Base < Rails::Generators::Base
+    include PropelApi::ConfigurationMethods
+    include PropelApi::PathGenerationMethods
+
+
+    
+    private
+  end
+end