develoz-rails 0.1.0

data/lib/generators/develoz/concerns/templates/spec/models/concerns/configurable_spec.rb.tt

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+describe Configurable do
+  # This spec tests the Configurable concern.
+  # It creates a test model with a polymorphic configuration association.
+  before(:all) do
+    ActiveRecord::Schema.define do
+      create_table :configurable_records, force: true do |t|
+        t.string :name
+      end
+    end
+  end
+
+  after(:all) do
+    ActiveRecord::Schema.define { drop_table :configurable_records, if_exists: true }
+  end
+
+  let(:test_class) do
+    stub_const("ConfigurableRecord", Class.new(ApplicationRecord) do
+      self.table_name = "configurable_records"
+      include Configurable
+      configurable :highest_format_only, :boolean
+      configurable :report_groups, :array
+      configurable :feature_flags, :hash, global_fallback: true
+      configurable :page_size, default: 25
+    end)
+  end
+
+  let(:record) { test_class.create!(name: "test") }
+
+  before(:each) do
+    Configuration.destroy_all
+  end
+
+  describe ".configurable with a boolean attribute" do
+    it "casts an assigned value and exposes it through the predicate" do
+      record.highest_format_only = "true"
+
+      expect(record.highest_format_only?).to be(true)
+    end
+
+    it "reads the predicate from its own configuration key" do
+      record.update_configuration(:highest_format_only, true)
+
+      expect(record.highest_format_only?).to be(true)
+    end
+
+    it "persists the assigned value to its own configuration key on save" do
+      record.update!(highest_format_only: "true")
+
+      expect(record.configuration_value(:highest_format_only)).to be(true)
+    end
+
+    it "leaves the configuration untouched when nothing was assigned" do
+      record.update_configuration(:highest_format_only, true)
+
+      expect { record.update!(name: "changed") }.not_to(change do
+        record.configuration_value(:highest_format_only)
+      end)
+    end
+  end
+
+  describe ".configurable with a value attribute" do
+    it "reads the scoped value for the key" do
+      record.update_configuration(:report_groups, %w[APAC EMEA])
+
+      expect(record.report_groups).to eq(%w[APAC EMEA])
+    end
+
+    it "returns the default when no configuration exists" do
+      expect(record.report_groups).to eq([])
+    end
+
+    it "persists an assigned value to its own key on save" do
+      record.update!(report_groups: %w[APAC])
+
+      expect(record.configuration_value(:report_groups)).to eq(%w[APAC])
+    end
+
+    it "deletes the scoped record when assigned nil" do
+      record.update_configuration(:report_groups, %w[APAC])
+
+      expect { record.update!(report_groups: nil) }
+        .to change { record.configuration_for(:report_groups) }.to(nil)
+    end
+
+    it "returns the default while a nil assignment is pending" do
+      record.report_groups = nil
+
+      expect(record.report_groups).to eq([])
+    end
+
+    it "uses an explicit default" do
+      expect(record.page_size).to eq(25)
+    end
+  end
+
+  describe ".configurable with global_fallback" do
+    it "merges the global value under the scoped one" do
+      Configuration.create!(key: "feature_flags", value: { "a" => true, "b" => true })
+      record.update_configuration(:feature_flags, { "b" => false })
+
+      expect(record.feature_flags).to eq("a" => true, "b" => false)
+    end
+
+    it "falls back to the global value when no scoped override exists" do
+      Configuration.create!(key: "feature_flags", value: { "a" => true })
+
+      expect(record.feature_flags).to eq("a" => true)
+    end
+  end
+
+  describe "#configuration_for" do
+    it "returns the active scoped configuration for the key" do
+      config = record.update_configuration("demo", { "enabled" => true })
+
+      expect(record.configuration_for("demo")).to eq(config)
+    end
+
+    it "ignores inactive configurations" do
+      Configuration.create!(key: "demo", configurable_type: "ConfigurableRecord",
+                            configurable_id: record.id, value: { "enabled" => true }, active: false)
+
+      expect(record.configuration_for("demo")).to be_nil
+    end
+
+    it "ignores configurations scoped to a different record" do
+      other = test_class.create!(name: "other")
+      other.update_configuration("demo", { "enabled" => true })
+
+      expect(record.configuration_for("demo")).to be_nil
+    end
+  end
+
+  describe "#configuration_value" do
+    it "returns the stored value" do
+      record.update_configuration("demo", { "count" => 3 })
+
+      expect(record.configuration_value("demo")).to eq("count" => 3)
+    end
+
+    it "returns the default when no configuration exists" do
+      expect(record.configuration_value("demo", default: "fallback")).to eq("fallback")
+    end
+  end
+
+  describe "#update_configuration" do
+    it "creates a configuration when none exists" do
+      expect { record.update_configuration("demo", { "enabled" => true }) }
+        .to change(Configuration, :count).by(1)
+    end
+
+    it "updates the existing configuration in place" do
+      record.update_configuration("demo", { "enabled" => false })
+
+      expect { record.update_configuration("demo", { "enabled" => true }) }
+        .not_to change(Configuration, :count)
+      expect(record.configuration_value("demo")).to eq("enabled" => true)
+    end
+  end
+
+  describe "#delete_configuration" do
+    it "removes the scoped configuration" do
+      record.update_configuration("demo", { "enabled" => true })
+
+      expect { record.delete_configuration("demo") }.to change(Configuration, :count).by(-1)
+      expect(record.configuration_for("demo")).to be_nil
+    end
+  end
+end

