dscf-core 0.1.7 → 0.1.8

data/lib/generators/common/USAGE

@@ -0,0 +1,39 @@
+This generator creates a fully functional API resource for a given model using DSCF conventions.
+
+Usage:
+    rails generate common NAMESPACE::ModelName [options]
+
+Options:
+    --only COMPONENT1 COMPONENT2  Only generate specific components
+    --skip COMPONENT1 COMPONENT2  Skip generating specific components
+
+Available components: controller, serializer, request_spec, routes, locales, model
+
+Examples:
+    rails generate common Dscf::Core::User
+    rails generate common UserProfile
+    rails generate common Billing::Invoice
+    rails generate common Dscf::Core::Role --only serializer request_spec
+    rails generate common UserProfile --skip routes locales
+
+Note: Use space-separated values for --only/--skip options.
+Do not use multiple --only/--skip flags as they will override each other.
+
+Automatic Serializer Generation:
+    When generating a serializer, the generator analyzes model associations and
+    prompts to create missing serializers for associated models. This helps ensure
+    complete API serialization without manual tracking of dependencies.
+
+    • Detects missing serializers for belongs_to, has_many, has_one associations
+    • Interactive prompts with clear feedback
+    • Recursion protection prevents infinite loops in circular associations
+    • Can be declined to generate serializers manually later
+
+Notes:
+    • If the model file exists, `ransackable_attributes` and `ransackable_associations`
+    will be added just above any `private` section (or at the bottom of the class).
+    • The generator uses introspection to avoid adding insecure attributes (e.g. password fields).
+    • Existing route entries, ransackable methods, or locales are not duplicated.
+    • If a model file is missing, serializer and ransack methods are skipped.
+
+This generator is engine-aware and respects module namespaces.

data/lib/generators/common/common_generator.rb

