propel_facets 0.1.1

data/lib/generators/propel_facets/templates/models/concerns/model_facet.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+# Helper for defining json facets for an ActiveRecord model
+#
+# This should allow you to define json facets like seen in the following
+# example. Facets are used by JSON renderers like our controllers to determine
+# which format suits better for a given situation.
+#
+# ```ruby
+# class MyModel < ApplicationRecord
+#   json_facet :short, :name, :logo
+#   json_facet :public, :email, extend: :short
+#   json_facet :agency, :address_1, :address_2, extend: :public
+# end
+# ```
+#
+# The names for the facets here are :short, :public and :agency, but you are
+# free to use any name you wish. Those are names expected to be looked by
+# our API controllers. If not facet satisfies the reader, it may choose to
+# either throw an error or fall-back to some format of his own choice.
+#
+module ModelFacet
+  extend ActiveSupport::Concern
+
+  class_methods do
+    attr_accessor :all_facets
+
+    def inherited(subclass)
+      super(subclass)
+      subclass.all_facets = @all_facets.dup
+    end
+
+    # Directive to define a JSON facet
+    #
+    # Defines a named JSON facet specification that controls how a model is serialized to JSON.
+    # The facet can include fields, methods, and nested associations.
+    #
+    # Facets from base classes are merged on declaration of a facet.
+    # Base facets for a spec are merged upon usage.
+    #
+    # @param name [Symbol] The name of the facet
+    # @param *args [Array] List of fields/methods to include
+    # @param opts [Hash] Options hash that can include:
+    #   fields: Additional fields to include
+    #   methods: Method names to call and include
+    #   include: Nested associations to include with their original names
+    #   include_as: Nested associations with custom key names in the JSON output
+    #   extend: Name of another facet to extend from
+    #
+    # The difference between include and include_as:
+    # - include: Includes associations using their model name as the JSON key
+    #   Example: include: [:posts] => {"posts": [...]}
+    #
+    # - include_as: Includes associations with a custom key name in the JSON
+    #   Example: include_as: [comments: :replies] => {"replies": [...]}
+    #
+    # @example Basic facet with fields
+    #   json_facet :basic, :id, :name, :email
+    #   # => {"id": 1, "name": "John", "email": "john@example.com"}
+    #
+    # @example Complex facet showing include vs include_as
+    #   json_facet :detailed, 
+    #     :id, :name,
+    #     methods: [:full_name],
+    #     include: [:posts],              # Will appear as "posts" in JSON
+    #     include_as: [comments: :replies] # Will appear as "replies" in JSON
+    #   # => {
+    #   #   "id": 1,
+    #   #   "name": "John", 
+    #   #   "full_name": "John Smith",
+    #   #   "posts": [...],     # Original association name
+    #   #   "replies": [...]    # Custom key name
+    #   # }
+    def json_facet(name, *args)
+      opts = args.extract_options!
+      @all_facets = {} if @all_facets.nil?
+      spec = opts.merge(
+        fields: [opts[:fields] || []].flatten,
+        include: [opts[:include] || []].flatten,
+        include_as: [opts[:include_as] || []].flatten,
+        methods: [opts[:methods] || []].flatten
+      )
+      existing = @all_facets.fetch(name, {})
+      @all_facets[name] = merge_facet existing, spec
+    end
+
+    # Gets base facet to be extended
+    def base_facet(name)
+      if name.nil?
+        { fields: [], include: [], include_as: [], methods: [] }
+      elsif @all_facets.include? name.to_sym
+        @all_facets[name.to_sym]
+      else
+        warn "[FACET BASE] `#{name}` JSON facet not found to be a extended"
+        { fields: [], include: [], include_as: [], methods: [] }
+      end
+    end
+
+    # Merges a base facet with another facet definition
+    def merge_facet(*args)
+      a, b = args.shift(2)
+      extended_lists = {
+        fields: [b[:fields], a[:fields]].flatten.uniq.excluding(nil),
+        include: [b[:include], a[:include]].flatten.uniq.excluding(nil),
+        include_as: [b[:include_as], a[:include_as]].flatten.uniq.excluding(nil),
+        methods: [b[:methods], a[:methods]].flatten.uniq.excluding(nil)
+      }
+      extended = a.merge(b).merge(extended_lists)
+      return extended if args.empty?
+
+      merge_facet(extended, *args)
+    end
+
+    # Helps getting a facet after a given value
+    #
+    # This value can point to either a symbol, an array or even be nil.
+    # A symbol and an array with one symbol will behave exactly the same.
+    # If nil or an empty array is given, then this will return nil.
+    # While processing an array of symbols this will return the first facet
+    # it finds registered for current model. If none is found, returns nil.
+    def find_facet(names, missing: :noaction)
+      @all_facets = {} if @all_facets.nil?
+      array = [names].flatten
+      facet = array.find { |name| @all_facets.include? name }
+      if facet.nil?
+        case missing
+        when :noaction
+          nil
+        when :error
+          raise MissingFacet
+        end
+      else
+        @all_facets[facet]
+      end
+    end
+
+    # Returns spec with its base spec merged
+    #
+    # If base spec has any base chain, those will be merged recursively.
+    #
+    def extend_base(spec)
+      if spec.include? :base
+        base = base_facet(spec[:base])
+        nobase_spec = spec.dup
+        nobase_spec.delete :base
+        extended = merge_facet(base, nobase_spec)
+        extend_base extended
+      else
+        spec
+      end
+    end
+
+    # Builds a `serializable_hash` options object after a facet spec
+    def facet_serializable_options(name, spec)
+      actual = extend_base(spec)
+      include_as = (actual[:include_as] + [name]).flatten.uniq
+      include = actual[:include].reduce({}) do |memo, current|
+        memo.update(current => { facet: include_as })
+      end
+      { only: actual[:fields], include: include, methods: actual[:methods] }
+    end
+  end
+
+  # Public model method to allow getting JSON facet
+  def serializable_hash(options = nil)
+    injected = inject_facet(options)
+    hash = super(injected)
+    hash['id'] = id
+    hash['type'] = model_name.element.pluralize.underscore.dasherize
+    hash
+  end
+
+  # Inject our facet options to this model
+  def inject_facet(options = nil)
+    if options&.include? :facet
+      missing = options.fetch(:missing, :error)
+      name = options[:facet]
+      facet = self.class.find_facet(name, missing: missing)
+      if facet.nil?
+        options
+      else
+        extra = self.class.facet_serializable_options(name, facet)
+        options.merge(extra).except(:facet, :missing)
+      end
+    else
+      options
+    end
+  end
+end 

