exwiw 0.9.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 171e3c591c208afcb89c2a9330c2c80d67f8f86ab370858b4690d03c799d28bc
-  data.tar.gz: f913a31f6f8e2a29a9e4b2a296926c1266c17cc8655fd4cf33110899f2b468fd
+  metadata.gz: 577420a290ea24adc64ef6ba21914ac71b1c98f86163f9d1d8a88643cc89e15b
+  data.tar.gz: eaddb0073169543aa1bea944cb1b075fbd8258a034f4cffb9cf0011338ba260a
 SHA512:
-  metadata.gz: a8d6e99e0881f4cdaa8d6d737cfbd0107382a6585f119df7d3068007ebb768a976b47fd59f78fb2d931ed95147c707523b3c8e5d1e9af0507584de93796e1ec1
-  data.tar.gz: f1cbada5c1adb8892cc297a5e864051da3bdc0b7447cbe1c386b32dde4020cbf1ac6be94935d7bb547c2ec7f4482ebf79b3e1df796bb526db7fd7d5fb42ce662
+  metadata.gz: c21735b0dcda7b30b0519944c37f24610564e91801a29e2c0f7cc3632cc0f24c532d10c078127bccffd0a2f258a5695cdabe25094edf228b5e3203a629ddf175
+  data.tar.gz: 7e9ce9682b281c097485da409befc466dd06fc655c1612278b9e98f6bccdea575aa443ff4292777be1e4e68f88d826554702eecd6b94bddc31b1e4edc01c923b

data/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [0.9.1] - 2026-06-30
+
+### Fixed
+
+- **The `reverse_scope` satellite cascade now fires in single-target (`--target-table`) mode, not only scope-column mode.** A table that `belongs_to` a `reverse_scope`'d hub (a "satellite") is scoped by constraining it to the hub's in-scope ids — the multi-hop forward (`via_scoped_parent`) cascade. That cascade ran only in scope-column mode: in single-target / PK-anchor mode the hub itself was scoped via `reverse_scope`, but its `belongs_to` children fell through to a full dump — a silent cross-tenant export in a multi-tenant schema, despite the README promising the cascade works in "both single-target and scope-column mode." The single-target build now runs the same `build_belongs_to_scoped_clause` cascade for a non-target table that has no `belongs_to` path to the dump target, so satellites tighten to the kept ids (multi-hop, keeping the single-unambiguous-parent rule, polymorphic skip, and forward-path cycle guard); it can only narrow such a table's output, never widen it. Scope-column mode is unchanged — the cascade logic is reused as-is. Because single-target mode has no `validate_scope!` pre-flight, a satellite the cascade cannot resolve to a single scopable parent (e.g. it `belongs_to` two scopable hubs) is still dumped in full but now logs a warning. The README also documents that `referenced_by` scoping takes precedence over the hub cascade (which can under-scope) and how to force the hub cascade. SQL adapters only.
+
 ## [0.9.0] - 2026-06-30
 
 ### Added

data/README.md

@@ -220,6 +220,13 @@ Each table is resolved as follows:
   path, set `ignore: true` to skip it, or mark it `scope_exempt: true` (below) to
   export it in full.
 
+> **Note — referenced-by is preferred over the hub cascade.** A table that is
+> *both* `belongs_to` a scoped hub *and* referenced-by a constrained child is
+> scoped to the (narrower) referenced-by id-set, not the hub cascade, so the hub's
+> other children the child does not reference are dropped (under-scoping). To force
+> the broader hub cascade, set `ignore: true` on the child's `belongs_to` edge that
+> points at this table.
+
 Scope-column mode is SQL-only (mysql / postgresql / sqlite). It works with `exwiw
 explain` too, which is the recommended way to preview the queries before exporting.
 
