exwiw 0.9.6 → 0.9.8

data/lib/exwiw/strict_keys.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Exwiw
+  # Raised when a schema config JSON carries a key that no declared attribute
+  # accepts. A subclass of ArgumentError so existing "invalid config" handling
+  # (and specs) that rescue ArgumentError keep working.
+  UnknownConfigKeyError = Class.new(ArgumentError)
+
+  # Strict key validation for the schema config JSON.
+  #
+  # Serdes deserialization is lenient: a key that matches no declared attribute
+  # is silently dropped. For hand-maintained schema configs that turns a typo
+  # (`reverse_scop`) — or a key another adapter supports but this one does not
+  # (`raw_sql` on a MongoDB field) — into a silent no-op: the config loads, the
+  # dump runs, and the requested masking/scoping simply never happens.
+  # {TableConfig.from} / {MongodbCollectionConfig.from} therefore validate the
+  # raw hash against the declared attributes before deserializing, recursing
+  # into nested config objects (belongs_tos, columns/fields, reverse_scope,
+  # embedded_in, replace_with_fake_data).
+  #
+  # Free-form annotations do not need an escape hatch: `comment` is a declared
+  # (documentation-only) attribute on the table/collection configs and their
+  # belongs_to/column/field entries, so it always passes.
+  module StrictKeys
+    module_function
+
+    # Validate `hash` (a raw config hash, string- or symbol-keyed) against the
+    # attributes declared on the Serdes class `klass`, recursing into nested
+    # Serdes-typed attributes. `owner` names the config for the error message
+    # (e.g. "table 'users'"); `path` locates a nested entry within it (e.g.
+    # "belongs_tos[0]"). No-op for non-Hash input — Serdes' own type errors
+    # cover malformed values.
+    def validate!(klass, hash, owner:, path: nil)
+      return unless hash.is_a?(Hash)
+
+      attributes = klass.__send__(:_serde_attrs)
+      rename_strategy = klass.__send__(:_serde_rename_strategy)
+      allowed = attributes.each_value.to_h { |attr| [attr.serialized_name(rename_strategy), attr] }
+
+      unknown = hash.keys.map(&:to_s) - allowed.keys
+      unless unknown.empty?
+        location = path ? " (in #{path})" : ""
+        raise UnknownConfigKeyError,
+              "Unknown key#{'s' if unknown.size > 1} #{unknown.map { |key| "'#{key}'" }.join(', ')} " \
+              "in #{owner}#{location}. Allowed keys: #{allowed.keys.sort.join(', ')}. " \
+              "Unknown keys are rejected because they would otherwise be silently ignored " \
+              "(hiding typos and keys this adapter does not support); remove or rename the key, " \
+              "or use `comment` for free-form notes."
+      end
+
+      allowed.each do |key, attr|
+        nested_klass = serdes_class(attr.attr_type)
+        next if nested_klass.nil?
+
+        value = hash.key?(key) ? hash[key] : hash[key.to_sym]
+        nested_path = path ? "#{path}.#{key}" : key
+        case value
+        when Hash
+          validate!(nested_klass, value, owner: owner, path: nested_path)
+        when Array
+          value.each_with_index do |element, index|
+            validate!(nested_klass, element, owner: owner, path: "#{nested_path}[#{index}]") if element.is_a?(Hash)
+          end
+        end
+      end
+    end
+
+    # The Serdes-including class a (possibly optional/array-wrapped) attribute
+    # type deserializes into, or nil for scalar types.
+    def serdes_class(type)
+      case type
+      when Serdes::OptionalType then serdes_class(type.base_type)
+      when Serdes::ArrayType then serdes_class(type.element_type)
+      when Serdes::ConcreteType then serdes_class(type.exact_type)
+      when Class then type if type.include?(Serdes)
+      end
+    end
+  end
+end

data/lib/exwiw/table_column.rb

@@ -7,6 +7,11 @@ module Exwiw
     attribute :name, String
     attribute :replace_with, optional(String), skip_serializing_if_nil: true
     attribute :raw_sql, optional(String), skip_serializing_if_nil: true
+    # Ruby-process-side masking modes, applied to the fetched rows by
+    # RowTransformer (SQL adapters only) — unlike replace_with/raw_sql, which
+    # compile into the SELECT and run in the database.
+    attribute :map, optional(String), skip_serializing_if_nil: true
+    attribute :replace_with_fake_data, Serdes::OptionalType.new(FakeData), skip_serializing_if_nil: true
     # User-owned fields preserved across schema regeneration (see
     # TableConfig#merge). `ignore:true` drops the column from extraction (SELECT /
     # INSERT) once the config is loaded (see TableConfig#reject_ignored_members!).

data/lib/exwiw/table_config.rb

@@ -48,6 +48,15 @@ module Exwiw
     attribute :reverse_scope, Serdes::OptionalType.new(ReverseScope), skip_serializing_if_nil: true
 
     def self.from(hash)
