familia 2.0.0.pre16 → 2.0.0.pre18

data/pr_compliance_checklist.yaml

@@ -0,0 +1,45 @@
+# Custom Compliance Checklist for Familia
+# Documentation: https://qodo-merge-docs.qodo.ai/tools/compliance/
+
+pr_compliances:
+  - title: "ErrorHandling"
+    compliance_label: true
+    objective: "All external API calls and database operations must have proper error handling"
+    success_criteria: "Try-catch blocks around external calls with appropriate logging or error handling mechanisms"
+    failure_criteria: "External API calls, database operations, or network requests without error handling"
+
+  - title: "TestCoverage"
+    compliance_label: true
+    objective: "New features must include corresponding tests using the Tryouts framework"
+    success_criteria: "Test files present in try/ directory for new functionality following *_try.rb or *.try.rb naming convention"
+    failure_criteria: "New code without test coverage or tests not following Tryouts framework conventions"
+
+  - title: "ChangelogFragment"
+    compliance_label: true
+    objective: "User-facing changes must include a changelog"
+    success_criteria: "New fragment file in changelog.d/ directory following the naming convention and RST format, or updates to CHANGELOG.rst in root directory, or explicit justification for omission"
+    failure_criteria: "User-facing changes without changelog fragment, CHANGELOG.rst updates, or documentation updates"
+
+  - title: "DocumentationUpdates"
+    compliance_label: true
+    objective: "API changes must be reflected in documentation"
+    success_criteria: "YARD documentation comments for new public methods, or updates to docs/ for significant changes"
+    failure_criteria: "New public APIs or significant behavior changes without documentation updates"
+
+  - title: "BackwardCompatibility"
+    compliance_label: true
+    objective: "Changes must maintain backward compatibility or document breaking changes"
+    success_criteria: "No breaking changes to public APIs, or breaking changes clearly documented in migration guides"
+    failure_criteria: "Breaking changes without migration documentation or deprecation warnings"
+
+  - title: "ThreadSafety"
+    compliance_label: true
+    objective: "Code handling shared state must be thread-safe"
+    success_criteria: "Proper synchronization for shared mutable state, or clear documentation of thread-safety assumptions"
+    failure_criteria: "Shared mutable state accessed without synchronization in concurrent contexts"
+
+  - title: "DatabaseKeyNaming"
+    compliance_label: true
+    objective: "Database key generation must follow Familia conventions"
+    success_criteria: "Keys use delim separator, avoid reserved keywords (ttl, db, valkey, redis), and handle empty identifiers"
+    failure_criteria: "Keys using reserved keywords, empty identifiers, or non-standard separators"

data/try/edge_cases/empty_identifiers_try.rb

@@ -2,7 +2,7 @@
 
 # Test empty identifier edge cases
 
-require_relative '../helpers/test_helpers'
+require_relative '../support/helpers/test_helpers'
 
 
 ## empty string identifier handling

data/try/edge_cases/hash_symbolization_try.rb

@@ -4,7 +4,7 @@
 # bug in Tryouts 3.1 that prevents the setup instance vars from
 # being available to the testcases.
 
-require_relative '../helpers/test_helpers'
+require_relative '../support/helpers/test_helpers'
 
 Familia.debug = false
 
@@ -25,22 +25,31 @@ end
 @test_hash.keys
 #=> ["name", "age", "nested"]
 
-## After save and refresh, default behavior uses symbol keys
+## After save and refresh, default behavior uses string keys
 @test_obj.refresh!
 @test_obj.config.keys
-#=> [:name, :age, :nested]
+#=> ["name", "age", "nested"]
 
-## Nested hash also has symbol keys
-@test_obj.config[:nested].keys
-#=> [:theme]
+## Nested hash also has string keys
+@test_obj.config["nested"].keys
+#=> ["theme"]
 
 ## Get raw JSON from Valkey/Redis
 @raw_json = @test_obj.hget('config')
 @raw_json.class
 #=> String
 
-## deserialize_value with default symbolize: true returns symbol keys
-@symbol_result = @test_obj.deserialize_value(@raw_json)
+## deserialize_value with default symbolize: false returns string keys
+@string_result_default = @test_obj.deserialize_value(@raw_json)
+@string_result_default.keys
+#=> ["name", "age", "nested"]
+
+## Nested hash in default result also has string keys
+@string_result_default["nested"].keys
+#=> ["theme"]
+
+## deserialize_value with symbolize: true returns symbol keys
+@symbol_result = @test_obj.deserialize_value(@raw_json, symbolize: true)
 @symbol_result.keys
 #=> [:name, :age, :nested]
 