data/lib/generators/develoz/concerns/templates/spec/models/concerns/optimized_finders_spec.rb.tt

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+describe OptimizedFinders do
+  # This spec tests the OptimizedFinders module.
+  # It creates a parent/child relationship to exercise both class-level and
+  # association-level finders.
+  before(:all) do
+    ActiveRecord::Schema.define do
+      create_table :parents, force: true do |t|
+        t.string :name
+      end
+
+      create_table :children, force: true do |t|
+        t.references :parent, foreign_key: true
+        t.string :license
+        t.string :variant
+      end
+    end
+  end
+
+  after(:all) do
+    ActiveRecord::Schema.define do
+      drop_table :children, if_exists: true
+      drop_table :parents, if_exists: true
+    end
+  end
+
+  let(:parent_class) do
+    stub_const("Parent", Class.new(ApplicationRecord) do
+      self.table_name = "parents"
+      has_many :children, class_name: "Child", foreign_key: :parent_id
+    end)
+  end
+
+  let(:child_class) do
+    stub_const("Child", Class.new(ApplicationRecord) do
+      self.table_name = "children"
+      belongs_to :parent, class_name: "Parent", optional: true
+
+      def format
+        variant&.upcase
+      end
+    end)
+  end
+
+  let(:parent) { parent_class.create!(name: "parent") }
+
+  before do
+    parent_class
+    child_class
+  end
+
+  describe ".find_for" do
+    it "finds a record by single attribute" do
+      record = child_class.create!(license: "buy", variant: "hd")
+
+      expect(child_class.find_for(license: "buy")).to eq(record)
+    end
+
+    it "finds a record by multiple attributes" do
+      record = child_class.create!(license: "buy", variant: "hd")
+      child_class.create!(license: "rent", variant: "hd")
+
+      expect(child_class.find_for(license: "buy", variant: "hd")).to eq(record)
+    end
+
+    it "returns nil when no match is found" do
+      child_class.create!(license: "buy", variant: "hd")
+
+      expect(child_class.find_for(license: "rent", variant: "sd")).to be_nil
+    end
+  end
+
+  describe ".for" do
+    it "finds records by single attribute" do
+      r1 = child_class.create!(license: "buy", variant: "hd")
+      r2 = child_class.create!(license: "buy", variant: "sd")
+      child_class.create!(license: "rent", variant: "hd")
+
+      results = child_class.for(license: "buy")
+
+      expect(results).to contain_exactly(r1, r2)
+    end
+
+    it "returns empty array when no match is found" do
+      child_class.create!(license: "buy", variant: "hd")
+
+      expect(child_class.for(license: "rent", variant: "sd")).to be_empty
+    end
+  end
+
+  describe ".not_for" do
+    it "finds records NOT matching the given attributes" do
+      child_class.create!(license: "buy", variant: "hd")
+      rent = child_class.create!(license: "rent", variant: "hd")
+
+      results = child_class.not_for(license: "buy")
+
+      expect(results).to contain_exactly(rent)
+    end
+  end
+
+  describe ".gather" do
+    it "plucks values across all records" do
+      child_class.create!(license: "buy", variant: "hd")
+      child_class.create!(license: "rent", variant: "sd")
+
+      expect(child_class.gather(:license)).to contain_exactly("buy", "rent")
+    end
+
+    it "returns tuples for multiple columns" do
+      child_class.create!(license: "buy", variant: "hd")
+      child_class.create!(license: "rent", variant: "sd")
+
+      expect(child_class.gather(:license, :variant)).to contain_exactly(%w[buy hd], %w[rent sd])
+    end
+  end
+
+  describe "association-level optimization" do
+    it "uses in-memory search without SQL when association is loaded" do
+      record = child_class.create!(parent:, license: "buy", variant: "hd")
+      child_class.create!(parent:, license: "rent", variant: "hd")
+
+      parent.children.load
+
+      query_count = 0
+      counter = ->(*, **) { query_count += 1 }
+      ActiveSupport::Notifications.subscribed(counter, "sql.active_record") do
+        found = parent.children.find_for(license: "buy", variant: "hd")
+        expect(found).to eq(record)
+      end
+      expect(query_count).to eq(0)
+    end
+
+    it "uses database query when association is not loaded" do
+      record = child_class.create!(parent:, license: "buy", variant: "hd")
+
+      found = parent.children.find_for(license: "buy", variant: "hd")
+      expect(found).to eq(record)
+    end
+
+    it "uses in-memory search for non-database attributes" do
+      record = child_class.create!(parent:, license: "buy", variant: "hd")
+
+      expect(child_class.column_names).not_to include("format")
+
+      found = parent.children.find_for(format: "HD")
+      expect(found).to eq(record)
+    end
+
+    it "filters loaded associations in memory, including array values" do
+      buy = child_class.create!(parent:, license: "buy", variant: "hd")
+      rent = child_class.create!(parent:, license: "rent", variant: "sd")
+      child_class.create!(parent:, license: "trial", variant: "hd")
+      parent.children.load
+
+      expect(parent.children.for(license: %w[buy rent])).to contain_exactly(buy, rent)
+    end
+
+    it "filters unloaded associations in the database" do
+      buy = child_class.create!(parent:, license: "buy", variant: "hd")
+      child_class.create!(parent:, license: "rent", variant: "sd")
+
+      expect(parent.children.for(license: "buy")).to contain_exactly(buy)
+    end
+
+    it "rejects matching records from loaded associations in memory" do
+      child_class.create!(parent:, license: "buy", variant: "hd")
+      rent = child_class.create!(parent:, license: "rent", variant: "sd")
+      parent.children.load
+
+      expect(parent.children.not_for(license: "buy")).to contain_exactly(rent)
+    end
+
+    it "rejects matching records from unloaded associations in the database" do
+      child_class.create!(parent:, license: "buy", variant: "hd")
+      rent = child_class.create!(parent:, license: "rent", variant: "sd")
+
+      expect(parent.children.not_for(license: "buy")).to contain_exactly(rent)
+    end
+
+    it "gathers one or multiple attributes from a loaded association" do
+      child_class.create!(parent:, license: "buy", variant: "hd")
+      child_class.create!(parent:, license: "rent", variant: "sd")
+      parent.children.load
+
+      expect(parent.children.gather(:license)).to contain_exactly("buy", "rent")
+      expect(parent.children.gather(:license, :variant)).to contain_exactly(%w[buy hd], %w[rent sd])
+    end
+
+    it "gathers attributes from an unloaded association in the database" do
+      child_class.create!(parent:, license: "buy", variant: "hd")
+      child_class.create!(parent:, license: "rent", variant: "sd")
+
+      expect(parent.children.gather(:license)).to contain_exactly("buy", "rent")
+    end
+  end
+end