+      # Reject unknown keys before deserializing: Serdes silently drops them,
+      # which would turn a typo'd or unsupported key into a silent no-op (see
+      # Exwiw::StrictKeys). `comment` is a declared attribute here and on the
+      # nested belongs_to/column entries, so free-form notes stay accepted.
+      if hash.is_a?(Hash)
+        table_name = hash["name"] || hash[:name]
+        StrictKeys.validate!(self, hash, owner: "table '#{table_name}'")
+      end
+
       config = super
       config.send(:validate_after_load!)
       config
@@ -219,6 +228,42 @@ module Exwiw
         if primary_key.nil? && !ignore
           raise ArgumentError, "Table '#{name}' requires primary_key."
         end
+
+        columns.each { |column| validate_ruby_side_masking!(column) }
+      end
+    end
+
+    # The Ruby-side masking modes (`map` / `replace_with_fake_data`) are strictly
+    # exclusive — with each other and with the SQL-side modes. Only the new keys
+    # are restricted: the legacy raw_sql > replace_with precedence stays lenient.
+    # Deliberately static (no faker require, no proc eval) so schema
+    # regeneration never executes config Ruby; the seed column and the map proc
+    # are resolved at dump time by RowTransformer.build.
+    private def validate_ruby_side_masking!(column)
+      ruby_side = [column.map && "map", column.replace_with_fake_data && "replace_with_fake_data"].compact
+      return if ruby_side.empty?
+
+      sql_side = [column.raw_sql && "raw_sql", column.replace_with && "replace_with"].compact
+      if ruby_side.size > 1 || sql_side.any?
+        raise ArgumentError,
+              "Table '#{name}' column '#{column.name}': #{(ruby_side + sql_side).join('/')} cannot be combined; " \
+              "use at most one of map/replace_with_fake_data, without raw_sql/replace_with."
+      end
+
+      fake_data = column.replace_with_fake_data
+      return unless fake_data
+
+      unless RowTransformer::FAKE_TYPES.key?(fake_data.type)
+        raise ArgumentError,
+              "Table '#{name}' column '#{column.name}': unknown replace_with_fake_data type '#{fake_data.type}' " \
+              "(supported: #{RowTransformer::FAKE_TYPES.keys.join(', ')})."
+      end
+
+      seed_column = fake_data.seed.delete_prefix("#{name}.")
+      if seed_column.include?(".") || columns.none? { |c| c.name == seed_column }
+        raise ArgumentError,
+              "Table '#{name}' column '#{column.name}': replace_with_fake_data seed '#{fake_data.seed}' " \
+              "does not name a column of this table (use 'column' or '#{name}.column')."
       end
     end
 

data/lib/exwiw/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Exwiw
-  VERSION = "0.9.6"
+  VERSION = "0.9.8"
 end

data/lib/exwiw.rb

@@ -7,7 +7,9 @@ require "serdes"
 
 require_relative "exwiw/ext_json"
 require_relative "exwiw/config_file"
+require_relative "exwiw/strict_keys"
 require_relative "exwiw/belongs_to"
+require_relative "exwiw/fake_data"
 require_relative "exwiw/table_column"
 require_relative "exwiw/reverse_scope"
 require_relative "exwiw/table_config"
@@ -28,6 +30,7 @@ require_relative "exwiw/mongodb_parallel_dumper"
 require_relative "exwiw/mongo_query"
 require_relative "exwiw/query_ast"
 require_relative "exwiw/query_ast_builder"
+require_relative "exwiw/row_transformer"
 require_relative "exwiw/after_insert_hook"
 require_relative "exwiw/runner"
 require_relative "exwiw/explain_runner"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exwiw
 version: !ruby/object:Gem::Version
-  version: 0.9.6
+  version: 0.9.8
 platform: ruby
 authors:
 - Shia
@@ -47,6 +47,7 @@ files:
 - docs/plans/2026-05-29-rails-managed-tables.md
 - docs/plans/2026-05-31-ids-column-for-sql-adapters.md
 - docs/plans/2026-06-19-mongodb-export-remove-parallelism-native-ext.md
+- docs/row-transform-masking-notes.md
 - docs/scope-column-redesign.md
 - docs/sql-dump-optimization-notes.md
 - exe/exwiw
@@ -69,6 +70,7 @@ files:
 - lib/exwiw/embedded_in.rb
 - lib/exwiw/explain_runner.rb
 - lib/exwiw/ext_json.rb
+- lib/exwiw/fake_data.rb
 - lib/exwiw/mongo_query.rb
 - lib/exwiw/mongodb_collection_config.rb
 - lib/exwiw/mongodb_field.rb
@@ -79,8 +81,10 @@ files:
 - lib/exwiw/query_ast_builder.rb
 - lib/exwiw/railtie.rb
 - lib/exwiw/reverse_scope.rb
+- lib/exwiw/row_transformer.rb
 - lib/exwiw/runner.rb
 - lib/exwiw/schema_generator.rb
+- lib/exwiw/strict_keys.rb
 - lib/exwiw/table_column.rb
 - lib/exwiw/table_config.rb
 - lib/exwiw/version.rb