locallingo 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b218e7422188db797e061b9cf1133b1b25a630e9e4c6237c04f0f7fa94dd2b4f
-  data.tar.gz: 742d0794ade8f32f9346d4a02b61554b7cb81321569c5297f9d93c3f1639f4e3
+  metadata.gz: 47b5cfaffa1567e536de600f6f963538606fc386a89b61e90ad9cc4dd8327132
+  data.tar.gz: 767fa1b9c49c66a0b5b5e1bd6140edbca50edade201f415c9bfde2c6f0448206
 SHA512:
-  metadata.gz: 48e0a2e2625a03fc0d78e9b5a9884efc4ec0ee7525533f150865d7bb391c473edd96f44bbca6974a24a6e564d4d08e644a0b36403a5c8a51b28a0943d54c1d1c
-  data.tar.gz: 4f08c9b89ab57351c5099ff6e31c4c24fa6b33a16df8ec0b70cb0ba365e292d90ef0fbe047d4b5494b9c2c7abe0627657c6ce4b545fd4a4552150f7338fd159d
+  metadata.gz: fad2120d8032a4a019dda5f6c82cd2f597de9dd79f9bb4eab1b9026530c859316c232314325398f51e12d61fc043c95882960969d5be325a80e6676463b55862
+  data.tar.gz: ff18516ac297ff0612111d0326552e6e771a6e0299854c598f3ea5645e9baaf722dd80e2571fc68186f3225af3eb35a69dc496107904feedd2cfc9d7356b1e8a

data/CHANGELOG.md

