exwiw 1.1.1 → 1.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be2a5e77df07b1f463bb898d1ae06fd98bf1744d5e9cd82951bb37ba080ed379
-  data.tar.gz: dfb735937b5afb901a314fc72349e6093df0796b166e1d9b4a7212de0a2654e7
+  metadata.gz: 0014e16bc315ba2aee359cdf8aeebc71edb91da1ae2a6dc1792d4da55f81593f
+  data.tar.gz: bec818638046dc447be1624043639240743bda93bd25607fc3977475cfc4c68c
 SHA512:
-  metadata.gz: 9736dc30f83eb07744acc42413f2b2f697c19267bcbd40a355166e78e8fae7fdd42c66f057d5583297dc21f7c9ac6a2dd84814f1cfd819208dadad97e5b3afda
-  data.tar.gz: bf9797812840921845668d489015f05d017418e298075bde89fdc98c1d32f322520f8194a6b4f989a47fc65a5d0955ffd941fc51c20270745a391a18361e26b7
+  metadata.gz: 773b59703dd74b61cb4da1665f73492fe6c35b906134d26cb406ce174e5919859a5e4c6418a660dfb8f3972a75fc908da4bac77606c39474c11e015edc180638
+  data.tar.gz: 366f12162f6ddace018a027efbaa9a2563023dc51d4e26da20cebab8d988671419d4a3055f13dbe7b2d384030279443865b4e239d0d19fd903dba28ea4b8632a

data/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [1.1.2] - 2026-09-07
+
+### Added
+
+- **`reverse_scope.column` matches the arm union against a column other than the primary key.** A table referenced by a shared code rather than by its id (`rate_cards.code <- contracts.rate_code`) could not be reverse-scoped, because the generated clause was always `<table>.<primary_key> IN (…)`. The new optional key names the column on the reverse-scoped table to compare with; unset, the primary key is used as before. Both the SQL adapters and the MongoDB runtime filter honor it, and a `column` that is not declared on the table/collection is rejected on load.
+
 ## [1.1.1] - 2026-09-07
 
 ### Fixed

data/README.md

@@ -882,6 +882,7 @@ Notes:
 - **Only scoped referencers belong in `via`.** Each arm's query must come out constrained; an unconstrained referencer (e.g. a `scope_exempt` table, or one with no path to a scope) would project *every* id and union the whole table back — so such an arm is **skipped with a warning** rather than silently widening the dump. An unknown table is likewise skipped with a warning. If no arm survives, the table stays unscopable and (in [scope-column mode](#scope-column-mode)) the run aborts via `validate_scope!`.
 - **Declarations chain.** A referencer that is itself scoped only by its *own* `reverse_scope` counts as scoped: the arm nests that declaration's `UNION` inside its query, so a normalized side table referenced by a document-style hub that is in turn reverse-scoped through a join table resolves end to end (`attachments <- documents <- join rows <- the target`). A cycle of declarations is cut — the repeated table's arm comes out unconstrained and is dropped with the warning above. The chaining is deliberately limited to `reverse_scope` arms: the *automatic* single-referencer detection still treats a child scoped solely by its own declaration as unconstrained, so such a child never rescues (or, by widening the candidate set past one, costs) a parent that relies on the automatic detection — declare `reverse_scope` on the parent if you need that shape. Chains deeper than three declarations are flagged with a warning, since each level re-embeds its referencers' subqueries and the generated SQL grows exponentially with depth.
 - **NULLs are excluded** per arm (`IS NOT NULL`).
