has_helpers 5.0.2

data/lib/has_helpers/factory_scenario/dsl.rb

@@ -0,0 +1,80 @@
+# typed: false
+# frozen_string_literal: true
+
+module HasHelpers
+  module FactoryScenario
+    # DSL used by `FactoryScenario.define` to declare reusable e2e setups.
+    #
+    #=== Examples
+    #   HasHelpers::FactoryScenario.define "basic/example_setup" do
+    #     # Pull in lets/helpers from an existing RSpec shared context.
+    #     include_context "some_shared_context"
+    #
+    #     # Declare lazy aliases that can be activated by run/response/request refs.
+    #     build :organization
+    #     build :policy, default: { organization: "@organization" }
+    #     build :advisor, as: :writing_advisor, traits: [:with_org]
+    #
+    #     # Expose a shared-context "let" so `@product_type` can be used in request attrs.
+    #     expose :product_type
+    #
+    #     # Optional execution hook; return hash keys are default response aliases.
+    #     run do
+    #       perform_some_action!(policy)
+    #
+    #       { policy: policy, organization: organization }
+    #     end
+    #   end
+    #
+    #   Client request (example):
+    #   {
+    #     "scenario": "basic/example_setup",
+    #     "objects": {
+    #       "organization": { "attributes": { "name": "my_org" } },
+    #       "custom_policy": {
+    #         "factory": "policy",
+    #         "attributes": { "organization": "@organization", "product_type": "@product_type" }
+    #       }
+    #     },
+    #     "response": ["organization", "policy", "custom_policy"]
+    #   }
+    class DSL
+      def initialize(definition)
+        @definition = definition
+      end
+
+      # Declare a lazy alias backed by a factory.
+      #
+      # params:
+      # - factory    <Symbol|String>            FactoryBot factory name (e.g. :policy).
+      #
+      # - as         <Symbol|String|nil>        Alias used by the scenario's reference system
+      #                                         (e.g. "custom_policy"). Defaults to `factory`.
+      #
+      # - traits     Array<Symbol|String>       Traits applied when the object is built.
+      #
+      # - default    Hash                       Default attributes merged before request overrides. Passed to factory bot.
+      #                                         Supports "@alias" references (e.g. { organization: "@organization" }).
+      #
+      # - block     <Proc|nil>                  Reserved hook for future composition/extensions.
+      def build(factory, as: nil, traits: [], default: {}, &block)
+        @definition.build(factory, as: as, traits: traits, default: default, &block)
+      end
+
+      # Attach an RSpec shared context used while evaluating run/exposed aliases.
+      def include_context(name)
+        @definition.include_contexts << name
+      end
+
+      # Expose shared-context "let"s as aliases usable in `@alias` references.
+      def expose(*aliases)
+        @definition.exposed_aliases.concat(aliases.flatten.map(&:to_sym))
+      end
+
+      # Register executable setup logic; returned hash drives default response payload.
+      def run(&block)
+        @definition.run(&block)
+      end
+    end
+  end
+end

data/lib/has_helpers/factory_scenario/factory_bot_override.rb

@@ -0,0 +1,53 @@
+# typed: false
+# frozen_string_literal: true
+
+module HasHelpers
+  module FactoryScenario
+    module FactoryBotOverride
+      THREAD_KEY = :factory_scenario_overrides
+
+      def self.with_overrides(map)
+        Thread.current[THREAD_KEY] = map
+        yield
+      ensure
+        Thread.current[THREAD_KEY] = nil
+      end
+
+      def self.for(name)
+        (Thread.current[THREAD_KEY] || {})[name.to_sym]
+      end
+
+      module SingletonPatch
+        def create(name, *traits, **attrs, &block)
+          traits, attrs = merge_override(name, traits, attrs)
+
+          super(name, *traits, **attrs, &block)
+        end
+
+        def build(name, *traits, **attrs, &block)
+          traits, attrs = merge_override(name, traits, attrs)
+
+          super(name, *traits, **attrs, &block)
+        end
+
+        def create_list(name, count, *traits, **attrs, &block)
+          traits, attrs = merge_override(name, traits, attrs)
+          super(name, count, *traits, **attrs, &block)
+        end
+
+        private
+
+        def merge_override(name, traits, attrs)
+          cfg = FactoryBotOverride.for(name)
+          return [traits, attrs] unless cfg
+
+          [cfg[:traits] + traits, cfg[:attributes].merge(attrs)]
+        end
+      end
+    end
+  end
+end
+
+unless ::FactoryBot.singleton_class.ancestors.include?(HasHelpers::FactoryScenario::FactoryBotOverride::SingletonPatch)
+  ::FactoryBot.singleton_class.prepend(HasHelpers::FactoryScenario::FactoryBotOverride::SingletonPatch)
+end