data/lib/generators/develoz/concerns/templates/spec/models/concerns/searchable_concern_spec.rb.tt

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+describe SearchableConcern do
+  # This spec tests the SearchableConcern module.
+  # Replace `SearchableModel` with a real model in your app that calls `searchable_by`.
+  before(:all) do
+    ActiveRecord::Schema.define do
+      create_table :searchable_models, force: true do |t|
+        t.string :name
+        t.string :description
+      end
+    end
+  end
+
+  after(:all) do
+    ActiveRecord::Schema.define { drop_table :searchable_models, if_exists: true }
+  end
+
+  let(:model_class) do
+    stub_const("SearchableModel", Class.new(ApplicationRecord) do
+      self.table_name = "searchable_models"
+      include SearchableConcern
+      searchable_by :name, :description
+    end)
+  end
+
+  describe ".searchable_by" do
+    it "adds search_by_text scope to model" do
+      expect(model_class).to respond_to(:search_by_text)
+    end
+
+    it "returns records matching search text on configured columns" do
+      match = model_class.create!(name: "The Matrix")
+      no_match = model_class.create!(name: "Inception")
+
+      results = model_class.search_by_text("matrix")
+
+      expect(results).to include(match)
+      expect(results).not_to include(no_match)
+    end
+
+    it "supports prefix matching" do
+      record = model_class.create!(name: "Interstellar")
+
+      results = model_class.search_by_text("inter")
+
+      expect(results).to include(record)
+    end
+
+    it "is idempotent when called multiple times on the same class" do
+      expect { model_class.searchable_by(:name) }.not_to raise_error
+      expect(model_class.ancestors.count(PgSearch::Model)).to eq(1)
+    end
+
+    it "returns empty when no matches found" do
+      model_class.create!(name: "The Matrix")
+
+      results = model_class.search_by_text("xyz123nonexistent")
+
+      expect(results).to be_empty
+    end
+  end
+
+  describe ".search" do
+    it "delegates to search_by_text when query is present" do
+      match = model_class.create!(name: "The Matrix")
+      model_class.create!(name: "Inception")
+
+      results = model_class.search("matrix")
+
+      expect(results).to include(match)
+    end
+
+    it "returns all records when query is blank" do
+      match1 = model_class.create!(name: "The Matrix")
+      match2 = model_class.create!(name: "Inception")
+
+      expect(model_class.search("")).to include(match1, match2)
+      expect(model_class.search(nil)).to include(match1, match2)
+    end
+  end
+end

