exwiw 0.8.2 → 0.8.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb6879b8efb94ef9a9a0bd37df32962257106df9eec4c3fc9de844a12c6360cd
-  data.tar.gz: b43b0bfde090111d7ce23083db7471f15974292ddb5886da682de9bc443febfa
+  metadata.gz: 90d949cb54565ed644b599102cfabc16236fe2d83523594cd7b14f269118a9b2
+  data.tar.gz: 7236bb6ee6b9dda38aec93491f0266e334890e3c271b4f7d5d072d46a1e0f88b
 SHA512:
-  metadata.gz: e8cca59b376a369b9253d1482f3ee64ae8c542b00c1c3eddb192d273efe0e3c969e3aec1770f087977efe6b75fa52f375538e286d31a87d7f87a197739a4eeaf
-  data.tar.gz: 78a3ece09cd6ec9ecb6fd7b0a2f166bc41d51720ea36935ca4cd974bf766008f11688f0e0dc7bbd8a63ce29f4719806e1a4705b0390850a857a192fcfaa56976
+  metadata.gz: bcfac0aaf220b55dfa3172f94d2ad0a6e828f53253e367aa9203db7061695fa6a9188e22a92c18d51bd9a55b6a9bf840cf780a3647d4aca2a0cccff1a785a347
+  data.tar.gz: d891fc7101fea30d674b933213715a8a4534c459e191b9bf4fce31b3bda8a9be037bf09627419f43ef914d2a9288aa40e1cd4836a4d8e1e0901d73e320218cd3