data/lib/has_helpers/factory_scenario/registry.rb

@@ -0,0 +1,31 @@
+# typed: false
+# frozen_string_literal: true
+
+module HasHelpers
+  module FactoryScenario
+    class Registry
+      def initialize
+        @definitions = {}
+      end
+
+      def register(definition)
+        @definitions[definition.name] = definition
+      end
+
+      def fetch(name)
+        load_from_disk(name) unless @definitions.key?(name)
+        @definitions[name]
+      end
+
+      private
+
+      def load_from_disk(name)
+        base = ::Rails.root || HasHelpers::Engine.root
+        path = base.join("spec", "support", "factory_scenarios", "#{name}.rb")
+        return unless path.file?
+
+        load path.to_s
+      end
+    end
+  end
+end

data/lib/has_helpers/factory_scenario/runner.rb

@@ -0,0 +1,285 @@
+# typed: false
+# frozen_string_literal: true
+
+module HasHelpers
+  module FactoryScenario
+    # Executes a scenario by composing:
+    # - scenario-defined build aliases
+    # - client-provided object overrides/new objects
+    # - lazy activation through run/response/activate references
+    class Runner
+      attr_reader :explicit_keys
+
+      Reference = Struct.new(:raw) do
+        def segments
+          raw.to_s.sub(/\A@/, "").split(".")
+        end
+
+        def alias_name
+          segments.first.to_sym
+        end
+
+        def attr_path
+          segments[1..] || []
+        end
+      end
+
+      def initialize(definition, objects_param, activate_aliases = [], response_aliases = nil)
+        @definition = definition
+        @objects_param = normalize_objects_param(objects_param)
+        @activate_aliases = Array(activate_aliases).map(&:to_sym)
+        @response_aliases = response_aliases&.map(&:to_sym)
+        @built = {}
+        @alias_registry = build_alias_registry
+        @run_context_instance = nil
+        @explicit_keys = []
+      end
+
+      def run
+        with_factorybot_overrides do
+          @run_context_instance ||= build_run_context
+          execute_run_block
+
+          @activate_aliases.each { |alias_name| resolve_alias(alias_name) }
+          response_targets.each { |alias_name| resolve_alias(alias_name) }
+          build_remaining_request_objects
+          persist_and_reload_records
+        end
+
+        @built
+      end
+
+      private
+
+      def normalize_objects_param(objects_param)
+        return objects_param.to_unsafe_h if objects_param.respond_to?(:to_unsafe_h)
+
+        objects_param || {}
+      end
+
+      def execute_run_block
+        return unless @definition.run_block
+
+        result_hash = @run_context_instance.instance_eval(&@definition.run_block)
+        return unless result_hash.is_a?(Hash)
+
+        result_hash.each { |key, value| @built[key.to_sym] ||= value }
+        @explicit_keys = result_hash.keys.map(&:to_sym)
+      end
+
+      def response_targets
+        @response_aliases || @built.keys
+      end
+
+      def build_alias_registry
+        registry = {}
+
+        all_steps.each { |step| registry[step[:as].to_sym] = { source: :step, step: step } }
+
+        @objects_param.keys.each do |key|
+          registry[key.to_sym] ||= {}
+          registry[key.to_sym].merge!(source: :request)
+        end
+
+        @definition.exposed_aliases.each do |exposed_alias|
+          registry[exposed_alias] ||= {}
+          registry[exposed_alias].merge!(source: :exposed)
+        end
+
+        registry
+      end
+
+      def resolve_alias(alias_name)
+        sym = alias_name.to_sym
+        return @built[sym] if @built.key?(sym)
+
+        entry = @alias_registry[sym]
+        return resolve_alias_from_context(sym) if entry.nil?
+
+        case entry[:source]
+        when :request then build_from_request(sym)
+        when :step then build_from_step(sym, entry[:step])
+        when :exposed then expose_from_context(sym)
+        else
+          raise "Unknown source for #{sym}"
+        end
+      end
+
+      def resolve_alias_from_context(alias_name)
+        context = @run_context_instance || build_run_context
+        raise "Unknown alias #{alias_name}" unless context.respond_to?(alias_name)
+
+        @built[alias_name] = context.public_send(alias_name)
+      end
+
+      def expose_from_context(alias_name)
+        value = @run_context_instance.respond_to?(alias_name) ? @run_context_instance.public_send(alias_name) : nil
+        @built[alias_name] = value
+      end
+
+      def build_from_step(alias_name, step)
+        cfg = object_cfg(alias_name)
+        attrs = resolve_references((step[:default] || {}).merge(cfg[:attributes]))
+        existing_id = extract_existing_id!(attrs)
+        traits = (cfg[:traits].presence || step[:traits] || []).select { |trait| trait.is_a?(Symbol) }
+
+        record =
+          if existing_id
+            ::FactoryBot.factories.find(step[:factory]).build_class.find(existing_id)
+          else
+            ::FactoryBot.create(step[:factory], *traits, **attrs)
+          end
+
+        @built[alias_name] = record
+      end
+
+      def build_from_request(alias_name)
+        cfg = object_cfg(alias_name)
+        attrs = resolve_references(cfg[:attributes].dup)
+        existing_id = extract_existing_id!(attrs)
+        factory = (cfg[:factory] || alias_name).to_sym
+        traits = cfg[:traits].select { |trait| trait.is_a?(Symbol) }
+
+        record =
+          if existing_id
+            ::FactoryBot.factories.find(factory).build_class.find(existing_id)
+          else
+            ::FactoryBot.create(factory, *traits, **attrs)
+          end
+
+        @built[alias_name] = record
+      end
+
+      def object_cfg(alias_name)
+        raw = @objects_param[alias_name.to_s] || @objects_param[alias_name] || {}
+        raw = raw.to_unsafe_h if raw.respond_to?(:to_unsafe_h)
+
+        {
+          factory: raw["factory"] || raw[:factory],
+          traits: Array(raw["traits"] || raw[:traits]).map(&:to_sym),
+          attributes: normalize_attributes(raw["attributes"] || raw[:attributes] || {})
+        }
+      end
+
+      def extract_existing_id!(attrs)
+        return nil unless attrs.is_a?(Hash)
+
+        attrs.delete(:existing_id) || attrs.delete("existing_id") ||
+          attrs.delete(:id) || attrs.delete("id")
+      end
+
+      def resolve_references(value)
+        case value
+        when String
+          return value unless value.start_with?("@")
+
+          ref = Reference.new(value)
+          target = built_or_build(ref.alias_name)
+          return target if ref.attr_path.empty?
+
+          ref.attr_path.reduce(target) { |memo, segment| memo.public_send(segment) }
+        when Array
+          value.map { |item| resolve_references(item) }
+        when Hash
+          value.to_h { |k, v| [k, resolve_references(v)] }
+        else
+          value
+        end
+      end
+
+      def built_or_build(alias_name)
+        sym = alias_name.to_sym
+        return @built[sym] if @built.key?(sym)
+
+        resolve_alias(sym)
+      end
+
+      def all_steps
+        parent_steps = HasHelpers::FactoryScenario.registry.fetch(@definition.extends_name)&.steps || []
+        @definition.steps + parent_steps
+      end
+
+      def build_remaining_request_objects
+        @objects_param.keys.map(&:to_sym).each do |alias_name|
+          next if @built.key?(alias_name)
+          next unless @alias_registry.key?(alias_name)
+
+          resolve_alias(alias_name)
+        end
+      end
+
+      # Persist values built with FactoryBot.build and refresh records to include DB-side defaults/triggers.
+      def persist_and_reload_records
+        @built.each_value do |value|
+          next unless value.respond_to?(:new_record?) && value.respond_to?(:save!)
+
+          value.save! if value.new_record?
+          value.reload if value.respond_to?(:reload)
+        end
+      end
+
+      def build_run_context
+        return RunContext.new(self) unless defined?(::RSpec) && defined?(::RSpec::Core)
+
+        definition = @definition
+        example_group = ::RSpec::Core::ExampleGroup.describe("FactoryScenario #{definition.name}") do
+          definition.include_contexts.each { |context_name| include_context context_name }
+        end
+
+        example_group.new.tap do |instance|
+          instance.instance_variable_set(:@__factory_scenario_runner, self)
+          define_alias_methods(instance)
+          define_objects_method(instance)
+        end
+      end
+
+      def define_alias_methods(instance)
+        aliases = (@objects_param.keys.map(&:to_sym) + all_steps.map { |step| step[:as].to_sym }).uniq
+        aliases.each do |alias_name|
+          runner = self
+          instance.define_singleton_method(alias_name) do
+            runner.send(:built_or_build, alias_name)
+          end
+        end
+      end
+
+      def define_objects_method(instance)
+        runner = self
+        instance.define_singleton_method(:objects) do
+          runner.instance_variable_get(:@built)
+        end
+      end
+
+      def with_factorybot_overrides
+        FactoryBotOverride.with_overrides({}) { yield }
+      end
+
+      def normalize_attributes(attrs)
+        return {} unless attrs.is_a?(Hash)
+
+        attrs = attrs.to_unsafe_h if attrs.respond_to?(:to_unsafe_h)
+        attrs = attrs.transform_keys { |key| key.is_a?(String) ? key.to_sym : key }
+
+        attrs.transform_values do |value|
+          if value.is_a?(Hash)
+            normalize_attributes(value)
+          elsif value.is_a?(Array)
+            value.map { |item| item.is_a?(Hash) ? normalize_attributes(item) : item }
+          else
+            value
+          end
+        end
+      end
+
+      class RunContext
+        def initialize(runner)
+          @runner = runner
+        end
+
+        def objects
+          @runner.instance_variable_get(:@built)
+        end
+      end
+    end
+  end
+end