data/lib/generators/develoz/concerns/templates/spec/models/concerns/transitionable_spec.rb.tt

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+describe Transitionable do
+  # This spec tests the Transitionable concern.
+  # It creates a test table with status + status_transitions columns.
+  before(:all) do
+    ActiveRecord::Schema.define do
+      create_table :transitionable_records, force: true do |t|
+        t.string :status, default: "pending", null: false
+        t.jsonb :status_transitions, default: [], null: false
+        t.timestamps
+      end
+    end
+  end
+
+  after(:all) do
+    ActiveRecord::Schema.define { drop_table :transitionable_records, if_exists: true }
+  end
+
+  let(:test_class) do
+    stub_const("TransitionableRecord", Class.new(ApplicationRecord) do
+      self.table_name = "transitionable_records"
+      extend Transitionable
+    end)
+  end
+
+  describe ".states with kwargs transitions map" do
+    before { test_class.states(pending: %i[paid], paid: []) }
+
+    it "declares an enum keyed by the declared states" do
+      expect(test_class.statuses.keys).to eq(%w[pending paid])
+    end
+
+    it "exposes the transition map" do
+      expect(test_class.transitions).to eq(pending: %i[paid].freeze, paid: [].freeze)
+    end
+  end
+
+  describe ".states with positional transitions hash" do
+    it "parses the hash and exposes the transitions" do
+      test_class.states({ draft: %i[review], review: %i[draft published] })
+
+      expect(test_class.statuses.keys).to eq(%w[draft review])
+      expect(test_class.transitions[:review]).to eq(%i[draft published].freeze)
+    end
+  end
+
+  describe ".states with positional array of states" do
+    it "declares free-mode states (transitions is nil)" do
+      test_class.states(%i[draft review published])
+
+      expect(test_class.statuses.keys).to eq(%w[draft review published])
+      expect(test_class.transitions).to be_nil
+    end
+  end
+
+  describe ".states with splat positional symbols" do
+    it "declares free-mode states (transitions is nil)" do
+      test_class.states(:a, :b, :c)
+
+      expect(test_class.statuses.keys).to eq(%w[a b c])
+      expect(test_class.transitions).to be_nil
+    end
+  end
+
+  describe ".states validation" do
+    it "raises when given both kwargs and positional args" do
+      expect { test_class.states(:a, pending: %i[paid]) }
+        .to raise_error(ArgumentError, /transitions hash or a list of states/)
+    end
+
+    it "raises when given no states" do
+      expect { test_class.states }
+        .to raise_error(ArgumentError, /at least one state/)
+    end
+  end
+
+  describe "integration with strict transitions" do
+    before { test_class.states(pending: %i[paid], paid: %i[cancelled], cancelled: []) }
+
+    it "uses the first declared state as default" do
+      expect(test_class.create!.status).to eq("pending")
+    end
+
+    it "records the initial status as the first transition on create" do
+      record = test_class.create!
+
+      expect(record.status_transitions.length).to eq(1)
+      expect(record.status_transitions.first).to include("to_state" => "pending")
+    end
+
+    it "does not record an initial transition when status_transitions is pre-populated" do
+      record = test_class.create!(
+        status_transitions: [ { "to_state" => "pending", "created_at" => "2024-01-01T00:00:00.000000Z" } ]
+      )
+
+      expect(record.status_transitions.length).to eq(1)
+    end
+
+    it "transitions and appends to status_transitions" do
+      record = test_class.create!
+
+      expect { record.paid_status! }
+        .to change(record, :status).from("pending").to("paid")
+        .and(change { record.status_transitions.length }.by(1))
+
+      expect(record.status_transitions.last["to_state"]).to eq("paid")
+    end
+
+    it "is a no-op when already in the target state" do
+      record = test_class.create!
+      transitions_before = record.status_transitions
+
+      record.pending_status!
+
+      expect(record.status_transitions).to eq(transitions_before)
+    end
+
+    it "records metadata when transition_metadata is set" do
+      record = test_class.create!(status: "paid")
+
+      record.update!(status: "cancelled", transition_metadata: { reason: "customer_request" })
+
+      expect(record.status_transitions.last).to include(
+        "to_state" => "cancelled",
+        "metadata" => { "reason" => "customer_request" }
+      )
+    end
+
+    it "raises ActiveRecord::RecordInvalid on a disallowed transition" do
+      record = test_class.create!
+
+      expect { record.cancelled_status! }.to raise_error(
+        ActiveRecord::RecordInvalid,
+        /Status cannot transition from "pending" to "cancelled"/
+      )
+    end
+  end
+
+  describe "#can_be_<state>?" do
+    before { test_class.states(pending: %i[paid], paid: []) }
+
+    it "returns true for an allowed transition" do
+      record = test_class.create!
+      expect(record.can_be_paid?).to be true
+    end
+
+    it "returns false for a disallowed transition" do
+      record = test_class.create!(status: "paid")
+      expect(record.can_be_pending?).to be false
+    end
+
+    it "returns false when the current state is nil" do
+      record = test_class.new(status: nil)
+      record.clear_changes_information
+
+      expect(record.can_be_paid?).to be false
+    end
+
+    context "when in free mode (transitions is nil)" do
+      before do
+        test_class.states(%i[draft published])
+        allow(test_class).to receive(:transitions).and_return(nil)
+      end
+
+      it "allows any declared state" do
+        record = test_class.create!
+        expect(record.can_be_published?).to be true
+      end
+    end
+  end
+
+  describe "#last_transition" do
+    before { test_class.states(pending: %i[paid], paid: []) }
+
+    it "returns nil when status_transitions is empty" do
+      record = test_class.create!
+      record.update_column(:status_transitions, [])
+
+      expect(record.last_transition).to be_nil
+    end
+
+    it "returns the latest entry as a Struct" do
+      record = test_class.create!(status: "paid")
+
+      transition = record.last_transition
+
+      expect(transition.to_state).to eq("paid")
+      expect(transition.metadata).to eq({})
+      expect(transition.created_at).to be_present
+    end
+  end
+
+  describe "#status_times" do
+    before { test_class.states(pending: %i[paid], paid: []) }
+
+    it "calculates the time spent between transitions" do
+      created_at = Time.zone.parse("2024-01-01T00:00:00Z")
+      pending_at = created_at + 1.minute
+      paid_at = pending_at + 2.minutes
+      record = test_class.create!(
+        created_at:,
+        status: "paid",
+        status_transitions: [
+          { "to_state" => "pending", "created_at" => pending_at.iso8601(6) },
+          { "to_state" => "paid", "created_at" => paid_at.iso8601(6) }
+        ]
+      )
+
+      expect(record.status_times).to eq(
+        [
+          { status: "pending", previous_time: created_at, time: pending_at, duration: 1.minute },
+          { status: "paid", previous_time: pending_at, time: paid_at, duration: 2.minutes }
+        ]
+      )
+    end
+  end
+
+  describe ".in_state" do
+    before { test_class.states(pending: %i[paid], paid: []) }
+
+    it "filters records by status" do
+      pending_record = test_class.create!
+      paid_record = test_class.create!(status: "paid")
+
+      in_pending = test_class.in_state(:pending)
+      expect(in_pending).to include(pending_record)
+      expect(in_pending).not_to include(paid_record)
+      expect(test_class.in_state(:pending, :paid)).to include(pending_record, paid_record)
+    end
+  end
+end