@@ -4,6 +4,51 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0]
+
+### Added
+- `Locallingo::Configuration.parse(text, root_path:, package:)` resolves
+  config from YAML text (ERB included) instead of `.locallingo.yml`, merged
+  over the shipped defaults the same way. (#35)
+- Concurrency conformance, development only (no new runtime dependency): CI
+  runs the suite on Ruby 4.0 too, and every pull request runs
+  conformance-kit 0.4's Conformance workflow: thread and fiber contention
+  examples, a Ractor canary of the pure core on Ruby 4.0, and a strict audit
+  of the gem's shared state. (#35)
+
+### Changed
+- Settings are frozen after boot, with nothing to call: the default settings
+  are frozen at load, and `Locallingo.configure` (a Rails initializer, or the
+  CLI's `.locallingo.rb`) publishes them frozen, in one assignment, so a
+  concurrent reader sees the old settings or the new, never half of them.
+  Concurrent `configure` calls run one at a time, so neither drops the
+  other's keys. Change them by calling `configure` again: **writing to
+  `Locallingo.settings` directly now raises `FrozenError`.** String keys are
+  stored as frozen plain String copies (a String subclass or its ivars are not
+  kept), so the settings are Ractor-shareable. A callable
+  key is kept as it is and never makes `configure` raise, even when it closes
+  over app state (a logger, a vault client); it keeps the settings readable
+  on the main Ractor only. (#35)
+- `translates_content` freezes its declaration at boot: the column and state
+  names and a String or Array `source_locale:`/`target_locales:` (as frozen
+  copies; the objects passed in are not frozen), and the drift. **Mutating them
+  through `locallingo_translatable` now raises `FrozenError`.** Callables
+  (`source_locale:`, `target_locales:`, `translatable:`, `hasher:`) are kept
+  as they are and never make the declaration raise. (#35)
+
+### Fixed
+- Without a `RubyLLM::Context`, a translation or quality-review call no
+  longer writes the resolved key into the process-global `RubyLLM.config`;
+  each call runs on a context of its own. Two translators with different keys
+  in one process could race, and one chat with the other's key. (#35)
+- `after_translate` hooks run via `system(command, chdir:)` instead of inside
+  `Dir.chdir`, which moved the working directory of the whole process while a
+  hook ran. (#35)
+- The static quality checks and `Configuration` (its ERB included) run inside
+  a non-main Ractor on Ruby 4.0: nested constants are frozen, and ERB no
+  longer evaluates on `TOPLEVEL_BINDING` (templates still resolve constants
+  from the top level, as the app sees them). (#35)
+
 ## [Unreleased]
 
 ### Added

data/README.md

@@ -46,7 +46,12 @@ end
 Put that in a `.locallingo.rb` file next to `.locallingo.yml` and the `lingo`
 CLI loads it on start — no Rails boot required. A key set via
 `Locallingo.configure` wins over one set through `RubyLLM.configure`, which
-wins over ENV. Locallingo never stores keys itself.
+wins over ENV. Locallingo never stores keys itself. `configure` publishes the
+settings frozen: change them by calling it again, never by writing to
+`Locallingo.settings`. Nothing else needs calling at boot. With String keys
+the settings are Ractor-shareable; a callable key is kept as it is (resolved on
+every use, so it may close over a logger or a vault client), which keeps the
+settings readable on the main Ractor only.
 
 ## Configuration
 
@@ -146,6 +151,10 @@ Locallingo::Manager.new(config:).validate           # => [violations]
 Locallingo::QualityChecker.new(config:).check(locale: "en")
 ```
 
+`Locallingo::Configuration.parse(yaml, root_path:, package:)` resolves the same
+config from YAML text (ERB included) instead of reading `.locallingo.yml`. A
+configuration loaded from the file reads it when it is built, never cached.
+
 ### Translating text that is not in locale files
 
 `Locallingo::Translator` runs the same prompt (rules, glossary, language guide),
@@ -170,9 +179,9 @@ result.translations # => { "title" => "Hallo", "intro" => "Etwas **Markdown**."
 result.failed       # => keys that failed after retries
 ```
 
-- With a `context:`, every call uses that `RubyLLM::Context`'s config; the
-  global `RubyLLM.config` is never written, so tenants can translate
-  concurrently.
+- Every call runs on a `RubyLLM::Context`: the `context:` given, else one
+  built for that call from the resolved key. The global `RubyLLM.config` is
+  never written, so tenants can translate concurrently.
 - `MissingCredentialsError` is raised before any call when no key is found.
 - `translate.max_batch_chars` (or `max_batch_chars:`) limits the source
   characters per batch (a single longer value is sent alone, not split); `translate.pause` (or `pause:`) is the sleep after each
@@ -237,6 +246,10 @@ Locallingo::RecordTranslator.new(translator:)
   for the next run (your fallback to the source locale applies meanwhile).
 - Writes use `update_columns`; pass `write: ->(record, attributes) { … }` to
   bump a lock version or run validations.
+- `translates_content` freezes the declaration as it is made, at boot: the
+  column and state names, a String or Array locale option (as a frozen copy)
+  and the drift. Callables are kept as they are, so they may close over app
+  state; like the model itself, a declaration is read on the main Ractor.
 
 ## License
 

data/lib/locallingo/active_record.rb

@@ -29,20 +29,39 @@ module Locallingo
     Definition = Data.define(:column, :state, :source_locale, :target_locales, :translatable, :drift)
 
     included do
-      class_attribute :locallingo_translatable, instance_writer: false
+      # The model's declaration: written once by translates_content in its class
+      # body at boot (main Ractor), and only read after that.
+      class_attribute :locallingo_translatable, instance_writer: false # rubocop:disable ThreadSafety/ClassAndModuleAttributes
     end
 
     class_methods do
+      # The declaration is frozen as it is made, at boot: the column and state
+      # names and a String/Symbol/Array locale option (frozen copies; the
+      # caller's own objects are left alone), and the Drift. Callables (locale options,
+      # translatable:, hasher:) are kept as they are, so a declaration holding
+      # one is read on the main Ractor only, like the model itself.
       def translates_content(column, state:, source_locale:, target_locales:, translatable: nil, hasher: nil)
         self.locallingo_translatable = Definition.new(
-          column: column.to_s, state: state.to_s, source_locale:, target_locales:,
+          column: Translatable.frozen_option(column.to_s), state: Translatable.frozen_option(state.to_s),
+          source_locale: Translatable.frozen_option(source_locale),
+          target_locales: Translatable.frozen_option(target_locales),
           translatable: translatable || ->(_path, _value) { true },
-          drift: hasher ? Drift.new(hasher:) : Drift.new
+          drift: (hasher ? Drift.new(hasher:) : Drift.new).freeze
         )
         before_save :mark_hand_edits
       end
     end
 
+    # A frozen copy of a non-callable declaration option (a String, or an Array
+    # of them); a callable or an already frozen value comes back as it is.
+    def self.frozen_option(value)
+      case value
+      when Array then value.map { |item| frozen_option(item) }.freeze
+      when String then value.frozen? ? value : value.dup.freeze
+      else value
+      end
+    end
+
     def translation_source_locale = resolve_translation_option(locallingo_translatable.source_locale).to_s
 
     def translation_target_locales

data/lib/locallingo/configuration.rb

@@ -14,9 +14,12 @@ module Locallingo
   #
   # Typed readers expose everything the Manager/QualityChecker/CLI need, so no
   # other class parses raw config hashes.
+  #
+  # The file is read when a Configuration is built (the CLI builds one per run)
+  # and never cached in the process, so an edit applies to the next run.
   class Configuration
     CONFIG_FILENAMES = %w[.locallingo.yml .locallingo.yaml].freeze
-    DEFAULT_CONFIG_PATH = File.expand_path("../../config/locallingo.default.yml", __dir__)
+    DEFAULT_CONFIG_PATH = File.expand_path("../../config/locallingo.default.yml", __dir__).freeze
 
     attr_reader :root_path, :package, :data
 
@@ -26,10 +29,18 @@ module Locallingo
       new(root_path:, package:)
     end
 
-    def initialize(root_path: Dir.pwd, package: nil, data: nil)
+    # Resolve config from YAML +text+ (what a `.locallingo.yml` holds, ERB
+    # included) instead of the file under +root_path+, merged over the shipped
+    # defaults the same way.
+    def self.parse(text, root_path: Dir.pwd, package: nil)
+      new(root_path:, package:, source: text)
+    end
+
+    # +source+ is YAML text read in place of the config file (see .parse).
+    def initialize(root_path: Dir.pwd, package: nil, data: nil, source: nil)
       @root_path = File.expand_path(root_path)
       @package = package
-      @data = data || resolve
+      @data = data || resolve(source)
     end
 
     # --- locations -----------------------------------------------------------
@@ -113,9 +124,10 @@ module Locallingo
     def dig(*keys) = data.dig(*keys)
 
     # Merge: shipped defaults <- user `defaults:` <- selected `packages:` entry.
-    def resolve
-      merged = deep_merge(shipped_defaults, user_defaults)
-      merged = deep_merge(merged, package_overrides) if package
+    def resolve(source)
+      document, origin = user_config(source)
+      merged = deep_merge(shipped_defaults, document.fetch("defaults", {}) || {})
+      merged = deep_merge(merged, package_overrides(document, origin)) if package && origin
       merged
     end
 
@@ -123,20 +135,19 @@ module Locallingo
       load_yaml(DEFAULT_CONFIG_PATH).fetch("defaults", {})
     end
 
-    def user_defaults
-      file = config_file
-      return {} unless file
+    # The user's config and where it came from: the +source+ text, else the
+    # config file under root_path, else nothing.
+    def user_config(source)
+      return [parse_yaml(source), "the given YAML"] if source
 
-      load_yaml(file).fetch("defaults", {}) || {}
-    end
-
-    def package_overrides
       file = config_file
-      return {} unless file
+      file ? [load_yaml(file), file] : [{}, nil]
+    end
 
-      packages = load_yaml(file).fetch("packages", []) || []
+    def package_overrides(document, origin)
+      packages = document.fetch("packages", []) || []
       entry = packages.find { |p| p["path"] == package }
-      raise Error, "No package #{package.inspect} in #{file}" unless entry
+      raise Error, "No package #{package.inspect} in #{origin}" unless entry
 
       entry.except("path")
     end
@@ -147,10 +158,19 @@ module Locallingo
         .find { |path| File.exist?(path) }
     end
 
-    def load_yaml(path)
-      YAML.safe_load(ERB.new(File.read(path)).result, aliases: true) || {}
+    def load_yaml(path) = parse_yaml(File.read(path))
+
+    def parse_yaml(text)
+      YAML.safe_load(ERB.new(text).result(erb_binding), aliases: true) || {}
     end
 
+    # ERB's default binding is TOPLEVEL_BINDING, which a non-main Ractor cannot
+    # reach; a blank object's binding evaluates the same templates. The string
+    # form, not a block: a block would resolve constants from inside
+    # Locallingo::Configuration (`Settings` would be Locallingo::Settings), the
+    # string resolves them from the top level, as TOPLEVEL_BINDING did.
+    def erb_binding = Object.new.instance_eval("binding", __FILE__, __LINE__)
+
     def deep_merge(base, override)
       base.merge(override) do |_key, base_val, override_val|
         if base_val.is_a?(Hash) && override_val.is_a?(Hash)

data/lib/locallingo/manager.rb

@@ -163,11 +163,12 @@ module Locallingo
       combined
     end
 
-    # Run the configured after_translate hook commands (from the app root).
+    # Run the configured after_translate hook commands (from the app root, in
+    # the child process only: the process-wide cwd is never changed).
     def run_after_translate_hooks
       config.after_translate.each do |command|
         log("Running: #{command}")
-        Dir.chdir(config.root_path) { system(command) }
+        system(command, chdir: config.root_path)
       end
     end
 

data/lib/locallingo/providers/ruby_llm.rb

@@ -19,10 +19,11 @@ module Locallingo
     # that support caching (Anthropic, OpenAI-compatible) bill the repeated
     # prefix at the cached rate.
     #
-    # Given a `RubyLLM::Context` (`RubyLLM.context { |c| c.anthropic_api_key = … }`),
-    # every chat runs on that context's own configuration: the global
-    # `RubyLLM.config` is never written, so translators with different keys
-    # (one per tenant) can run concurrently.
+    # Every chat runs on a `RubyLLM::Context`: the one given
+    # (`RubyLLM.context { |c| c.anthropic_api_key = … }`), else a fresh one built
+    # for that chat from the resolved key. The global `RubyLLM.config` is never
+    # written, so translators with different keys (one per tenant) can run
+    # concurrently.
     class RubyLLM
       # Maps a RubyLLM provider symbol to the ENV var whose presence indicates
       # credentials are available, so we can fail fast with a clear message
@@ -82,30 +83,24 @@ module Locallingo
       private
 
       def new_chat(model)
-        return context.chat(model:, provider:, assume_model_exists: true) if context
-
-        configure_credentials!
-        ::RubyLLM.chat(model:, provider:, assume_model_exists: true)
+        (context || chat_context).chat(model:, provider:, assume_model_exists: true)
       end
 
-      # RubyLLM does not read provider API keys from ENV on its own, so a
-      # standalone CLI run (no Rails initializer to call RubyLLM.configure)
-      # would raise "Missing configuration for <provider>". Push the resolved
-      # key into RubyLLM's config: an explicit `Locallingo.configure` key wins
-      # (re-resolved every chat so callables stay live), then a key the host
-      # app already set, then the ENV fallback.
-      def configure_credentials!
-        return unless CREDENTIAL_ENV.key?(provider)
-
-        config = ::RubyLLM.config
-        setting = key_setting
-        return unless config.respond_to?(setting) && config.respond_to?("#{setting}=")
-
-        key = settings_api_key
-        return if key.nil? && !presence(config.public_send(setting)).nil?
-
-        key ||= env_api_key
-        config.public_send("#{setting}=", key) unless key.nil?
+      # A context of its own for one chat. `RubyLLM.context` copies the global
+      # config, so a key the host app set via RubyLLM.configure carries over;
+      # an explicit `Locallingo.configure` key wins over it (re-resolved every
+      # chat so callables stay live), and ENV fills in when neither is set
+      # (RubyLLM does not read provider keys from ENV on its own, so a
+      # standalone CLI run would otherwise raise "Missing configuration").
+      def chat_context
+        ::RubyLLM.context do |config|
+          setting = key_setting
+          next unless CREDENTIAL_ENV.key?(provider) && config.respond_to?("#{setting}=")
+
+          key = settings_api_key
+          key ||= env_api_key if presence(config.public_send(setting)).nil?
+          config.public_send("#{setting}=", key) unless key.nil?
+        end
       end
 
       # Key resolution across sources, in precedence order. Used by

data/lib/locallingo/quality/static_rules.rb

@@ -11,6 +11,7 @@ module Locallingo
         "Can not" => "Cannot"
       }.freeze
 
+      # Every level frozen, so any Ractor can read the rules.
       RULES = {
         terminology: {
           /\bcan not\b/i => "Use 'cannot' (one word)",
@@ -18,11 +19,11 @@ module Locallingo
             "Use 'log in' (verb) not 'login' here",
           /\bclick\s+here\b/i => "Avoid 'click here' - use descriptive link text",
           /\bplease\b.*\bplease\b/i => "Multiple 'please' in same text - remove redundancy"
-        },
+        }.freeze,
         placeholders: {
           /%\{[^}]*\s[^}]*\}/ => "Placeholder contains spaces - may cause issues",
           /%\{[A-Z]/ => "Placeholder starts with uppercase - convention is lowercase"
-        },
+        }.freeze,
         clarity: {
           /\betc\.?\b/i => "Avoid 'etc.' - be specific or use 'and more'",
           /\bstuff\b/i => "Vague word 'stuff' - be more specific",
@@ -30,19 +31,19 @@ module Locallingo
           /\basap\b/i => "Avoid abbreviation 'ASAP' - use 'as soon as possible'",
           /\bfyi\b/i => "Avoid abbreviation 'FYI' - rephrase",
           /\s{2,}/ => "Multiple consecutive spaces"
-        },
+        }.freeze,
         business: {
           /\bsorry\b/i => "Consider 'We apologize' for formal business tone",
           /\boops\b/i => "Informal - use professional error messaging",
           /\buh\s*oh\b/i => "Informal - use professional error messaging",
           /\bawesome\b/i => "Consider more professional alternatives",
           /\bcool\b(?!\s*down)/i => "Informal - consider 'great' or 'excellent'"
-        },
+        }.freeze,
         accessibility: {
           /\bsee\s+below\b/i => "Screen reader unfriendly - describe the content",
           /\babove\b/i => "Positional reference - may not work for all users",
           /\bred\b.*\berror\b|\berror\b.*\bred\b/i => "Don't rely on color alone for meaning"
-        }
+        }.freeze
       }.freeze
 
       module_function