data/lib/has_helpers/factory_scenario.rb

@@ -0,0 +1,27 @@
+# typed: false
+# frozen_string_literal: true
+
+require "factory_bot"
+
+require "has_helpers/factory_scenario/definition"
+require "has_helpers/factory_scenario/dsl"
+require "has_helpers/factory_scenario/factory_bot_override"
+require "has_helpers/factory_scenario/registry"
+require "has_helpers/factory_scenario/runner"
+
+module HasHelpers
+  module FactoryScenario
+    @registry = Registry.new
+
+    def self.registry
+      @registry
+    end
+
+    def self.define(name, extends: nil, &block)
+      definition = Definition.new(name, extends_name: extends)
+      DSL.new(definition).instance_eval(&block) if block
+      @registry.register(definition)
+      definition
+    end
+  end
+end

data/lib/has_helpers/fixed_expiration_time_cache_session_store.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# ActionDispatch::Session::CacheStore custom store where the expired date
+# no longer changes after creation
+class HasHelpers::FixedExpirationTimeCacheSessionStore < ActionDispatch::Session::CacheStore
+  def write_session(env, sid, session_data, options)
+    # Only write the session to the store if it's a new session
+    unless session_already_exists?(sid)
+      super(env, sid, session_data, options)
+    end
+
+    sid
+  end
+
+  private
+
+  def session_already_exists?(sid)
+    @cache.read(cache_key(sid.private_id)) || @cache.read(cache_key(sid.public_id))
+  end
+end