+- **`column` picks the key the union is matched against.** By default the arms' projected values are compared with this table's `primary_key`. When the referencers point at another key of the table — say `rate_cards` are looked up by a `code` that `contracts.rate_code` carries, not by `rate_cards.id` — set `"reverse_scope": { "column": "code", "via": [{ "table": "contracts", "column": "rate_code" }] }` and the clause becomes `ON rate_cards.code = …`. The column must be declared in `columns`.
 - **Satellites need no config.** A table that `belongs_to` the reverse-scoped table (e.g. `end_users.id → users.id`, or `identities.user_id → users.id`) tightens to the kept ids automatically through the normal cascade — only the reverse-scoped table itself declares `reverse_scope`. The cascade is **multi-hop**, so a table several `belongs_to` hops below the reverse-scoped table (e.g. `end_user_profiles → end_users → users`) also tightens automatically, with no config of its own.
 - Works in both single-target and scope-column mode. In single-target mode there is no scope-column pre-flight (`validate_scope!`), so a satellite the cascade cannot resolve to a single scopable parent (e.g. it `belongs_to` two scopable hubs) is dumped in full with a warning rather than aborting. Polymorphic foreign keys are not eligible as anchors (the named `column` is always a concrete column).
 - **The MongoDB adapter supports `reverse_scope` too** — same config shape and semantics, but the id set is captured at runtime instead of being emitted as a `UNION` subquery. See [`reverse_scope` on collections](docs/mongodb.md#reverse_scope-on-collections) under MongoDB support.

data/docs/mongodb.md

@@ -63,6 +63,7 @@ Where the SQL adapters emit a `UNION` subquery, MongoDB has no cross-collection
 
 - **Processing order**: a reverse-scoped collection is dumped **after** all of its `via` referencers (an arm's own `belongs_to` back to the reverse-scoped collection is inverted rather than kept — the declaration states ids flow referencer → collection). If the arms form a genuine ordering cycle with the `belongs_to` graph, the export aborts with an error naming the cycle members. SQL processing order is unchanged (its INSERT output must stay loadable in foreign-key order).
 - **Arm hygiene mirrors SQL**: an arm whose referencer is unknown, embedded, not dumped, or itself unscoped (no path to the dump target and no `reverse_scope` of its own) is **skipped with a warning** — an unscoped referencer's ids span every scope and would silently widen the dump. Per-arm `null`/absent foreign keys are dropped (the SQL `IS NOT NULL`), an array-valued foreign-key column contributes one id per element, and captured values keep their native BSON types (an `ObjectId` foreign key matches an `ObjectId` `_id` with no coercion).
+- **`reverse_scope.column`** works as in SQL: when set, the captured ids are matched against that field (`{"<column>": {"$in": [...]}}`) instead of `primary_key`. It must be a declared field.
 - **Precedence mirrors SQL**: a collection with its own `belongs_to` path to the dump target is scoped by that path; a `reverse_scope` declared on it is ignored.
 - **Satellites need no config**, as in SQL: a collection that `belongs_to` the reverse-scoped collection tightens to the kept ids automatically through the ordinary captured-parent-id mechanism.
 - **`--parallel-workers` falls back to serial** (with a warning) when any collection declares `reverse_scope` — the parallel schedule does not express the referencers-first ordering constraint yet.

data/lib/exwiw/adapter/mongodb_adapter.rb

@@ -637,7 +637,7 @@ module Exwiw
         ids = ids.flat_map { |value| value.is_a?(Array) ? value : [value] }
         ids.compact!
         ids.uniq!
-        { config.primary_key => { "$in" => ids } }
+        { config.reverse_scope.key_for(config.primary_key) => { "$in" => ids } }
       end
 
       # The set of collection names *genuinely scoped* by the dump target: the

data/lib/exwiw/mongodb_collection_config.rb

@@ -68,6 +68,7 @@ module Exwiw
       instance.__send__(:validate_belongs_tos!)
       instance.__send__(:validate_fake_data!)
       instance.__send__(:validate_ignored_fields!)
+      instance.__send__(:validate_reverse_scope_column!)
       instance
     end
 
@@ -222,6 +223,14 @@ module Exwiw
             "or use ignore: true on the collection to exclude it entirely)."
     end
 
+    private def validate_reverse_scope_column!
+      column = reverse_scope&.column
+      return if column.nil? || ignore || column == primary_key || fields.any? { |f| f.name == column }
+
+      raise ArgumentError,
+            "MongodbCollectionConfig '#{name}': reverse_scope.column '#{column}' is not a declared field."
+    end
+
     private def validate_embedded!
       return unless embedded?
 

data/lib/exwiw/query_ast_builder.rb

@@ -400,7 +400,7 @@ module Exwiw
       return nil if arms.empty?
 
       QueryAst::WhereClause.new(
-        column_name: table.primary_key,
+        column_name: table.reverse_scope.key_for(table.primary_key),
         operator: :in_subquery,
         value: QueryAst::UnionSubquery.new(queries: arms)
       )

data/lib/exwiw/reverse_scope.rb

@@ -2,7 +2,8 @@
 
 module Exwiw
   # One referencer arm of a {ReverseScope}: the referencing table and the column
-  # on it that points at the reverse-scoped table's primary key.
+  # on it that points at the reverse-scoped table's key (its primary key, or the
+  # column named by {ReverseScope#column}).
   #
   # `column` is given explicitly so a *non-default* foreign key (e.g.
   # `business_entity_customers.kantan_yoyaku_user_id`, or `organization_admins.id`
@@ -27,7 +28,7 @@ module Exwiw
   # extraction queries should be UNION'd into the id set this table is
   # constrained to:
   #
-  #   <table>.<pk> IN (
+  #   <table>.<column or pk> IN (
   #     SELECT <ref1>.<col1> FROM <ref1> <ref1 scope> WHERE <col1> IS NOT NULL
   #     UNION SELECT <ref2>.<col2> FROM <ref2> <ref2 scope> WHERE <col2> IS NOT NULL
   #     UNION ...
@@ -42,6 +43,11 @@ module Exwiw
   class ReverseScope
     include Serdes
 
+    attribute :column, optional(String), skip_serializing_if_nil: true
     attribute :via, array(ReverseScopeVia), default: []
+
+    def key_for(primary_key)
+      column || primary_key
+    end
   end
 end

data/lib/exwiw/table_config.rb

@@ -245,6 +245,11 @@ module Exwiw
                 "(got #{batch_scope.size})."
         end
 
+        if reverse_scope&.column && !ignore && reverse_scope.column != primary_key && columns.none? { |c| c.name == reverse_scope.column }
+          raise ArgumentError,
+                "Table '#{name}': reverse_scope.column '#{reverse_scope.column}' is not a declared column."
+        end
+
         columns.each { |column| validate_ruby_side_masking!(column) }
       end
     end

data/lib/exwiw/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exwiw
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.1.2
 platform: ruby
 authors:
 - Shia