@@ -658,7 +665,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!`.
 - **NULLs are excluded** per arm (`IS NOT NULL`).
 - **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. Polymorphic foreign keys are not eligible as anchors (the named `column` is always a concrete column).
+- 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).
 
 ### Why a JOIN, not `IN (subquery)`
 

data/lib/exwiw/query_ast_builder.rb

@@ -86,6 +86,28 @@ module Exwiw
         where_clauses.push(reverse_clause) if reverse_clause
       end
 
+      # Forward cascade. A satellite of a reverse_scope'd (or referenced-by-scoped)
+      # hub has no belongs_to path to the dump target, so the clauses above stay
+      # empty and it would dump every row. When its belongs_to parent is itself
+      # scoped, constrain this table to the parent's in-scope ids — the same
+      # multi-hop cascade scope-column mode performs in build_scoped.
+      if table.name != dump_target.table_name &&
+         where_clauses.empty? && join_clauses.empty? &&
+         forward_scope_allowed?(table)
+        parent_clause = build_belongs_to_scoped_clause(table)
+        if parent_clause
+          where_clauses.push(parent_clause)
+        elsif @allow_reverse && @forward_path.empty? && !scope_exempt?(table) &&
+              scopable_parent_candidates(table).size > 1
+          @logger.warn(
+            "  #{table.name} belongs_to multiple scopable parents; the cascade cannot " \
+            "pick one unambiguously, so it is dumped in full. If this is intended, set " \
+            "`scope_exempt: true`. Otherwise, scope it through a single parent (e.g. ignore one belongs_to edge), " \
+            "or switch to scope-column mode to scope it directly."
+          )
+        end
+      end
+
       QueryAst::Select.new.tap do |ast|
         ast.from(table.name)
         if table.rails_managed?
@@ -290,48 +312,18 @@ module Exwiw
       )
     end
 
-    # Scope-column mode. Builds a `fk IN (SELECT parent.pk FROM <parent
-    # extraction query>)` clause for a table whose belongs_to parent is itself
-    # scopable but carries no scope column of its own — so find_path_to_scoped
-    # cannot terminate on it (via_path fails) and nothing references this table
-    # (referenced_by fails). The classic shape is a hub scoped only via
-    # referenced_by (e.g. CDP `customer_accounts`, scoped by the `customers` that
-    # reference it) with sibling detail tables (`customer_account_details`, ...)
-    # hanging off it. Constraining those siblings to the hub's in-scope ids keeps
-    # them out of a full dump. Returns nil when there is no single, unambiguous
-    # scopable parent, leaving the caller on the unscopable path.
+    # Builds a `fk IN (SELECT parent.pk FROM <parent extraction query>)` clause
+    # for a table whose belongs_to parent is itself scopable but carries no scope
+    # column of its own — so find_path_to_scoped cannot terminate on it (via_path
+    # fails) and nothing references this table (referenced_by fails). The classic
+    # shape is a hub scoped only via referenced_by (e.g. CDP `customer_accounts`,
+    # scoped by the `customers` that reference it) with sibling detail tables
+    # (`customer_account_details`, ...) hanging off it. Constraining those
+    # siblings to the hub's in-scope ids keeps them out of a full dump. Returns
+    # nil when there is no single, unambiguous scopable parent, leaving the caller
+    # on the unscopable path. Used by both scope-column and single-target mode.
     private def build_belongs_to_scoped_clause(table)
-      # This table plus every ancestor currently being forward-resolved. A
-      # candidate parent already on this path would close a belongs_to cycle, so
-      # it is skipped; threading the grown path into the parent build lets the
-      # cascade recurse N hops (users -> end_users -> end_user_profiles -> ...)
-      # and terminate only when a table reappears.
-      forward_path = @forward_path + [table.name]
-
-      candidates = table.belongs_tos.filter_map do |relation|
-        # A polymorphic belongs_to points at several parent tables through one
-        # column, so it cannot project to a single parent id set; skip it.
-        next if relation.polymorphic?
-
-        parent = table_by_name[relation.table_name]
-        next if parent.nil?
-
-        # Cycle guard: descending into a parent already on the forward path would
-        # loop (a -> b -> a). Stop, leaving this table on the :unscopable path.
-        next if forward_path.include?(parent.name)
-
-        # Build the parent's own scoped query. allow_reverse stays true so the
-        # parent may be scoped via referenced_by, and forward scoping stays
-        # enabled so a parent that is itself scoped via *its* parent resolves
-        # too — this is what makes the cascade multi-hop.
-        parent_query = self.class.run(parent.name, table_by_name, dump_target, @logger, allow_reverse: true, forward_path: forward_path)
-
-        # Only a constrained parent narrows anything; an unconstrained parent
-        # would select every pk (i.e. dump all) and not help.
-        next unless parent_query.where_clauses.any? || parent_query.join_clauses.any?
-
-        [relation, parent, parent_query]
-      end
+      candidates = scopable_parent_candidates(table)
 
       # Only the unambiguous single-parent case. Multiple scopable parents would
       # need their subqueries combined (not supported); fall back to unscopable.
@@ -360,6 +352,45 @@ module Exwiw
       )
     end
 
+    # The scopable belongs_to parents of `table`: each non-polymorphic parent
+    # whose own extraction query comes out constrained, paired with the relation
+    # and that query. Shared by build_belongs_to_scoped_clause (which requires
+    # exactly one) and the single-target full-dump warning (which flags two or
+    # more, since the cascade then cannot disambiguate).
+    private def scopable_parent_candidates(table)
+      # Memoized: #run can resolve this twice for the same table (once via
+      # build_belongs_to_scoped_clause, once for the ambiguous-parent warning),
+      # and each pass recursively builds every parent's query.
+      (@scopable_parent_candidates ||= {})[table.name] ||= begin
+        # This table plus every ancestor currently being forward-resolved; a
+        # candidate parent already on this path would close a belongs_to cycle, so
+        # it is skipped. Threading the grown path into the parent build lets the
+        # cascade recurse N hops and terminate only when a table reappears.
+        forward_path = @forward_path + [table.name]
+
+        table.belongs_tos.filter_map do |relation|
+          # A polymorphic belongs_to points at several parent tables through one
+          # column, so it cannot project to a single parent id set.
+          next if relation.polymorphic?
+
+          parent = table_by_name[relation.table_name]
+          next if parent.nil?
+          next if forward_path.include?(parent.name)
+
+          # allow_reverse and forward scoping stay enabled so the parent may itself
+          # be scoped via referenced_by or via *its* parent — this is what makes the
+          # cascade multi-hop.
+          parent_query = self.class.run(parent.name, table_by_name, dump_target, @logger, allow_reverse: true, forward_path: forward_path)
+
+          # Only a constrained parent narrows anything; an unconstrained parent
+          # would select every pk (i.e. dump all) and not help.
+          next unless parent_query.where_clauses.any? || parent_query.join_clauses.any?
+
+          [relation, parent, parent_query]
+        end
+      end
+    end
+
     private def build_where_clauses(table, dump_target)
       clauses = []
 

data/lib/exwiw/version.rb

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

metadata

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