@@ -0,0 +1,579 @@
+require "rails/generators"
+require "rails/generators/named_base"
+
+class CommonGenerator < Rails::Generators::NamedBase
+  VALID_COMPONENTS = %w[
+    controller
+    serializer
+    request_spec
+    routes
+    locales
+    model
+  ].freeze
+
+  source_root File.expand_path("templates", __dir__)
+  desc File.read(File.expand_path("USAGE", __dir__))
+
+  class_option :only, type: :array, default: [],
+                      desc: "Only generate specific components (controller, serializer, request_spec, routes, locales, model)"
+  class_option :skip, type: :array, default: [],
+                      desc: "Skip generating specific components (controller, serializer, request_spec, routes, locales, model)"
+  class_option :_recursive, type: :boolean, default: false,
+                            desc: "Internal flag to prevent recursive serializer generation prompts"
+
+  def validate_generator_options
+    validate_options!
+  end
+
+  def validate_options!
+    invalid_only = options[:only] - VALID_COMPONENTS
+    invalid_skip = options[:skip] - VALID_COMPONENTS
+
+    if invalid_only.any?
+      raise Thor::Error,
+            "Invalid values for --only: #{invalid_only.join(', ')}. Allowed values: #{VALID_COMPONENTS.join(', ')}"
+    end
+
+    return unless invalid_skip.any?
+
+    raise Thor::Error,
+          "Invalid values for --skip: #{invalid_skip.join(', ')}. Allowed values: #{VALID_COMPONENTS.join(', ')}"
+  end
+
+  def create_controller
+    return unless should_generate?("controller")
+
+    template "controller.rb.erb", controller_file_path
+  end
+
+  def create_serializer
+    return unless should_generate?("serializer")
+    return unless model_exists?
+
+    # Only check for missing serializers when creating (not destroying) and not in recursive generation
+    check_and_prompt_for_missing_serializers unless behavior == :revoke || recursive_generation?
+
+    template "serializer.rb.erb", serializer_file_path
+  end
+
+  def create_request_spec
+    return unless should_generate?("request_spec")
+
+    template "request_spec.rb.erb", request_spec_file_path
+  end
+
+  def update_model_with_ransackable_methods
+    return unless should_generate?("model")
+    return unless model_exists?
+    return unless model_file_exists?
+
+    add_ransackable_methods_to_model
+  end
+
+  def add_routes
+    return unless should_generate?("routes")
+
+    route_definition = "  resources :#{route_name}"
+
+    if File.exist?(routes_file_path)
+      # Check if route already exists
+      unless File.read(routes_file_path).include?("resources :#{route_name}")
+        # Try to inject after engine routes draw or Rails routes draw
+        routes_content = File.read(routes_file_path)
+        if routes_content.include?("Engine.routes.draw do")
+          inject_into_file routes_file_path, "#{route_definition}\n", after: /\.routes\.draw do\n/
+        elsif routes_content.include?("Rails.application.routes.draw do")
+          inject_into_file routes_file_path, "#{route_definition}\n", after: /Rails\.application\.routes\.draw do\n/
+        else
+          # Fallback: append to the end before the last 'end'
+          inject_into_file routes_file_path, "#{route_definition}\n", before: /^end\s*$/
+        end
+      end
+    else
+      create_file routes_file_path, <<~ROUTES
+        Rails.application.routes.draw do
+        #{route_definition}
+        end
+      ROUTES
+    end
+  end
+
+  def add_locale_entries
+    return unless should_generate?("locales")
+
+    locale_entries = generate_locale_entries
+    indented_entries = indent_locale_block(locale_entries, 2)
+
+    if File.exist?(locale_file_path)
+      model_key = model_class_name.underscore
+      append_to_file locale_file_path, "\n\n#{indented_entries}" unless File.read(locale_file_path).include?("#{model_key}:")
+    else
+      create_file locale_file_path, <<~LOCALE
+          en:
+        #{indented_entries}
+      LOCALE
+    end
+  end
+
+  private
+
+  def recursive_generation?
+    options[:_recursive] == true
+  end
+
+  def should_generate?(component)
+    return false if options[:skip].include?(component)
+    return true if options[:only].empty?
+
+    options[:only].include?(component)
+  end
+
+  # Name parsing methods
+  def resource_class_name
+    @resource_class_name ||= name
+  end
+
+  def controller_class_name
+    "#{model_class_name.pluralize}Controller"
+  end
+
+  def model_class_name
+    if resource_class_name.include?("::")
+      resource_class_name.split("::").last.singularize
+    else
+      resource_class_name.singularize
+    end
+  end
+
+  def controller_name
+    model_class_name.pluralize.underscore
+  end
+
+  def route_name
+    controller_name
+  end
+
+  def factory_name
+    resource_class_name.underscore.tr("/", "_")
+  end
+
+  # File path methods
+  def namespace_path
+    if resource_class_name.include?("::")
+      resource_class_name.deconstantize.underscore.gsub("::", "/")
+    else
+      ""
+    end
+  end
+
+  def controller_file_path
+    if namespace_path.present?
+      "app/controllers/#{namespace_path}/#{controller_name}_controller.rb"
+    else
+      "app/controllers/#{controller_name}_controller.rb"
+    end
+  end
+
+  def serializer_file_path
+    if namespace_path.present?
+      "app/serializers/#{namespace_path}/#{model_class_name.underscore}_serializer.rb"
+    else
+      "app/serializers/#{model_class_name.underscore}_serializer.rb"
+    end
+  end
+
+  def request_spec_file_path
+    if namespace_path.present?
+      "spec/requests/#{namespace_path}/#{controller_name}_spec.rb"
+    else
+      "spec/requests/#{controller_name}_spec.rb"
+    end
+  end
+
+  def routes_file_path
+    "config/routes.rb"
+  end
+
+  def locale_file_path
+    "config/locales/en.yml"
+  end
+
+  def model_file_path
+    if namespace_path.present?
+      "app/models/#{namespace_path}/#{model_class_name.underscore}.rb"
+    else
+      "app/models/#{model_class_name.underscore}.rb"
+    end
+  end
+
+  # Model introspection methods
+  def model_exists?
+    resource_class_name.constantize
+    true
+  rescue NameError
+    raise Thor::Error, <<~ERROR if should_generate?("serializer") || should_generate?("model")
+      Model `#{resource_class_name}` not found.
+      Make sure it exists, or skip model-dependent components using:
+        --skip model serializer
+    ERROR
+
+    false
+  end
+
+  def model_file_exists?
+    File.exist?(model_file_path)
+  end
+
+  def model_class
+    @model_class ||= resource_class_name.constantize
+  end
+
+  def model_attributes
+    return [] unless model_exists?
+
+    excluded_columns = %w[id created_at updated_at]
+
+    model_class.column_names.reject do |column|
+      column.end_with?("_id") || excluded_columns.include?(column)
+    end
+  end
+
+  def model_associations
+    return [] unless model_exists?
+
+    model_class.reflect_on_all_associations.map do |association|
+      # Get the actual class name by trying to constantize it
+      # This handles cases where Rails infers the class name based on the association name
+      actual_class_name = begin
+        association.klass.name
+      rescue NameError
+        # If the class can't be loaded, fall back to the association's class_name
+        association.class_name
+      end
+
+      {
+        name: association.name,
+        macro: association.macro,
+        class_name: actual_class_name
+      }
+    end
+  end
+
+  # Ransackable methods
+  def sensitive_attributes
+    %w[
+      password password_digest password_confirmation
+      token api_key secret_key access_token refresh_token
+      salt encrypted_password reset_password_token
+      confirmation_token unlock_token authentication_token
+      otp_secret_key single_access_token perishable_token
+      remember_token remember_created_at current_sign_in_at
+      last_sign_in_at current_sign_in_ip last_sign_in_ip
+      failed_attempts locked_at
+    ]
+  end
+
+  def safe_ransackable_attributes
+    return [] unless model_exists?
+
+    all_attributes = model_class.column_names
+    all_attributes.reject do |attr|
+      sensitive_attributes.any? { |sensitive| attr.downcase.include?(sensitive.downcase) }
+    end
+  end
+
+  def safe_ransackable_associations
+    return [] unless model_exists?
+
+    model_associations.map { |assoc| assoc[:name].to_s }
+  end
+
+  def model_has_ransackable_methods?
+    return false unless model_file_exists?
+
+    model_content = File.read(model_file_path)
+
+    # Check for existing methods
+    has_attributes_method = model_content.match?(/def\s+self\.ransackable_attributes(\s*\(.*\))?\s*$/)
+    has_associations_method = model_content.match?(/def\s+self\.ransackable_associations(\s*\(.*\))?\s*$/)
+
+    has_attributes_method || has_associations_method
+  end
+
+  def add_ransackable_methods_to_model
+    return unless model_file_exists?
+    return if model_has_ransackable_methods?
+
+    model_content = File.read(model_file_path)
+
+    # Determine the appropriate indentation by looking at existing methods
+    indentation = detect_model_indentation(model_content)
+
+    ransackable_methods = <<~RUBY
+
+      #{indentation}def self.ransackable_attributes(auth_object = nil)
+      #{indentation}  %w[#{safe_ransackable_attributes.join(' ')}]
+      #{indentation}end
+
+      #{indentation}def self.ransackable_associations(auth_object = nil)
+      #{indentation}  %w[#{safe_ransackable_associations.join(' ')}]
+      #{indentation}end
+    RUBY
+
+    # Strategy 1: Place just before 'private' if it exists and is properly indented
+    if model_content.match?(/^\s*private\s*$/)
+      inject_into_file model_file_path, ransackable_methods, before: /^\s*private\s*$/
+    # Strategy 2: Place just before 'protected' if it exists (but no private)
+    elsif model_content.match?(/^\s*protected\s*$/)
+      inject_into_file model_file_path, ransackable_methods, before: /^\s*protected\s*$/
+    # Strategy 3: Place before the last 'end' of the class (try to find the class end)
+    else
+      # Look for the last 'end' that closes the class
+      inject_into_file model_file_path, ransackable_methods, before: /^#{indentation.chomp}end\s*$|^end\s*$/
+    end
+  end
+
+  def detect_model_indentation(model_content)
+    # Look for existing method definitions to determine indentation
+    method_match = model_content.match(/^(\s+)def\s+/)
+    if method_match
+      method_match[1]
+    else
+      # Fallback: look for any line that's indented within the class
+      line_match = model_content.match(/^(\s+)\w+/)
+      if line_match
+        line_match[1]
+      else
+        "  " # Default to 2 spaces
+      end
+    end
+  end
+
+  def serializer_attributes
+    return ":id, :created_at, :updated_at" unless model_exists?
+
+    base_attrs = %w[id]
+    custom_attrs = model_attributes.reject { |attr| is_sensitive_attribute?(attr) }
+    timestamp_attrs = %w[created_at updated_at]
+
+    all_attrs = (base_attrs + custom_attrs + timestamp_attrs)
+    ":#{all_attrs.join(', :')}"
+  end
+
+  def serializer_associations
+    return {} unless model_exists?
+
+    grouped_associations = {}
+
+    model_associations.group_by { |assoc| assoc[:macro] }.each do |macro, associations|
+      grouped_associations[macro] = associations.map do |association|
+        # Only try to find/suggest serializers when creating (not destroying)
+        serializer_name = if behavior == :revoke
+                            # For destroy mode, just use the basic serializer name without checking
+                            if association[:class_name].include?("::")
+                              namespace_parts = association[:class_name].split("::")
+                              "#{namespace_parts.last}Serializer"
+                            else
+                              "#{association[:class_name]}Serializer"
+                            end
+                          else
+                            find_or_suggest_serializer(association[:class_name])
+                          end
+
+        {
+          name: association[:name],
+          class_name: association[:class_name],
+          serializer: serializer_name
+        }
+      end
+    end
+
+    grouped_associations
+  end
+
+  # Check if an attribute is sensitive and should be excluded from serializers
+  def is_sensitive_attribute?(attr_name)
+    sensitive_attributes.any? { |sensitive| attr_name.downcase.include?(sensitive.downcase) }
+  end
+
+  # Find existing serializer or suggest a name for one
+  def find_or_suggest_serializer(class_name)
+    # Handle namespaced classes
+    if class_name.include?("::")
+      namespace_parts = class_name.split("::")
+      model_name = namespace_parts.last
+      namespace = namespace_parts[0..-2].join("::")
+      suggested_name = "#{model_name}Serializer"
+      serializer_class_name = "#{namespace}::#{suggested_name}"
+    else
+      suggested_name = "#{class_name}Serializer"
+      serializer_class_name = suggested_name
+    end
+
+    # Check if serializer file exists (more reliable than constantize during generation)
+    serializer_file = serializer_file_path_for_class(class_name)
+    if File.exist?(serializer_file)
+      serializer_class_name
+    else
+      # Return suggested name, will be used in template
+      suggested_name
+    end
+  end
+
+  # Check for missing serializers and prompt user
+  def check_and_prompt_for_missing_serializers
+    missing_serializers = find_missing_serializers
+    return if missing_serializers.empty?
+    return unless behavior == :invoke # Only prompt on generate, not destroy
+
+    say "\n🔍  Detected associations without serializers:", :yellow
+    missing_serializers.each do |missing|
+      say "      • #{missing[:association_name]} (#{missing[:class_name]}) -> #{missing[:suggested_serializer]}"
+    end
+
+    say "\n🛠️   Would you like to generate the missing serializers now? (y/n)", :green
+    if yes?("")
+      say "\n🚀  Generating missing serializers...\n"
+      generate_missing_serializers_safely(missing_serializers)
+      say "✅  All missing serializers have been generated.\n", :green
+    else
+      say "\n🛑  Skipping serializer generation.\n", :yellow
+      say "ℹ️   You can generate them later with:", :blue
+      missing_serializers.each do |missing|
+        say "      rails generate common #{missing[:class_name]} --only serializer"
+      end
+      say ""
+    end
+  end
+
+  # Generate missing serializers safely without recursion
+  def generate_missing_serializers_safely(missing_serializers)
+    missing_serializers.each do |missing|
+      serializer_path = serializer_file_path_for_class(missing[:class_name])
+
+      if File.exist?(serializer_path)
+        say "      exists  #{serializer_path}", :blue
+        next
+      end
+      begin
+        args = [missing[:class_name]]
+        opts = {only: ["serializer"], _recursive: true} # Add your recursive flag if needed
+
+        generator = self.class.new(args, opts, {
+                                     behavior: :invoke,
+                                     destination_root: destination_root,
+                                     shell: shell # Uses current shell; can customize if you want silence
+                                   })
+
+        generator.invoke_all
+
+        say "      ✅  Created #{missing[:suggested_serializer]}"
+      rescue StandardError => e
+        say "      ❌  Failed to create #{missing[:suggested_serializer]}: #{e.message}", :red
+      end
+    end
+  end
+
+  # Find all missing serializers for associations
+  def find_missing_serializers
+    missing = []
+
+    serializer_associations.each_value do |associations|
+      associations.each do |association|
+        class_name = association[:class_name]
+
+        next if class_name.start_with?("ActiveStorage::")
+
+        # Check if serializer file exists
+        serializer_file = serializer_file_path_for_class(class_name)
+
+        next if File.exist?(serializer_file)
+
+        # Try to find the serializer
+        if class_name.include?("::")
+          namespace_parts = class_name.split("::")
+          model_name = namespace_parts.last
+          namespace = namespace_parts[0..-2].join("::")
+          suggested_serializer = "#{model_name}Serializer"
+          full_serializer_name = "#{namespace}::#{suggested_serializer}"
+        else
+          suggested_serializer = "#{class_name}Serializer"
+          full_serializer_name = suggested_serializer
+        end
+
+        missing << {
+          association_name: association[:name],
+          class_name: class_name,
+          suggested_serializer: suggested_serializer,
+          full_serializer_name: full_serializer_name
+        }
+      end
+    end
+
+    missing.uniq { |m| m[:class_name] }
+  end
+
+  # Get serializer file path for a given class name
+  def serializer_file_path_for_class(class_name)
+    if class_name.include?("::")
+      namespace_parts = class_name.split("::")
+      model_name = namespace_parts.last
+      namespace_path = namespace_parts[0..-2].join("/").underscore
+      "app/serializers/#{namespace_path}/#{model_name.underscore}_serializer.rb"
+    else
+      "app/serializers/#{class_name.underscore}_serializer.rb"
+    end
+  end
+
+  # Controller namespace methods
+  def controller_namespace
+    resource_class_name.include?("::") ? resource_class_name.deconstantize : nil
+  end
+
+  def controller_namespace_modules
+    return [] unless controller_namespace
+
+    controller_namespace.split("::")
+  end
+
+  # Locale generation
+  def generate_locale_entries
+    model_key = model_class_name.underscore
+
+    <<~LOCALE.chomp
+      #{model_key}:
+        success:
+          index: "#{model_class_name.pluralize.humanize} retrieved successfully"
+          show: "#{model_class_name.humanize} details retrieved successfully"
+          create: "#{model_class_name.humanize} created successfully"
+          update: "#{model_class_name.humanize} updated successfully"
+        errors:
+          index: "Failed to retrieve #{model_class_name.pluralize.humanize}"
+          show: "Failed to retrieve #{model_class_name.humanize} details"
+          create: "Failed to create #{model_class_name.humanize.downcase}"
+          update: "Failed to update #{model_class_name.humanize.downcase}"
+    LOCALE
+  end
+
+  def indent_locale_block(yaml_string, spaces)
+    indent = " " * spaces
+    yaml_string.lines.map { |line| "#{indent}#{line}" }.join
+  end
+
+  # Spec helper methods
+  def spec_describe_name
+    if namespace_path.present?
+      "'#{namespace_path.camelize}::#{controller_class_name}'"
+    else
+      "'#{controller_class_name}'"
+    end
+  end
+
+  def spec_url_helper
+    if namespace_path.present?
+      "#{namespace_path.underscore.tr('/', '_')}_#{controller_name}"
+    else
+      controller_name
+    end
+  end
+end

