purizumu 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d408af4fde18f4121def0d7c973ded6e80fee0893a1fd2c9cfdfe46b1595dae
-  data.tar.gz: ca1fdc72ff34d5247d2507547ff6e012b41f4779da1a80131cfbc05acd91fb5e
+  metadata.gz: 72573b19670b458b24a5da4260623d80470ddfc2948e197fc521264aa4825bc4
+  data.tar.gz: 2a06be3b4baea735405a4b37a6f22765507504cb1d049703420424249422852b
 SHA512:
-  metadata.gz: 35e08731206e156bd2a9bf63cdf6329b87d715ceb4d5d1844c85995186f2bcfdbbbefebfc7aee15549e4e3b1af2c992359d6058baf6e8d3aeef37f1cbc427439
-  data.tar.gz: 64cecd53d1431269285e3d3908687522880cdfd3b4e17495da5debbd05269d35e1783794d723990e7387d03e98ea84f00d09fabfebbeee9e5a8a6d6b4bcbc794
+  metadata.gz: e2a338946fd43b0e867f29eb6863cda8b4732a3659dff4b698577735d0bf52b367517ce56f62523dd8106134def31634134c32bc5cf6c786c05b84aaab67175e
+  data.tar.gz: b10400ba178ce055773d6c602039ff09be5ff85821645b5e1aa320dde7d473c79fb5a7b81bf0067f4508fc77b3d6b811743cd0b11f1793865cbdcb55d5690d21

data/README.md

@@ -43,7 +43,7 @@ end
 
 Available configuration options:
 