data/lib/generators/propel_facets/test/propel_facets_generator_test.rb

@@ -0,0 +1,75 @@
+require "test_helper"
+require_relative "../propel_facets_generator"
+
+class PropelFacetsGeneratorTest < Rails::Generators::TestCase
+  tests PropelFacetsGenerator
+  destination Rails.root.join("tmp/generators")
+  setup :prepare_destination
+
+  test "generator runs without errors" do
+    assert_nothing_raised do
+      run_generator
+    end
+  end
+
+  test "generates all required files" do
+    run_generator
+
+    # Model concerns
+    assert_file "app/models/concerns/model_facet.rb"
+    
+    # Controller concerns  
+    assert_file "app/controllers/concerns/facet_renderer.rb"
+    assert_file "app/controllers/concerns/strong_params_helper.rb"
+    
+    # Utility classes
+    assert_file "lib/api_params.rb"
+    
+    # Error classes
+    assert_file "app/errors/application_error.rb"
+    assert_file "app/errors/missing_facet.rb"
+    
+    # Documentation
+    assert_file "doc/json_facet.md"
+    
+    # ApplicationRecord
+    assert_file "app/models/application_record.rb"
+  end
+
+  test "generates files with correct content" do
+    run_generator
+
+    assert_file "app/models/concerns/model_facet.rb" do |content|
+      assert_match(/module ModelFacet/, content)
+      assert_match(/def json_facet/, content)
+    end
+
+    assert_file "app/controllers/concerns/facet_renderer.rb" do |content|
+      assert_match(/module FacetRenderer/, content)
+      assert_match(/def connect_facet/, content)
+    end
+
+    assert_file "lib/api_params.rb" do |content|
+      assert_match(/class ApiParams/, content)
+      assert_match(/def permit/, content)
+    end
+  end
+
+  test "template structure is properly organized" do
+    # Verify the template files exist in organized structure
+    assert File.exist?(File.join(source_root, "models/concerns/model_facet.rb"))
+    assert File.exist?(File.join(source_root, "controllers/concerns/facet_renderer.rb"))
+    assert File.exist?(File.join(source_root, "controllers/concerns/strong_params_helper.rb"))
+    assert File.exist?(File.join(source_root, "lib/api_params.rb"))
+    assert File.exist?(File.join(source_root, "errors/application_error.rb"))
+    assert File.exist?(File.join(source_root, "errors/missing_facet.rb"))
+    assert File.exist?(File.join(source_root, "doc/json_facet.md"))
+    assert File.exist?(File.join(source_root, "models/application_record.rb"))
+  end
+
+  private
+
+  def source_root
+    File.expand_path("../templates", __FILE__)
+  end
+end 