data/lib/locallingo/quality/terminology.rb

@@ -36,7 +36,7 @@ module Locallingo
         "cdd" => nil
       ).freeze
 
-      BUILTINS = { "business" => BUSINESS, "banking" => BANKING, "none" => {} }.freeze
+      BUILTINS = { "business" => BUSINESS, "banking" => BANKING, "none" => {}.freeze }.freeze
 
       attr_reader :terms
 

data/lib/locallingo/record_translator.rb

@@ -18,7 +18,10 @@ module Locallingo
   # Records must be persisted and of one model (ids are the key prefix). This
   # class never loads ActiveRecord itself; records only need the concern.
   class RecordTranslator
+    # A capture-free lambda, made shareable where the engine has Ractors, so
+    # the constant is readable from any Ractor.
     DEFAULT_WRITE = ->(record, attributes) { record.update_columns(attributes) }
+                    .then { |write| defined?(::Ractor) ? ::Ractor.make_shareable(write) : write }
 
     # +write+ is called as `write.call(record, attributes)` inside the lock,
     # e.g. to bump a lock version or run validations (`record.update!(attributes)`).

data/lib/locallingo/rubocop.rb

@@ -16,6 +16,6 @@ require_relative "../rubocop/cop/locallingo/strftime_in_view"
 module Locallingo
   # Absolute path to the cop defaults, for `inherit_gem: locallingo: <path>`.
   module RuboCop