data/lib/has_helpers/flattener/association.rb

@@ -0,0 +1,140 @@
+# typed: true
+# frozen_string_literal: true
+
+module Flattener
+  class Association
+    include ActiveModel::Model
+    HAS_MANY_COUNT = 2
+
+    attr_accessor :ar_association, :expand_on, :expand_on_nil, :join, :join_resource
+    attr_writer :always_include, :count, :for, :merge, :merge_into_parent, :flattener,
+                :expand_on_column, :reject_if, :alias_name, :removed,
+                :is_nested_attributes, :foreign_key, :pivot_foreign_key
+
+    delegate :klass, :macro, to: :ar_association
+
+    def initialize(ar_association, **args)
+      super(ar_association: ar_association, **args)
+    end
+
+    def update(args)
+      args.each do |k, v|
+        send("#{k}=", v)
+      end
+    end
+
+    def remove
+      self.for = []
+      self.always_include = false
+      self.removed = true
+    end
+
+    def name
+      @name ||= alias_name || ar_association.name
+    end
+
+    def alias_name
+      @alias_name ||= self.class.aliases[ar_association_name]
+    end
+
+    delegate :name, to: :ar_association, prefix: true
+
+    def count
+      @count ||= macro == :has_many ? HAS_MANY_COUNT : 0
+    end
+
+    def foreign_key
+      @foreign_key ||= begin
+                         columns = (type == :has_many ? flattener.columns : parent_flattener.columns)
+                         (columns.detect { |column| column.name.to_s == ar_association.foreign_key.to_s }.try(:alias_name) ||
+                           ar_association.foreign_key).to_s
+                       end
+    end
+
+    # Returns the foreign key on the base table, referencing the pivot table.
+    # In contrast, when an association is used as a pivot the foreign_key will
+    # be the column on the pivot table which references back to the base table.
+    # The pivot FK does not exist in the transactional database and must therefore
+    # be determined using the available klass name.
+    #
+    # The default behavior may be overridden by setting an explicit value.
+    #
+    #   association.pivot_foreign_key = :firm_id
+    def pivot_foreign_key
+      @pivot_foreign_key || klass.name.foreign_key
+    end
+
+    def merge_into_parent
+      @merge_into_parent = macro == :has_one if @merge_into_parent.nil?
+      @merge_into_parent
+    end
+
+    def always_include
+      @always_include = (type == :constant && !ar_association.active_record.include?(HasHelpers::Constant)) if @always_include.nil? # always include if a constant, and parents not a constant
+      @always_include
+    end
+
+    def removed
+      @removed ||= false
+    end
+
+    def reject_if
+      @reject_if ||= proc { |_r| false }
+    end
+
+    def type
+      return :constant if is_constant?
+      return :nested_attributes if is_nested_attributes?
+      macro
+    end
+
+    def expand_on_column
+      @expand_on_column ||= @expand_on && "type"
+    end
+
+    def flattener
+      @flattener ||= Flattener.for(klass).pivot_or_self.new
+    end
+
+    def parent_flattener
+      @parent_flattener ||= Flattener.for(ar_association.active_record).new
+    end
+
+    # FIXME: Refactor to avoid conflicting with the Ruby keyword "for" *
+    def for
+      @for ||= Flattener.default_for(type)
+    end
+
+    def is_constant?
+      klass.include?(HasHelpers::Constant) && macro == :belongs_to
+    end
+
+    def is_nested_attributes?
+      if @is_nested_attributes.nil?
+        ar_association.active_record.nested_attributes_options.key?(ar_association.name)
+      else
+        @is_nested_attributes
+      end
+    end
+
+    def is_pivot?
+      flattener.class.is_pivot?
+    end
+
+    def ==(other)
+      self.ar_association == other.ar_association
+    end
+
+    class << self
+      attr_writer :aliases
+
+      def aliases
+        @aliases ||= {}
+      end
+    end
+
+    def self.alias(name, alias_name)
+      aliases[name] = alias_name
+    end
+  end
+end

data/lib/has_helpers/flattener/attribute.rb

@@ -0,0 +1,42 @@
+# typed: true
+# frozen_string_literal: true
+
+module Flattener
+  class Attribute
+    include ActiveModel::Model
+    include Flattener::Utils
+
+    attr_accessor :resource, :column
+    delegate :is_primary_key?, to: :column
+
+    def name
+      combine_names(resource.name, column.alias_name || column_name)
+    end
+
+    def column_name
+      column_name = column.name.dup unless column.name == "name" && (column.klass.include?(HasHelpers::Constant) || resource.parent.present?)
+      column_name
+    end
+
+    # TODO: not finished
+    def key
+      "#{resource.prefix}[#{column.name}]"
+    end
+
+    def editable?
+      [is_primary_key?, resource.is_constant?].uniq == [false]
+    end
+
+    def to_h
+      { name: name, key: key, type: column.sql_type, percent: column.is_percent?, currency: column.is_currency?, editable: editable? }
+    end
+
+    def column_association
+      @column_association ||= column.association
+    end
+
+    def column_association_name
+      column_association && combine_names(resource.name, column_association.name)
+    end
+  end
+end