data/lib/generators/propel_facets/test/test_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'rails/all'
+require 'rails/generators'
+require 'rails/generators/test_case'
+
+# Configure Rails.application as this generator requires it
+module Dummy
+  class Application < Rails::Application
+    config.root = __dir__
+    config.session_store :cookie_store, key: '_dummy_session'
+    config.secret_key_base = 'dummy_secret_key_base'
+    config.eager_load = false
+    config.active_support.deprecation = :log
+    config.active_support.test_order = :random
+  end
+end
+
+Rails.application = Dummy::Application.new
+Rails.application.initialize! 

data/lib/generators/propel_facets/unpack_generator.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+##
+# PropelFacets unpacker that extracts the FACETS GENERATOR into the host application
+#
+# Usage:
+#   rails generate propel_facets:unpack                 # Unpack entire generator (code + templates)
+#   rails generate propel_facets:unpack --force         # Overwrite existing generator files
+#   rails generate propel_facets:unpack --templates-only # Only copy templates, not generator logic
+#   rails generate propel_facets:unpack --models-only   # Only copy model templates
+#   rails generate propel_facets:unpack --controllers-only # Only copy controller templates
+#   rails generate propel_facets:unpack --errors-only   # Only copy error templates
+#   rails generate propel_facets:unpack --lib-only      # Only copy lib templates
+#   rails generate propel_facets:unpack --docs-only     # Only copy documentation templates
+#
+# This extracts the PropelFacets generator from the gem into lib/generators/propel_facets/
+# so you can customize the generator logic and templates for your specific needs.
+#
+module PropelFacets
+  class UnpackGenerator < Rails::Generators::Base
+    source_root File.expand_path("templates", __dir__)
+    
+    desc "Extract PropelFacets generator code from gem to lib/generators/propel_facets/ for full customization"
+
+    class_option :force,
+                 type: :boolean,
+                 default: false,
+                 desc: "Overwrite existing generator files"
+
+    class_option :templates_only,
+                 type: :boolean,
+                 default: false,
+                 desc: "Extract only generator templates, not generator logic"
+
+    class_option :models_only,
+                 type: :boolean,
+                 default: false,
+                 desc: "Extract only model generator templates"
+
+    class_option :controllers_only,
+                 type: :boolean,
+                 default: false,
+                 desc: "Extract only controller generator templates"
+
+    class_option :errors_only,
+                 type: :boolean,
+                 default: false,
+                 desc: "Extract only error generator templates"
+
+    class_option :lib_only,
+                 type: :boolean,
+                 default: false,
+                 desc: "Extract only lib generator templates"
+
+    class_option :docs_only,
+                 type: :boolean,
+                 default: false,
+                 desc: "Extract only documentation generator templates"
+
+    def unpack_propel_facets_generator
+      show_welcome_message
+      
+      components_to_unpack = determine_components
+      destination_path = "lib/generators/propel_facets"
+      
+      if File.exist?(destination_path) && !options[:force]
+        say "⚠️  #{destination_path} already exists (use --force to overwrite)", :yellow
+        return
+      end
+
+      say "📦 Extracting PropelFacets generator components: #{components_to_unpack.join(', ')}", :green
+      say ""
+
+      unpack_components(components_to_unpack, destination_path)
+      show_completion_message(destination_path)
+    end
+
+    private
+
+    def show_welcome_message
+      say ""
+      say "╔══════════════════════════════════════╗", :cyan
+      say "║    PROPEL FACETS GENERATOR UNPACKER  ║", :cyan  
+      say "╚══════════════════════════════════════╝", :cyan
+      say ""
+      say "This extracts the PropelFacets GENERATOR from the gem into your application", :blue
+      say "at lib/generators/propel_facets/ so you can customize generator logic and templates.", :blue
+      say ""
+      say "📦 FROM: Gem-based generator (black box)", :yellow
+      say "📁 TO:   Local generator in lib/generators/propel_facets/ (fully customizable)", :green
+      say ""
+    end
+
+    def determine_components
+      if options[:models_only]
+        return %w[models]
+      elsif options[:controllers_only]
+        return %w[controllers]
+      elsif options[:errors_only]
+        return %w[errors]
+      elsif options[:lib_only]
+        return %w[lib]
+      elsif options[:docs_only]
+        return %w[docs]
+      elsif options[:templates_only]
+        return %w[models controllers errors lib docs]
+      else
+        # Default: everything including generator logic
+        return %w[models controllers errors lib docs generator_logic]
+      end
+    end
+
+    def unpack_components(components, destination_path)
+      FileUtils.mkdir_p(destination_path)
+      
+      components.each do |component|
+        unpack_component(component, destination_path)
+      end
+    end
+
+    def unpack_component(component, destination_path)
+      case component
+      when 'models'
+        copy_model_templates(destination_path)
+      when 'controllers'
+        copy_controller_templates(destination_path)
+      when 'errors'
+        copy_error_templates(destination_path)
+      when 'lib'
+        copy_lib_templates(destination_path)
+      when 'docs'
+        copy_doc_templates(destination_path)
+      when 'generator_logic'
+        copy_generator_logic(destination_path)
+      else
+        say "   ⚠️  Unknown component: #{component}", :red
+      end
+    end
+
+    def copy_model_templates(destination_path)
+      say "📂 Extracting model generator templates...", :blue
+      
+      copy_directory_templates("models", destination_path)
+      
+      say "   ✅ Model generator templates extracted", :green
+    end
+
+    def copy_controller_templates(destination_path)
+      say "📂 Extracting controller generator templates...", :blue
+      
+      copy_directory_templates("controllers", destination_path)
+      
+      say "   ✅ Controller generator templates extracted", :green
+    end
+
+    def copy_error_templates(destination_path)
+      say "📂 Extracting error generator templates...", :blue
+      
+      copy_directory_templates("errors", destination_path)
+      
+      say "   ✅ Error generator templates extracted", :green
+    end
+
+    def copy_lib_templates(destination_path)
+      say "📂 Extracting lib generator templates...", :blue
+      
+      copy_directory_templates("lib", destination_path)
+      
+      say "   ✅ Lib generator templates extracted", :green
+    end
+
+    def copy_doc_templates(destination_path)
+      say "📂 Extracting documentation generator templates...", :blue
+      
+      copy_directory_templates("doc", destination_path)
+      
+      say "   ✅ Documentation generator templates extracted", :green
+    end
+
+    def copy_generator_logic(destination_path)
+      say "📂 Extracting generator logic code...", :blue
+      
+      # Copy the main generator files with proper Rails registration
+      generator_files = {
+        'install_generator.rb' => 'install_generator.rb',
+        'propel_facets.rb' => 'propel_facets.rb'
+      }
+      
+      copied_count = 0
+      generator_files.each do |source_name, dest_name|
+        source_file = File.join(File.dirname(__dir__), source_name)
+        dest_file = File.join(destination_path, dest_name)
+        
+        if File.exist?(source_file)
+          if source_name == 'install_generator.rb'
+            # Copy install generator with proper Rails namespace for host app
+            source_content = File.read(source_file)
+            
+            # Ensure proper module structure for Rails generator registration
+            modified_content = source_content.gsub(
+              /^class PropelFacets::InstallGenerator/,
+              "module PropelFacets\n  class InstallGenerator"
+            )
+            
+            # Add module end if we added module start
+            if modified_content != source_content
+              modified_content += "\nend" unless modified_content.end_with?("end\n") || modified_content.end_with?("end")
+            end
+            
+            FileUtils.mkdir_p(File.dirname(dest_file))
+            File.write(dest_file, modified_content)
+          else
+            # Copy other files normally
+          FileUtils.cp(source_file, dest_file)
+          end
+          copied_count += 1
+        else
+          say "   ⚠️  Generator file not found: #{source_name}", :yellow
+        end
+      end
+      
+      # Also copy test directory if it exists
+      test_source_dir = File.join(File.dirname(__dir__), "test")
+      test_dest_dir = File.join(destination_path, "test")
+      
+      if Dir.exist?(test_source_dir)
+        copy_directory_recursively(test_source_dir, test_dest_dir)
+        copied_count += 1
+        say "   📋 Test directory copied", :blue
+      end
+      
+      if copied_count > 0
+        say "   ✅ Generator logic code extracted with proper Rails registration (#{copied_count} files/directories)", :green
+      else
+        say "   ⚠️  No generator logic files found", :yellow
+      end
+    end
+
+    def copy_directory_templates(directory, destination_path)
+      source_dir = File.join(self.class.source_root, directory)
+      dest_dir = File.join(destination_path, "templates", directory)
+      
+      if Dir.exist?(source_dir)
+        FileUtils.mkdir_p(dest_dir)
+        copy_directory_recursively(source_dir, dest_dir)
+      else
+        say "   ⚠️  Directory not found: #{directory}", :yellow
+      end
+    end
+
+    def copy_directory_recursively(source, destination)
+      Dir.glob("#{source}/**/*", File::FNM_DOTMATCH).each do |source_file|
+        next if File.directory?(source_file)
+        next if File.basename(source_file).start_with?('.')
+        
+        relative_path = source_file.sub("#{source}/", '')
+        dest_file = File.join(destination, relative_path)
+        
+        FileUtils.mkdir_p(File.dirname(dest_file))
+        FileUtils.cp(source_file, dest_file)
+      end
+    end
+
+    def show_completion_message(destination_path)
+      say ""
+      say "🎉 PropelFacets GENERATOR unpacked successfully!", :green
+      say ""
+      say "📁 Generator extracted to: #{destination_path}/", :bold
+      say "📂 Templates available at: #{destination_path}/templates/", :bold
+      say ""
+      
+      say "🔧 GENERATOR customization guide:", :bold
+      say "   ⚙️  Main generator: #{destination_path}/propel_facets_generator.rb"
+      say "   📝 Model templates: #{destination_path}/templates/models/"
+      say "   🎮 Controller templates: #{destination_path}/templates/controllers/"
+      say "   🚨 Error templates: #{destination_path}/templates/errors/"
+      say "   📚 Lib templates: #{destination_path}/templates/lib/"
+      say "   📖 Documentation: #{destination_path}/templates/doc/"
+      say "   🧪 Tests: #{destination_path}/test/"
+      say ""
+      
+      say "⚠️  Important: You now have a LOCAL GENERATOR, not gem generator:", :yellow
+      say "   • Your local generator overrides the gem version completely"
+      say "   • Customize any part: logic, templates, options, behavior"
+      say "   • Commit generator code to version control"
+      say "   • Update manually when PropelFacets gem is updated"
+      say ""
+      
+      say "💡 Test your customized generator:", :blue
+      say "   # Your local generator will be used instead of the gem:"
+      say "   rails generate propel_facets"
+      say ""
+      
+      say "🔄 To use gem generator again:", :cyan
+      say "   rm -rf #{destination_path}  # Removes local generator, falls back to gem"
+      say ""
+      
+      say "🚀 Now you can:", :green
+      say "   • Modify facet templates for your organization's JSON standards"
+      say "   • Customize model concern behavior and default facets"
+      say "   • Add custom error handling for your API patterns"
+      say "   • Create company-specific facet naming conventions"
+      say "   • Extend the JSON serialization capabilities"
+      say "   • Add new utility classes for API parameter handling"
+    end
+  end
+end 