-    CONFIG_DEFAULT = File.expand_path("../../config/default.yml", __dir__)
+    CONFIG_DEFAULT = File.expand_path("../../config/default.yml", __dir__).freeze
   end
 end

data/lib/locallingo/settings.rb

@@ -12,10 +12,21 @@ module Locallingo
   #
   # Callables are resolved lazily on every use (never memoized), so keys can
   # come from sources that aren't ready at configure time or that rotate.
+  #
+  # A String key is stored as a frozen plain String copy, so settings frozen by
+  # `Locallingo.configure` are Ractor-shareable; a callable is kept as is.
   class Settings
     PROVIDERS = %i[openai anthropic gemini deepseek openrouter].freeze
 
-    attr_accessor(*PROVIDERS.map { |name| :"#{name}_api_key" })
+    attr_reader(*PROVIDERS.map { |name| :"#{name}_api_key" })
+
+    PROVIDERS.each do |name|
+      define_method(:"#{name}_api_key=") do |value|
+        # A plain String copy: a subclass or its ivars could carry mutable state.
+        value = String.new(value).freeze if value.is_a?(String)
+        instance_variable_set(:"@#{name}_api_key", value)
+      end
+    end
 
     # The usable key for +provider+: callables are called, results stripped,
     # and blank or unknown-provider values come back as nil.