@@ -48,21 +57,12 @@ end
 @symbol_result[:nested].keys
 #=> [:theme]
 
-## deserialize_value with symbolize: false returns string keys
-@string_result = @test_obj.deserialize_value(@raw_json, symbolize: false)
-@string_result.keys
-#=> ["name", "age", "nested"]
-
-## Nested hash in string result also has string keys
-@string_result['nested'].keys
-#=> ["theme"]
-
-## Values are preserved correctly in both cases
+## Values are preserved correctly with symbol keys
 @symbol_result[:name]
 #=> "John"
 
-## String keys also work correctly
-@string_result['name']
+## Values are preserved correctly with string keys
+@string_result_default['name']
 #=> "John"
 
 ## Arrays are handled correctly too
@@ -71,27 +71,27 @@ end
 @array_json = @test_obj.hget('config')
 #=> "[{\"item\":\"value\"},\"string\",123]"
 
+## Array with default (symbolize: false) keeps hash keys as strings
+@string_array_default = @test_obj.deserialize_value(@array_json)
+@string_array_default[0].keys
+#=> ["item"]
+
 ## Array with symbolize: true converts hash keys to symbols
-@symbol_array = @test_obj.deserialize_value(@array_json)
+@symbol_array = @test_obj.deserialize_value(@array_json, symbolize: true)
 @symbol_array[0].keys
 #=> [:item]
 
-## Array with symbolize: false keeps hash keys as strings
-@string_array = @test_obj.deserialize_value(@array_json, symbolize: false)
-@string_array[0].keys
-#=> ["item"]
-
-## Non-hash/array values are returned as-is
+## JSON-encoded string is parsed correctly
 @test_obj.deserialize_value('"just a string"')
-#=> "\"just a string\""
+#=> "just a string"
 
-## Non-hash/array values are returned as-is
+## Non-JSON string returns as-is
 @test_obj.deserialize_value('just a string')
 #=> "just a string"
 
-## A stringified number is still a stringified number
+## JSON number is parsed to Integer
 @test_obj.deserialize_value('42')
-#=> "42"
+#=> 42
 
 ## Invalid JSON returns original string
 @test_obj.deserialize_value('invalid json')

data/try/edge_cases/json_serialization_try.rb

@@ -1,6 +1,6 @@
 # try/edge_cases/json_serialization_try.rb
 
-require_relative '../helpers/test_helpers'
+require_relative '../support/helpers/test_helpers'
 
 Familia.debug = false
 
@@ -44,7 +44,7 @@ test_obj.simple = 'just a string'
 test_obj.tags = %w[ruby valkey json familia]
 test_obj.save
 test_obj.hgetall
-#=> {"id"=>"json_test_1", "config"=>"{\"theme\":\"dark\",\"notifications\":true,\"settings\":{\"volume\":80}}", "tags"=>"[\"ruby\",\"valkey\",\"json\",\"familia\"]", "simple"=>"just a string"}
+#=> {"id"=>"\"json_test_1\"", "config"=>"{\"theme\":\"dark\",\"notifications\":true,\"settings\":{\"volume\":80}}", "tags"=>"[\"ruby\",\"valkey\",\"json\",\"familia\"]", "simple"=>"\"just a string\""}
 
 ## Test 4: Hash should be deserialized back to Hash
 test_obj = JsonTest.new 'any_id_will_do'

data/try/edge_cases/legacy_data_detection/deserialization_edge_cases_try.rb