data/lib/propel_facets.rb

@@ -0,0 +1,3 @@
+module PropelFacets
+  VERSION = "0.1.1"
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: propel_facets
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Propel Team
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-07-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+description: A Rails generator that provides a flexible system for defining different
+  JSON representations of ActiveRecord models and automatically connecting them to
+  controller actions.
+email:
+- admin@propel-hq.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/generators/propel_facets/README.md
+- lib/generators/propel_facets/USAGE
+- lib/generators/propel_facets/install_generator.rb
+- lib/generators/propel_facets/templates/config/propel_facets.rb
+- lib/generators/propel_facets/templates/controllers/concerns/facet_renderer.rb
+- lib/generators/propel_facets/templates/controllers/concerns/strong_params_helper.rb
+- lib/generators/propel_facets/templates/doc/json_facet.md
+- lib/generators/propel_facets/templates/errors/application_error.rb
+- lib/generators/propel_facets/templates/errors/missing_facet.rb
+- lib/generators/propel_facets/templates/lib/api_params.rb
+- lib/generators/propel_facets/templates/models/application_record.rb
+- lib/generators/propel_facets/templates/models/concerns/model_facet.rb
+- lib/generators/propel_facets/test/propel_facets_generator_test.rb
+- lib/generators/propel_facets/test/test_helper.rb
+- lib/generators/propel_facets/unpack_generator.rb
+- lib/propel_facets.rb
+homepage: https://github.com/propel-hq/propel_rails.git
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/propel-hq/propel_rails.git
+  source_code_uri: https://github.com/propel-hq/propel_rails.git
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Rails generator for flexible JSON representations
+test_files: []