data/lib/locallingo/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Locallingo
-  VERSION = "0.5.1"
+  VERSION = "0.6.0"
 end

data/lib/locallingo.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "monitor"
 require_relative "locallingo/version"
 require_relative "locallingo/settings"
 require_relative "locallingo/configuration"
@@ -42,20 +43,59 @@ module Locallingo
     Configuration.load(root_path:, package:)
   end
 
-  # Code-level settings (provider credentials) — see Locallingo::Settings.
-  def self.settings
-    @settings ||= Settings.new
+  # Boot-time state, finalized: always a frozen Settings, so any thread or
+  # Ractor reads finished settings and only `configure` replaces them. With
+  # String keys (or none) it is Ractor-shareable; a callable key is not, so it
+  # keeps the settings readable on the main Ractor only.
+  #
+  # rubocop:disable ThreadSafety/ClassInstanceVariable -- @settings is written only by configure and reset_settings!, at boot on the main Ractor, and always holds a frozen Settings; @configure_lock (engines without Ractor only) is set once, at load
+  @settings = Settings.new.freeze
+
+  # Serializes configure: one Monitor per Ractor, in Ractor-local storage (only
+  # the main Ractor can publish @settings, so in practice the main Ractor's).
+  # The main Ractor's is made here, at load, never lazily. A Monitor, so a
+  # configure nested in a configure block does not deadlock. Engines without
+  # Ractor keep it in @configure_lock.
+  if defined?(::Ractor)
+    ::Ractor.current[:locallingo_configure_lock] = Monitor.new
+  else
+    @configure_lock = Monitor.new
   end
 