@@ -0,0 +1,170 @@
+# Edge case tests for deserialize_value with legacy data detection
+#
+# Tests the nuanced deserialization that distinguishes between:
+# - Corrupted JSON (data that looks like JSON but fails to parse)
+# - Legacy plain strings (data that was never JSON)
+# - Valid JSON data
+
+require_relative '../../../lib/familia'
+require 'logger'
+require 'stringio'
+
+# Capture log output for verification
+@log_output = StringIO.new
+@original_logger = Familia.instance_variable_get(:@logger)
+Familia.instance_variable_set(:@logger, Logger.new(@log_output))
+Familia.instance_variable_get(:@logger).level = Logger::DEBUG
+
+class TestModel < Familia::Horreum
+  identifier_field :test_id
+  field :test_id
+  field :data
+end
+
+@model = TestModel.new(test_id: "test1")
+
+## Valid JSON number deserializes correctly
+@result = @model.deserialize_value("123", field_name: :data)
+@result
+#=> 123
+
+## Valid JSON boolean deserializes correctly
+@result = @model.deserialize_value("true", field_name: :data)
+@result
+#=> true
+
+## Valid JSON string deserializes correctly
+@result = @model.deserialize_value('"hello"', field_name: :data)
+@result
+#=> "hello"
+
+## Valid JSON array deserializes correctly
+@result = @model.deserialize_value('[1,2,3]', field_name: :data)
+@result
+#=> [1, 2, 3]
+
+## Valid JSON object deserializes correctly
+@result = @model.deserialize_value('{"key":"value"}', field_name: :data)
+@result
+#=> {"key"=>"value"}
+
+## Plain string (legacy data) returns as-is
+@log_output = StringIO.new
+Familia.instance_variable_set(:@logger, Logger.new(@log_output))
+Familia.instance_variable_get(:@logger).level = Logger::DEBUG
+@result = @model.deserialize_value("plain text", field_name: :data)
+@result
+#=> "plain text"
+
+## Legacy data logs at debug level
+@log_output.rewind
+@log_content = @log_output.read
+puts "LOG CONTENT: #{@log_content.inspect}" if ENV['DEBUG']
+@log_content
+#=~> /Legacy plain string/
+
+## Corrupted JSON starting with { logs error
+@log_output = StringIO.new
+Familia.instance_variable_set(:@logger, Logger.new(@log_output))
+Familia.instance_variable_get(:@logger).level = Logger::DEBUG
+@result = @model.deserialize_value("{broken", field_name: :data)
+@result
+#=> "{broken"
+
+## Corrupted JSON logs at error level
+@log_output.rewind
+@log_content = @log_output.read
+puts "LOG CONTENT: #{@log_content.inspect}" if ENV['DEBUG']
+@log_content.match?(/Corrupted JSON/)
+#=> true
+
+## Corrupted JSON starting with [ logs error
+@log_output = StringIO.new
+Familia.instance_variable_set(:@logger, Logger.new(@log_output))
+Familia.instance_variable_get(:@logger).level = Logger::DEBUG
+@result = @model.deserialize_value("[1,2,", field_name: :data)
+@result
+#=> "[1,2,"
+
+## Corrupted array logs at error level
+@log_output.rewind
+@log_content = @log_output.read
+@log_content.match?(/Corrupted JSON/)
+#=> true
+
+## Corrupted JSON starting with quote logs error
+@log_output = StringIO.new
+Familia.instance_variable_set(:@logger, Logger.new(@log_output))
+Familia.instance_variable_get(:@logger).level = Logger::DEBUG
+@result = @model.deserialize_value('"unterminated', field_name: :data)
+@result
+#=> '"unterminated'
+
+## Unterminated string logs at error level
+@log_output.rewind
+@log_content = @log_output.read
+@log_content.match?(/Corrupted JSON/)
+#=> true
+
+## Corrupted boolean-like value logs error
+@log_output = StringIO.new
+Familia.instance_variable_set(:@logger, Logger.new(@log_output))
+Familia.instance_variable_get(:@logger).level = Logger::DEBUG
+@result = @model.deserialize_value("true123", field_name: :data)
+@result
+#=> "true123"
+
+## Plain text starting with 'true' is legacy data
+@log_output.rewind
+@log_content = @log_output.read
+@log_content
+#=~> /Legacy plain string/
+
+## Field name context appears in error messages
+@log_output = StringIO.new
+Familia.instance_variable_set(:@logger, Logger.new(@log_output))
+Familia.instance_variable_get(:@logger).level = Logger::DEBUG
+@result = @model.deserialize_value("{broken", field_name: :important_field)
+@log_output.rewind
+@log_content = @log_output.read
+@log_content.match?(/TestModel#important_field/)
+#=> true
+
+## dbkey context appears in error messages when available
+@model.save
+@log_output = StringIO.new
+Familia.instance_variable_set(:@logger, Logger.new(@log_output))
+Familia.instance_variable_get(:@logger).level = Logger::DEBUG
+@result = @model.deserialize_value("{broken", field_name: :data)
+@log_output.rewind
+@log_content = @log_output.read
+@log_content.match?(/#{Regexp.escape(@model.dbkey)}/)
+#=> true
+
+## Empty string returns nil
+@result = @model.deserialize_value("", field_name: :data)
+@result
+#=> nil
+
+## nil returns nil
+@result = @model.deserialize_value(nil, field_name: :data)
+@result
+#=> nil
+
+## JSON null deserializes to nil
+@result = @model.deserialize_value("null", field_name: :data)
+@result
+#=> nil
+
+## Symbolize option works with hash keys
+@result = @model.deserialize_value('{"name":"test"}', symbolize: true, field_name: :data)
+@result.keys.first.class
+#=> Symbol
+
+## Default keeps string keys
+@result = @model.deserialize_value('{"name":"test"}', field_name: :data)
+@result.keys.first.class
+#=> String
+
+# Teardown
+Familia.instance_variable_set(:@logger, @original_logger)

data/try/edge_cases/race_conditions_try.rb

@@ -1,6 +1,6 @@
 # Test connection race conditions
 
-require_relative '../helpers/test_helpers'
+require_relative '../support/helpers/test_helpers'
 
 ## concurrent connection access test
 user_class = Class.new(Familia::Horreum) do

data/try/edge_cases/reserved_keywords_try.rb

@@ -1,6 +1,6 @@
 # Test reserved keyword handling
 
-require_relative '../helpers/test_helpers'
+require_relative '../support/helpers/test_helpers'
 
 ## attempting to use ttl as field name causes error
 TestClass = Class.new(Familia::Horreum) do

data/try/edge_cases/string_coercion_try.rb

@@ -1,6 +1,6 @@
 # try/edge_cases/string_coercion_try.rb
 
-require_relative '../helpers/test_helpers'
+require_relative '../support/helpers/test_helpers'
 
 Familia.debug = false
 

data/try/edge_cases/ttl_side_effects_try.rb

@@ -1,6 +1,6 @@
 # Test TTL side effects
 
-require_relative '../helpers/test_helpers'
+require_relative '../support/helpers/test_helpers'
 
 ## field update behavior with TTL
 begin

data/try/features/encrypted_fields/aad_protection_try.rb

@@ -3,7 +3,7 @@
 require 'concurrent'
 require 'base64'
 
-require_relative '../../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 
 test_keys = {
   v1: Base64.strict_encode64('a' * 32),

data/try/features/encrypted_fields/concealed_string_core_try.rb

@@ -1,6 +1,6 @@
 # try/features/encryption_fields/concealed_string_core_try.rb
 
-require_relative '../../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 require 'base64'
 
 Familia.debug = false

data/try/features/encrypted_fields/context_isolation_try.rb

@@ -2,7 +2,7 @@
 
 require 'base64'
 
-require_relative '../../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 
 # Setup encryption keys for testing
 test_keys = {

data/try/features/encrypted_fields/encrypted_fields_core_try.rb

@@ -1,6 +1,6 @@
 # try/features/encrypted_fields_core_try.rb
 
-require_relative '../../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 require 'base64'
 
 

data/try/features/encrypted_fields/encrypted_fields_integration_try.rb

@@ -2,7 +2,7 @@
 
 # Test constants will be redefined in each test since variables don't persist
 
-require_relative '../../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 require 'base64'
 
 

data/try/features/encrypted_fields/encrypted_fields_no_cache_security_try.rb

@@ -3,7 +3,7 @@
 # Security tests for the no-cache encryption strategy
 # These tests verify that we maintain security properties by NOT caching derived keys
 
-require_relative '../../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 
 test_keys = {
   v1: Base64.strict_encode64('a' * 32),

data/try/features/encrypted_fields/encrypted_fields_security_try.rb

@@ -1,6 +1,6 @@
 # try/features/encrypted_fields_security_try.rb
 
-require_relative '../../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 require 'base64'
 
 # Define all test classes up front to avoid tryouts retry conflicts

data/try/features/encrypted_fields/error_conditions_try.rb

@@ -2,7 +2,7 @@
 
 require 'base64'
 
-require_relative '../../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 
 # Setup encryption keys for error testing
 @test_keys = {

data/try/features/encrypted_fields/fresh_key_derivation_try.rb

@@ -2,7 +2,7 @@
 
 require 'base64'
 
-require_relative '../../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 
 test_keys = {
   v1: Base64.strict_encode64('a' * 32),

data/try/features/encrypted_fields/fresh_key_try.rb

@@ -1,4 +1,4 @@
-require_relative '../../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 require 'base64'
 
 # Setup encryption configuration

data/try/features/encrypted_fields/key_rotation_try.rb

@@ -2,7 +2,7 @@
 
 require 'base64'
 
-require_relative '../../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 
 # Setup multiple key versions for rotation testing
 @test_keys = {

data/try/features/encrypted_fields/memory_security_try.rb

@@ -1,7 +1,7 @@
 # try/features/encryption_fields/memory_security_try.rb
 
 require 'base64'
-require_relative '../../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 
 test_keys = {
   v1: Base64.strict_encode64('a' * 32),

data/try/features/encrypted_fields/missing_current_key_version_try.rb

@@ -2,7 +2,7 @@
 
 require 'base64'
 
-require_relative '../../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 
 # This tryouts file is based on the premise that there is no current key
 # version set. This is a global setting so if other tryouts rely on

data/try/features/encrypted_fields/nonce_uniqueness_try.rb

@@ -3,7 +3,7 @@
 require 'base64'
 require 'set'
 
-require_relative '../../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 
 test_keys = {
   v1: Base64.strict_encode64('a' * 32),

data/try/features/encrypted_fields/secure_by_default_behavior_try.rb

@@ -1,6 +1,6 @@
 # try/features/encryption_fields/secure_by_default_behavior_try.rb
 
-require_relative '../../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 require 'base64'
 
 Familia.debug = false

data/try/features/encrypted_fields/thread_safety_try.rb

@@ -3,7 +3,7 @@
 require 'concurrent'
 require 'base64'
 
-require_relative '../../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 
 # Setup encryption keys for testing
 test_keys = {

data/try/features/encrypted_fields/universal_serialization_safety_try.rb

@@ -1,6 +1,6 @@
 # try/features/encryption_fields/universal_serialization_safety_try.rb
 
-require_relative '../../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 require 'base64'
 
 Familia.debug = false

data/try/{encryption → features/encryption}/config_persistence_try.rb

@@ -5,7 +5,7 @@
 
 require 'base64'
 
-require_relative '../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 require 'familia/encryption/providers/xchacha20_poly1305_provider'
 
 # SETUP

data/try/{encryption/encryption_core_try.rb → features/encryption/core_try.rb}

@@ -1,7 +1,7 @@
 # try/encryption/encryption_core_try.rb
 
-require_relative '../helpers/test_helpers'
-require_relative '../../lib/familia/encryption'
+require_relative '../../support/helpers/test_helpers'
+require_relative '../../../lib/familia/encryption'
 require 'base64'
 
 # Test constants will be redefined in each test since variables don't persist

data/try/{encryption → features/encryption}/instance_variable_scope_try.rb

@@ -6,7 +6,7 @@
 
 require 'base64'
 
-require_relative '../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 
 @test_keys = {
   v1: Base64.strict_encode64('a' * 32)

data/try/{encryption → features/encryption}/module_loading_try.rb

@@ -5,7 +5,7 @@
 
 require 'base64'
 
-require_relative '../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 
 # Test basic functionality
 

data/try/{encryption → features/encryption}/providers/aes_gcm_provider_try.rb

@@ -1,6 +1,6 @@
 # try/encryption/providers/aes_gcm_provider_try.rb
 
-require_relative '../../helpers/test_helpers'
+require_relative '../../../support/helpers/test_helpers'
 require 'base64'
 
 ## AES-GCM provider availability check (always available with OpenSSL)

data/try/{encryption → features/encryption}/providers/xchacha20_poly1305_provider_try.rb

@@ -1,6 +1,6 @@
 # try/encryption/providers/xchacha20_poly1305_provider_try.rb
 
-require_relative '../../helpers/test_helpers'
+require_relative '../../../support/helpers/test_helpers'
 require 'base64'
 
 ## XChaCha20Poly1305 provider availability check

data/try/{encryption → features/encryption}/roundtrip_validation_try.rb

@@ -5,7 +5,7 @@
 
 require 'base64'
 
-require_relative '../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 
 ## Test successful encryption
 test_keys = { v1: Base64.strict_encode64('a' * 32) }

data/try/{encryption → features/encryption}/secure_memory_handling_try.rb

@@ -1,7 +1,7 @@
 # try/encryption/secure_memory_handling_try.rb
 
-require_relative '../helpers/test_helpers'
-require_relative '../../lib/familia/encryption/providers/secure_xchacha20_poly1305_provider'
+require_relative '../../support/helpers/test_helpers'
+require_relative '../../../lib/familia/encryption/providers/secure_xchacha20_poly1305_provider'
 require 'base64'
 
 # SETUP

data/try/features/expiration/expiration_try.rb

@@ -1,6 +1,6 @@
 # try/features/expiration_try.rb
 
-require_relative '../../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 
 Familia.debug = false
 

data/try/features/external_identifier/external_identifier_try.rb

@@ -1,6 +1,6 @@
 # try/features/external_identifier/external_identifier_try.rb
 
-require_relative '../../helpers/test_helpers'
+require_relative '../../support/helpers/test_helpers'
 
 Familia.debug = false