data/lib/generators/common/templates/controller.rb.erb

@@ -0,0 +1,75 @@
+<% if controller_namespace_modules.any? -%>
+<% controller_namespace_modules.each do |mod| -%>
+module <%= mod %>
+<% end -%>
+  class <%= controller_class_name %> < ApplicationController
+    include Dscf::Core::Common
+
+    private
+
+    def model_params
+      params.require(:<%= model_class_name.underscore %>).permit(
+        # TODO: Add your permitted parameters here
+        # Example: :name, :email, :status
+      )
+    end
+
+    # Override to define associations to eager load
+    def eager_loaded_associations
+      []
+    end
+
+    # Override to define allowed columns for ordering/pagination
+    def allowed_order_columns
+      %w[id created_at updated_at]
+    end
+
+    # Override to define serializer includes for different actions
+    def default_serializer_includes
+      {
+        default: [],
+        index: [],
+        show: [],
+        create: [],
+        update: []
+      }
+    end
+  end
+<% controller_namespace_modules.each do |mod| -%>
+end
+<% end -%>
+<% else -%>
+class <%= controller_class_name %> < ApplicationController
+  include Dscf::Core::Common
+
+  private
+
+  def model_params
+    params.require(:<%= model_class_name.underscore %>).permit(
+      # TODO: Add your permitted parameters here
+      # Example: :name, :email, :status
+    )
+  end
+
+  # Override to define associations to eager load
+  def eager_loaded_associations
+    []
+  end
+
+  # Override to define allowed columns for ordering/pagination
+  def allowed_order_columns
+    %w[id created_at updated_at]
+  end
+
+  # Override to define serializer includes for different actions
+  def default_serializer_includes
+    {
+      default: [],
+      index: [],
+      show: [],
+      create: [],
+      update: []
+    }
+  end
+end
+<% end -%>