-- `config.engine`: translation engine symbol. Purizumu currently ships with `:xai`.
+- `config.engine`: translation engine symbol. Purizumu currently ships with `:xai` and `:test` (see [Test Mode](#test-mode)).
 - `config.key`: API key for the configured engine.
 - `config.model`: LLM model name.
 - `config.base_url`: API base URL. Defaults to `https://api.x.ai/v1`.
@@ -130,6 +130,65 @@ The expected tool payload is:
 }
 ```
 
+## Test Mode
+
+In a test suite you usually do not want translated attribute reads to hit the configured translation engine's API. Enable test mode and Purizumu will stub translations locally without any network requests:
+
+```ruby
+Purizumu.test_mode!
+```
+
+While test mode is on, `Purizumu.engine` returns a stub engine regardless of the configured engine, and no API key or model is required. By default, the stub returns `"[<locale>] <original content>"`, so `"Prism"` translated to `:jp` becomes `"[jp] Prism"` — deterministic and easy to assert against.
+
+You can also supply a block to control what the stub returns. The block receives the full translation request as keyword arguments (`model_name`, `attribute_name`, `content`, `locale`, `source_locale`):
+
+```ruby
+Purizumu.test_mode! do |content:, locale:, **|
+  "#{content} (#{locale})"
+end
+```
+
+To turn it back off (and clear any custom block):
+
+```ruby
+Purizumu.disable_test_mode!
+```
+
+You can check the current state with `Purizumu.test_mode?`.
+
+### RSpec
+
+Enable it once for the entire run in `spec/spec_helper.rb` (or `rails_helper.rb`):
+
+```ruby
+RSpec.configure do |config|
+  config.before(:suite) do
+    Purizumu.test_mode!
+  end
+end
+```
+
+Or, if you only want it for specific examples, enable it per test:
+
+```ruby
+before { Purizumu.test_mode! }
+after { Purizumu.disable_test_mode! }
+```
+
+Test mode is independent of configuration, so it survives `Purizumu.reset_configuration!` — enabling it in `before(:suite)` keeps it on even if individual tests reset or rebuild the configuration.
+
+### Configuring the Test Engine Directly
+
+If you prefer plain configuration — for example in a Rails `config/environments/test.rb` setup where nothing resets Purizumu's configuration — the stub engine is also available as a regular engine:
+
+```ruby
+Purizumu.configure do |config|
+  config.engine = :test
+end
+```
+
+This behaves like test mode with no block: no network requests, no API key or model required, and the same `"[<locale>] <original content>"` stub output. The difference is that it lives in the configuration, so `Purizumu.reset_configuration!` or a later `Purizumu.configure` will replace it. `Purizumu.test_mode!` still overrides whatever engine is configured.
+
 ## Generator Output
 
 `rails generate purizumu:install` creates a migration for the translation table with:

data/lib/purizumu/engines/test.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Purizumu
+  module Engines
+    # Translation engine used in test mode. It never performs network
+    # requests; it returns a deterministic stub translation, or the result
+    # of the handler given to Purizumu.test_mode!.
+    class Test
+      def initialize(handler: nil)
+        @handler = handler
+      end
+
+      def translate(model_name:, attribute_name:, content:, locale:, source_locale:)
+        if handler
+          handler.call(
+            model_name:,
+            attribute_name:,
+            content:,
+            locale:,
+            source_locale:
+          ).to_s
+        else
+          "[#{locale}] #{content}"
+        end
+      end
+
+      private
+
+      attr_reader :handler
+    end
+  end
+end

data/lib/purizumu/translator.rb

@@ -11,6 +11,7 @@ module Purizumu
 
     def call
       return source_content if source_content.nil? || source_content == ''
+      return source_content unless record.persisted?
 
       existing_translation&.content || create_translation!.content
     end

data/lib/purizumu/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Purizumu
-  VERSION = '0.1.1'
+  VERSION = '0.2.0'
 end

data/lib/purizumu.rb

@@ -9,6 +9,7 @@ require 'uri'
 require 'purizumu/version'
 require 'purizumu/errors'
 require 'purizumu/configuration'
+require 'purizumu/engines/test'
 require 'purizumu/engines/xai'
 require 'purizumu/engines/xai/payload_builder'
 require 'purizumu/engines/xai/response_parser'
@@ -32,16 +33,34 @@ module Purizumu
       @configuration = Configuration.new
     end
 
+    def test_mode!(&handler)
+      @test_mode = true
+      @test_handler = handler
+    end
+
+    def test_mode?
+      @test_mode == true
+    end
+
+    def disable_test_mode!
+      @test_mode = false
+      @test_handler = nil
+    end
+
     def translate_attribute(record, attribute_name, locale: I18n.locale)
       Translator.new(record: record, attribute_name: attribute_name, locale: locale).call
     end
 
     def engine
+      return Engines::Test.new(handler: @test_handler) if test_mode?
+
       engine_name = configuration.engine.to_sym
 
       case engine_name
       when :xai
         Engines::Xai.new(configuration: configuration)
+      when :test
+        Engines::Test.new
       else
         raise UnsupportedEngineError, "Unsupported translation engine: #{engine_name}"
       end

data/spec/purizumu/test_mode_spec.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Purizumu, '.test_mode!' do
+  after do
+    described_class.disable_test_mode!
+  end
+
+  it 'is disabled by default' do
+    expect(described_class.test_mode?).to be(false)
+  end
+
+  it 'enables test mode' do
+    described_class.test_mode!
+
+    expect(described_class.test_mode?).to be(true)
+  end
+
+  it 'returns the test engine while enabled' do
+    described_class.test_mode!
+
+    expect(described_class.engine).to be_a(Purizumu::Engines::Test)
+  end
+
+  it 'does not require engine configuration while enabled' do
+    described_class.test_mode!
+
+    expect(described_class.engine.translate(**translate_arguments)).to be_a(String)
+  end
+
+  it 'survives configuration resets' do
+    described_class.test_mode!
+    described_class.reset_configuration!
+
+    expect(described_class.test_mode?).to be(true)
+  end
+
+  it 'returns a deterministic stub translation by default' do
+    described_class.test_mode!
+
+    expect(described_class.engine.translate(**translate_arguments)).to eq('[jp] Prism')
+  end
+
+  it 'uses the handler result when a block is given' do
+    described_class.test_mode! { |locale:, content:, **| "#{content} in #{locale}" }
+
+    expect(described_class.engine.translate(**translate_arguments)).to eq('Prism in jp')
+  end
+
+  it 'passes the full request to the handler' do
+    seen = nil
+    described_class.test_mode! { |**request| seen = request }
+    described_class.engine.translate(**translate_arguments)
+
+    expect(seen).to eq(translate_arguments)
+  end
+
+  it 'coerces handler results to strings' do
+    described_class.test_mode! { |**| :symbolic }
+
+    expect(described_class.engine.translate(**translate_arguments)).to eq('symbolic')
+  end
+
+  it 'clears a previous handler when re-enabled without a block' do
+    described_class.test_mode! { |**| 'from handler' }
+    described_class.test_mode!
+
+    expect(described_class.engine.translate(**translate_arguments)).to eq('[jp] Prism')
+  end
+
+  describe '.disable_test_mode!' do
+    before do
+      described_class.test_mode! { |**| 'from handler' }
+      described_class.disable_test_mode!
+    end
+
+    it 'disables test mode' do
+      expect(described_class.test_mode?).to be(false)
+    end
+
+    it 'restores the configured engine' do
+      expect(described_class.engine).to be_a(Purizumu::Engines::Xai)
+    end
+
+    it 'clears the handler for later re-enables' do
+      described_class.test_mode!
+
+      expect(described_class.engine.translate(**translate_arguments)).to eq('[jp] Prism')
+    end
+  end
+
+  describe 'configuring the test engine directly' do
+    before do
+      described_class.configure { |config| config.engine = :test }
+    end
+
+    it 'returns the test engine' do
+      expect(described_class.engine).to be_a(Purizumu::Engines::Test)
+    end
+
+    it 'returns the default stub translation' do
+      expect(described_class.engine.translate(**translate_arguments)).to eq('[jp] Prism')
+    end
+
+    it 'is overridden by a test mode handler' do
+      described_class.test_mode! { |**| 'from handler' }
+
+      expect(described_class.engine.translate(**translate_arguments)).to eq('from handler')
+    end
+  end
+
+  describe 'translating model attributes in test mode' do
+    subject(:translated_name) { record.human_name }
+
+    before do
+      stub_const('GemRecord', Class.new(ActiveRecord::Base) do
+        self.table_name = 'gems'
+
+        attribute_translation :human_name
+      end)
+
+      described_class.test_mode!
+      I18n.locale = :jp
+    end
+
+    let!(:record) { GemRecord.create!(human_name: 'Prism') }
+
+    it 'returns the stubbed translation' do
+      expect(translated_name).to eq('[jp] Prism')
+    end
+
+    it 'persists the stubbed translation' do
+      translated_name
+
+      expect(persisted_translation.content).to eq('[jp] Prism')
+    end
+
+    it 'never opens an HTTP connection' do
+      allow(Net::HTTP).to receive(:new)
+      translated_name
+
+      expect(Net::HTTP).not_to have_received(:new)
+    end
+  end
+
+  def persisted_translation
+    Purizumu::Translation.find_by!(
+      model_class_name: 'GemRecord',
+      record_id: record.id,
+      attribute_name: 'human_name',
+      locale: 'jp'
+    )
+  end
+
+  def translate_arguments
+    {
+      model_name: 'GemRecord',
+      attribute_name: 'human_name',
+      content: 'Prism',
+      locale: 'jp',
+      source_locale: 'en'
+    }
+  end
+end

data/spec/purizumu/translator_spec.rb

@@ -110,6 +110,76 @@ RSpec.describe Purizumu::Translator do
       expect(Purizumu::Translation.where(record_id: blank_record.id)).to be_empty
     end
 
+    context 'with an unsaved record' do
+      let(:unsaved_record) { GemRecord.new(human_name: 'Prism', slug: 'prism') }
+
+      before do
+        allow(Purizumu).to receive(:engine)
+        I18n.locale = :jp
+        unsaved_record.human_name
+      end
+
+      it 'returns the source content' do
+        expect(unsaved_record.human_name).to eq('Prism')
+      end
+
+      it 'does not invoke the engine' do
+        expect(Purizumu).not_to have_received(:engine)
+      end
+
+      it 'does not create a translation row' do
+        expect(Purizumu::Translation.where(model_class_name: 'GemRecord')).to be_empty
+      end
+    end
+
+    context 'when validations read a translated attribute on create' do
+      before do
+        stub_validated_gem_record
+        allow(Purizumu).to receive(:engine)
+        I18n.locale = :jp
+      end
+
+      it 'does not raise during create' do
+        expect { create_validated_gem_record }.not_to raise_error
+      end
+
+      it 'does not invoke the engine' do
+        create_validated_gem_record
+
+        expect(Purizumu).not_to have_received(:engine)
+      end
+
+      it 'does not create translation rows' do
+        create_validated_gem_record
+
+        expect(Purizumu::Translation.where(model_class_name: 'ValidatedGemRecord')).to be_empty
+      end
+    end
+
+    context 'when callbacks read a translated attribute before validation on create' do
+      before do
+        stub_slugged_gem_record
+        allow(Purizumu).to receive(:engine)
+        I18n.locale = :jp
+      end
+
+      it 'allows the callback to derive values from the source attribute' do
+        expect(create_slugged_gem_record.slug).to eq('crystal-clear')
+      end
+
+      it 'does not invoke the engine' do
+        create_slugged_gem_record
+
+        expect(Purizumu).not_to have_received(:engine)
+      end
+
+      it 'does not create translation rows' do
+        create_slugged_gem_record
+
+        expect(Purizumu::Translation.where(model_class_name: 'SluggedGemRecord')).to be_empty
+      end
+    end
+
     it 'clears persisted translations for a changed translated attribute after commit' do
       create_existing_translation
 
@@ -154,6 +224,37 @@ RSpec.describe Purizumu::Translator do
     Purizumu::Translation.create!(existing_translation_attributes)
   end
 
+  def stub_validated_gem_record
+    stub_const('ValidatedGemRecord', Class.new(ActiveRecord::Base) do
+      self.table_name = 'gems'
+
+      validates :human_name, presence: true
+      attribute_translation :human_name
+    end)
+  end
+
+  def create_validated_gem_record
+    ValidatedGemRecord.create!(human_name: 'Prism', slug: 'prism')
+  end
+
+  def stub_slugged_gem_record
+    stub_const('SluggedGemRecord', Class.new(ActiveRecord::Base) do
+      self.table_name = 'gems'
+
+      validates :human_name, presence: true
+      before_validation :generate_slug, if: -> { slug.blank? }
+      attribute_translation :human_name
+
+      def generate_slug
+        self.slug = human_name.to_s.parameterize
+      end
+    end)
+  end
+
+  def create_slugged_gem_record
+    SluggedGemRecord.create!(human_name: 'Crystal clear')
+  end
+
   def prepare_regenerated_translation
     create_existing_translation
     allow(Purizumu).to receive(:engine).and_return(

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: purizumu
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - OpenAI Codex
@@ -65,6 +65,7 @@ files:
 - lib/generators/purizumu/install/templates/create_purizumu_translations.rb.erb
 - lib/purizumu.rb
 - lib/purizumu/configuration.rb
+- lib/purizumu/engines/test.rb
 - lib/purizumu/engines/xai.rb
 - lib/purizumu/engines/xai/payload_builder.rb
 - lib/purizumu/engines/xai/response_parser.rb
@@ -77,9 +78,10 @@ files:
 - spec/purizumu/configuration_spec.rb
 - spec/purizumu/engines/xai_spec.rb
 - spec/purizumu/generators/install_generator_spec.rb
+- spec/purizumu/test_mode_spec.rb
 - spec/purizumu/translator_spec.rb
 - spec/spec_helper.rb
-- spec/tmp/generator/db/migrate/20260412203610_create_purizumu_translations.rb
+- spec/tmp/generator/db/migrate/20260814023453_create_purizumu_translations.rb
 homepage: https://example.com/purizumu
 licenses:
 - MIT