data/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [0.8.3] - 2026-06-24
+
+### Fixed
+
+- **Forward scope (`via_scoped_parent`) now cascades across multiple `belongs_to` hops instead of dying after one.** A table with no scope column of its own is scoped by constraining it to its `belongs_to` parent's in-scope ids (`fk IN (SELECT parent.pk FROM <parent's scoped query>)`). Previously the parent was rebuilt with forward scoping turned off, so if the parent was *itself* scoped only through *its* parent (e.g. an identity-family table two or more hops below a `reverse_scope`/`referenced_by` table — `users ← end_users ← end_user_profiles`), the rebuilt parent came back unconstrained and the child was classified `:unscopable` — forcing a `scope_exempt` full dump and re-introducing the bloat the prune removes. The boolean single-hop bound is replaced by a forward-path guard: the rescue keeps forward scoping enabled while rebuilding the parent (appending the current table to the path), so the cascade recurses N levels and produces a correspondingly nested `IN (subquery)`; it terminates only on a genuine `belongs_to` cycle (a table already on the path is not revisited, falling through to `:unscopable`). The single-unambiguous-parent rule and the polymorphic-skip are unchanged, and the reverse arms still cannot loop back through the table being reverse-scoped. SQL adapters only.
+
 ## [0.8.2] - 2026-06-24
 
 ### Added

data/README.md

@@ -183,8 +183,11 @@ Each table is resolved as follows:
   (`fk IN (SELECT parent.pk FROM <parent's scoped query>)`). This covers a *hub*
   table that has no scope column and is scoped only because an extractable child
   references it (see referenced-by below): the hub's other `belongs_to` children
-  ride along to just the in-scope rows instead of being dumped in full. Limited to
-  a single forward hop and a single unambiguous scopable parent.
+  ride along to just the in-scope rows instead of being dumped in full. The parent
+  itself may be scoped the same way, so this **cascades across multiple hops**
+  (each a single unambiguous scopable parent) and the subquery nests
+  correspondingly; the recursion terminates on a genuine `belongs_to` cycle (a
+  table already on the path is left `:unscopable` rather than looped on).
 - **Cannot be scoped at all** (no scope column and no path to one) → exwiw
   **aborts** and lists the offending tables, so an unscoped table is never silently
   dumped in full. For each, either declare a `scope_column`, add a `belongs_to`
@@ -619,7 +622,7 @@ Notes:
 - **`column` is explicit**, so a *non-default* foreign key (e.g. `kantan_yoyaku_user_id`, or `organization_admins.id` which itself references `users.id`) is honored, and even a column with no declared `belongs_to` edge can be enumerated.
 - **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`.
+- **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).
 
 ### Rails-managed tables (special `type` values)

data/lib/exwiw/query_ast_builder.rb

@@ -2,8 +2,8 @@
 
 module Exwiw
   class QueryAstBuilder
-    def self.run(table_name, table_by_name, dump_target, logger, allow_reverse: true, allow_forward: true)
-      new(table_name, table_by_name, dump_target, logger, allow_reverse: allow_reverse, allow_forward: allow_forward).run
+    def self.run(table_name, table_by_name, dump_target, logger, allow_reverse: true, forward_path: [])
+      new(table_name, table_by_name, dump_target, logger, allow_reverse: allow_reverse, forward_path: forward_path).run
     end
 
     # Scope-column mode classification for a single table. One of
@@ -49,17 +49,20 @@ module Exwiw
 
     attr_reader :table_name, :table_by_name, :dump_target
 
-    def initialize(table_name, table_by_name, dump_target, logger, allow_reverse: true, allow_forward: true)
+    def initialize(table_name, table_by_name, dump_target, logger, allow_reverse: true, forward_path: [])
       @table_name = table_name
       @table_by_name = table_by_name
       @dump_target = dump_target
       @logger = logger
       @allow_reverse = allow_reverse
-      # @allow_forward gates the "scope via an indirectly-scoped belongs_to
-      # parent" rescue (build_belongs_to_scoped_clause). Disabled while building a
-      # parent/child subquery so a single forward hop never recurses into another
-      # (which could loop on a belongs_to cycle).
-      @allow_forward = allow_forward
+      # @forward_path is the chain of tables currently being forward-resolved by
+      # the "scope via an indirectly-scoped belongs_to parent" rescue
+      # (build_belongs_to_scoped_clause). Each forward hop appends the table it is
+      # descending from, so the rescue recurses N levels (users -> end_users ->
+      # end_user_profiles -> ...) and stops only on a real belongs_to cycle: a
+      # table already on the path is not re-resolved, falling through to
+      # :unscopable instead of looping forever.
+      @forward_path = forward_path
     end
 
     def run
@@ -187,10 +190,11 @@ module Exwiw
         next if relation.nil? || relation.polymorphic?
 
         # Build the child's own extraction query. allow_reverse:false stops a
-        # chain of FK-less tables from recursing back into each other;
-        # allow_forward:false stops the child from forward-scoping back through
-        # this very table (which would loop).
-        child_query = self.class.run(other.name, table_by_name, dump_target, @logger, allow_reverse: false, allow_forward: false)
+        # chain of FK-less tables from recursing back into each other; adding this
+        # table to forward_path stops the child from forward-scoping back through
+        # it (which would loop) while still letting the child forward-scope
+        # through other tables.
+        child_query = self.class.run(other.name, table_by_name, dump_target, @logger, allow_reverse: false, forward_path: @forward_path + [table.name])
 
         # Only an *already constrained* child narrows anything; an unconstrained
         # child would select every fk value (i.e. dump all) and not help.
@@ -248,12 +252,12 @@ module Exwiw
           next
         end
 
-        # Build the referencer's own scoped extraction query. allow_reverse /
-        # allow_forward are disabled to bound recursion exactly as the
-        # single-referencer path does (a referencer scopable only via its own
-        # reverse/forward rescue would loop or, worse, recurse back into this
-        # table).
-        ref_query = self.class.run(referencer.name, table_by_name, dump_target, @logger, allow_reverse: false, allow_forward: false)
+        # Build the referencer's own scoped extraction query. allow_reverse is
+        # disabled and this table is added to forward_path to bound recursion
+        # exactly as the single-referencer path does (a referencer that could only
+        # be scoped by recursing back into this table would loop); the referencer
+        # may still forward-scope through other tables.
+        ref_query = self.class.run(referencer.name, table_by_name, dump_target, @logger, allow_reverse: false, forward_path: @forward_path + [table.name])
 
         unless ref_query.where_clauses.any? || ref_query.join_clauses.any?
           @logger.warn(
@@ -297,6 +301,13 @@ module Exwiw
     # them out of a full dump. Returns nil when there is no single, unambiguous
     # scopable parent, leaving the caller on the unscopable path.
     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.
@@ -305,10 +316,15 @@ module Exwiw
         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; allow_forward:false bounds this
-        # to a single forward hop so a belongs_to cycle cannot loop.
-        parent_query = self.class.run(parent.name, table_by_name, dump_target, @logger, allow_reverse: true, allow_forward: false)
+        # 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.
@@ -460,11 +476,18 @@ module Exwiw
       return :direct if directly_scoped?(table)
       return :via_path if build_join_clauses_scoped(table).any?
       return :referenced_by if @allow_reverse && build_referenced_by_clause(table)
-      return :via_scoped_parent if @allow_forward && build_belongs_to_scoped_clause(table)
+      return :via_scoped_parent if forward_scope_allowed?(table) && build_belongs_to_scoped_clause(table)
 
       :unscopable
     end
 
+    # True when this table may still attempt the forward "scope via a scoped
+    # belongs_to parent" rescue: it is not already on the forward-resolution
+    # path, so descending into its parent cannot revisit it (a belongs_to cycle).
+    private def forward_scope_allowed?(table)
+      !@forward_path.include?(table.name)
+    end
+
     private def build_scoped(table)
       ast = QueryAst::Select.new
       ast.from(table.name)
@@ -502,11 +525,13 @@ module Exwiw
         end
       end
 
-      if @allow_forward
+      if forward_scope_allowed?(table)
         # Belongs_to a parent that is itself scoped but carries no scope column of
         # its own (so via_path cannot terminate on it) — e.g. a hub table scoped
-        # only via referenced_by. Constrain this table to that parent's in-scope
-        # ids so its rows ride along instead of being dumped in full.
+        # only via referenced_by, or a parent that is itself scoped through *its*
+        # parent. Constrain this table to that parent's in-scope ids so its rows
+        # ride along instead of being dumped in full; the parent build recurses
+        # the cascade further up.
         parent_clause = build_belongs_to_scoped_clause(table)
         if parent_clause
           ast.where(parent_clause)
@@ -514,12 +539,13 @@ module Exwiw
         end
       end
 
-      # Only the genuine top-level build (no rescue disabled) is allowed to fail
-      # hard. The Runner/ExplainRunner pre-flight (validate_scope!) rejects
-      # unscopable tables before extraction, so a top-level build never
-      # legitimately lands here; if it does, raise rather than emit an unfiltered
-      # (potential full PII) dump.
-      if @allow_reverse && @allow_forward
+      # Only the genuine top-level build (allow_reverse on, forward_path empty —
+      # i.e. no rescue subquery in progress) is allowed to fail hard. The
+      # Runner/ExplainRunner pre-flight (validate_scope!) rejects unscopable
+      # tables before extraction, so a top-level build never legitimately lands
+      # here; if it does, raise rather than emit an unfiltered (potential full
+      # PII) dump.
+      if @allow_reverse && @forward_path.empty?
         raise ArgumentError, scope_unscopable_message(table)
       end
 

data/lib/exwiw/version.rb

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

metadata

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