+  # Code-level settings (provider credentials) — see Locallingo::Settings.
+  def self.settings = @settings
+
   # Configure the gem from Ruby — the credentials path for apps whose keys
   # don't live in ENV (call it from a Rails initializer or a `.locallingo.rb`
   # setup file next to `.locallingo.yml`; the CLI loads the latter on start).
+  # Yields a copy of the current settings, then publishes it frozen in one
+  # assignment: a concurrent reader sees the old settings or the new, never
+  # half of them. Concurrent calls run one at a time, so neither drops the
+  # other's keys. Calling it again keeps the keys it does not set.
   def self.configure
-    yield settings
-    settings
+    configure_lock.synchronize do
+      draft = settings.dup
+      yield draft
+      @settings = draft.freeze
+    end
   end
 
+  # Back to frozen, blank defaults (for tests).
   def self.reset_settings!
-    @settings = nil
+    @settings = Settings.new.freeze
+  end
+
+  # Another Ractor's lock is made on first use: atomically on Ruby 3.4+; below,
+  # two of its threads could each make one, which is harmless because a
+  # non-main Ractor cannot publish settings anyway.
+  def self.configure_lock
+    return @configure_lock unless defined?(::Ractor)
+
+    key = :locallingo_configure_lock
+    return ::Ractor.store_if_absent(key) { Monitor.new } if ::Ractor.respond_to?(:store_if_absent)
+
+    ::Ractor.current[key] ||= Monitor.new
   end
+  private_class_method :configure_lock
+  # rubocop:enable ThreadSafety/ClassInstanceVariable
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: locallingo
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Mikael Henriksson