exwiw 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ecbb0b978dfd64c1e48c396e600662a9f7d4bb9c2c8f0e0050440987b53c815d
-  data.tar.gz: eff38c81ce04abb165f0edcad7316e1820d44abd54c6596ce450357c11a9c201
+  metadata.gz: e0b25a06efa96c6a7cfcc0e19187a735e7d83f317dc41f585af904e665a0ff46
+  data.tar.gz: b646c7949e2425e0155a0e70cd93eb4190506d97f9ecca790e77f7a9f9d469ed
 SHA512:
-  metadata.gz: 2b119cb478ae9e6bb019bb2d0d94272ed84f7bb20ac3013236260b8c98433c9c97f37b3d4dafc132a70736d0d6eb4a20e4fc0e44e473dfc5d1a91f7dbda560a0
-  data.tar.gz: 17268aa8ec3ad2959521cc4b16d453e86480935ae98ba43e4f38fb4545dada3af23980fc79b8f3751268fa79e078e87c7e7388e8bab7ce9fefbef9e6344c9453
+  metadata.gz: d6b42bb54f5bc27345d69c4d634f70f964be04b67845c8b64a791fa8659eb04cbdb92fe13ce86ebb8dec717ef8caa8b9cbfb33d5de5e55769010363f8f4c2bdf
+  data.tar.gz: 3f6f4bc0637983318900442495f2b5dd9a29d3d147064494d22216e6a3ee284b4ff5af5b882e51b5bcc1c4e3655c39664a7caf7ae010105818b46644e1a278c8

data/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-09-07
+
+### Added
+
+- **`exwiw schema check --from-db --fail-on=stale` keys the exit code to the drift that would break an export, so the check can run as a pre-extraction gate ([#223](https://github.com/heyinc/exwiw/pull/223)).** The report gains two categories, `stale_tables` and `stale_columns`: a non-ignored config still naming a table or column the schema no longer has — the extraction SELECT would name something that does not exist. Additions (a new table or column the config has not adopted yet) and unresolved `needs_mask_decision` flags stay in the report but no longer drive the exit code under `--fail-on=stale`, because for a gate that runs before every extraction they are someone's TODO rather than a reason to stop the run; `--fail-on=any` (the default) keeps today's behavior exactly, and the new report keys are additive, so existing consumers of the JSON are unaffected. Removals on an `ignore: true` table or of an `ignore: true` column are not stale — nothing selects them; a removed rails-managed table IS stale (it is dumped whole), though its columns can never be (the dump is `SELECT *`) — a case only the rake tasks' reports can produce today, since the `--from-db` generator never emits rails-managed configs. When staleness is what fails the check, the CLI names the stale tables/columns on stderr instead of the generic "resolve every `needs_mask_decision` column" advice.
+
+- **`reverse_scope` declarations now chain: an arm whose referencer is itself scoped only by its own `reverse_scope` resolves instead of being dropped ([#224](https://github.com/heyinc/exwiw/pull/224)).** Previously the arm's referencer query was built with reverse extraction disabled entirely, so a referencer with no `belongs_to` path of its own came out unconstrained and the arm was skipped — and in single `--target-table` mode the table then fell back to a **full dump** (scope-column mode rejected it in pre-flight). Each skipped arm did warn, but nothing stated that consequence, which is what the new outcome warning below now does. Declared chains — `attachments <- documents <- join rows <- the target` — now nest: each arm resolves the referencer's own declared `reverse_scope`. The nesting applies **only inside reverse_scope arm builds**: the automatic single-referencer detection still builds its candidate children without it, so which tables that detection scopes is unchanged (a widened candidate set could flip its single-candidate requirement and cost a table the scope it had). A cycle of declarations is cut (the repeated table's arm comes out unconstrained and is dropped with the existing warning) rather than recursing forever, and a chain more than three declarations deep is flagged with a warning — every level re-embeds its referencers' subqueries, so generated SQL grows exponentially with depth. MongoDB's runtime reverse scoping is unchanged.
+
+### Changed
+
+- **A table left unscoped because several constrained tables reference it is now flagged at `warn`, not `debug`.** In single `--target-table` mode that outcome is a full dump of the table, and the only signal used to be a debug line; the warning names the referencers and suggests declaring `reverse_scope` to union their ids. In scope-column mode the pre-flight abort message changed shape for the same situation: the affected table's entry now names the referencers with the same `reverse_scope` suggestion, per table, instead of a generic clause in the message tail.
+
+### Fixed
+
+- **MySQL: sibling `UNION` arms sharing a nested scope id-set no longer fail id-set materialization.** Each arm of a union id-set (several foreign keys of one referencer, or polymorphic arms probing the same ancestor) could embed the same materialized id-set, and MySQL cannot reference one `TEMPORARY` table twice in a single statement (`ER_CANT_REOPEN_TABLE`); the failed `CREATE` then disabled materialization for the rest of the run. Nested scopes inside union arms now compile as inline derived tables, so the outer id-set materializes once and the temp table appears once per statement.
+
 ## [1.0.0] - 2026-09-01
 
 ### Removed

data/README.md

@@ -60,7 +60,7 @@ exwiw has three subcommands:
 
 - `export` (default) — generate INSERT/COPY SQL files. If the subcommand is omitted, `export` is assumed.
 - `explain` — print each query `export` would run together with its `EXPLAIN` output. SQL adapters compile the SELECT without executing it; mongodb runs the server's explain (defaulting to the execution-free `queryPlanner`).
-- `schema generate|check|tidy --from-db` — maintain the schema config by reading a live database, for applications that cannot be loaded to generate it from their models. See [Non-Rails applications](#non-rails-applications-exwiw-schema---from-db).
+- `schema generate|check|tidy --from-db` — maintain the schema config by reading a live database, for applications that cannot be loaded to generate it from their models. See [Non-Rails applications](#non-rails-applications-exwiw-schema----from-db).
 
 ### `exwiw export`
 
@@ -442,15 +442,22 @@ the comparison as JSON, then exits non-zero when anything needs attention:
   "added_tables": [],
   "added_columns": ["users.contact_email"],
   "removed_tables": [],
-  "removed_columns": [],
-  "changed_tables": ["users"],
-  "needs_mask_decision": ["orders.memo"]
+  "removed_columns": ["orders.legacy_flag"],
+  "changed_tables": ["orders", "users"],
+  "needs_mask_decision": ["orders.memo"],
+  "stale_tables": [],
+  "stale_columns": ["orders.legacy_flag"]
 }
 ```
 
 `added_*` / `removed_*` / `changed_tables` mean the config no longer matches the schema — run
 `schema:generate` and `schema:tidy` to reconcile it. `needs_mask_decision` lists the columns
-whose masking nobody has decided on yet (see [the flag](#needs_mask_decision)). The exit code
+whose masking nobody has decided on yet (see [the flag](#needs_mask_decision)). `stale_tables` /
+`stale_columns` are the subset of the removals an extraction would actually trip over — a
+non-ignored config still naming a table or column the schema no longer has, so the export's
+SELECT would fail; removals of `ignore: true` entries (and of a rails-managed table's columns,
+which are dumped as `SELECT *`) stay out of them. They drive the exit code only under
+[`--fail-on=stale`](#non-rails-applications-exwiw-schema----from-db). The exit code
 makes it usable as a CI check that keeps a schema change from being merged until both are
 resolved; the JSON is stable and sorted, so it can be posted as-is. In a multi-database app each
 entry is prefixed with its database (`primary/users.email`), so the same table name in two
@@ -464,7 +471,7 @@ the same `EXWIW_SCHEMA_CHECK_OUTPUT` file and the same exit code — it just reg
 `MongoidSchemaGenerator` (safe mode + `tidy_mongoid`) instead. Collections and fields are
 reported under the same keys as tables and columns. An application that cannot be loaded to
 generate from its models at all can run the same check against its database instead: see
-[Non-Rails applications](#non-rails-applications-exwiw-schema---from-db).
+[Non-Rails applications](#non-rails-applications-exwiw-schema----from-db).
 
 #### Multiple databases
 
@@ -533,6 +540,15 @@ exwiw schema tidy --from-db -a postgresql -h db.example.com -p 5432 -u app --dat
   `EXWIW_SCHEMA_CHECK_OUTPUT`, and exits 1 when the config needs attention. A check that could
   not *run* (an unreachable database, a malformed config) exits with a different status, so CI
   can tell the two apart.
+- `check` also accepts `--fail-on=stale` for use as a pre-extraction gate: the exit code then
+  tracks only the report's `stale_tables` / `stale_columns` — a non-ignored config still naming
+  a table or column the schema no longer has, which is exactly the drift that would fail the
+  export's SELECT. Additions and unresolved `needs_mask_decision` flags stay visible in the
+  report but do not stop the run, so a schema migration that merely *adds* a column does not
+  block extraction. The default (`--fail-on=any`) is the CI behavior above, unchanged.
+  `--fail-on` is command-line only (not a config-file key — a gate flag belongs to the
+  invocation, not the committed config) and is meaningful only on `schema check`: the other
+  schema verbs reject it, and `export` ignores it like the other schema-only flags.
 - One run covers one database — the connection addresses one — so the files are written flat into
   the schema directory. There is no per-database subdirectory layout here; a second database is a
   second run against a second connection.
@@ -864,6 +880,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!`.
+- **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`).
 - **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).

data/lib/exwiw/adapter/mysql_adapter.rb

@@ -269,6 +269,16 @@ module Exwiw
         @materialize_scopes = false
       end
 
+      # The inverse, for a region that may embed the same id-set more than once
+      # in one statement (MySQL cannot reopen a TEMPORARY table).
+      private def without_scope_materialization
+        saved = @materialize_scopes
+        @materialize_scopes = false
+        yield
+      ensure
+        @materialize_scopes = saved
+      end
+
       private def materialized_scope_table(subquery)
         return nil unless @materialize_scopes
         return nil if @scope_materialization_disabled
@@ -348,9 +358,13 @@ module Exwiw
         return compile_ast(subquery.query) if subquery.is_a?(Exwiw::QueryAst::SelectSubquery)
 
         # A UnionSubquery wraps several such Selects; UNION their compiled forms
-        # into a single id set.
+        # into a single id set. Sibling arms can carry the same nested scope
+        # id-set, and MySQL cannot reference one TEMPORARY table twice in a
+        # statement (ER_CANT_REOPEN_TABLE), so nested scopes compile inline here.
         if subquery.is_a?(Exwiw::QueryAst::UnionSubquery)
-          return subquery.queries.map { |q| compile_ast(q) }.join(' UNION ')
+          return without_scope_materialization do
+            subquery.queries.map { |q| compile_ast(q) }.join(' UNION ')
+          end
         end
 
         inner_values = subquery.where_values.map { |v| escape_value(v) }

data/lib/exwiw/cli.rb

@@ -119,6 +119,10 @@ module Exwiw
       @parallel_workers = nil
       @mongodb_query_timeout_ms = nil
       @explain_verbosity = nil
+      # `schema check` only: which part of the report drives the exit code.
+      # nil (not "any") so validation can tell "user passed --fail-on" apart
+      # from the default when rejecting it on the other verbs.
+      @fail_on = nil
       # nil (not :info) so we can tell "user passed --log-level" from the default,
       # letting a config-file value fill in; the :info default is applied later.
       @log_level = nil
@@ -252,9 +256,33 @@ module Exwiw
 
       return if SchemaCheck.clean?(report)
 
-      $stderr.puts "exwiw: the schema config is out of date or has undecided masking; " \
-                   "run `exwiw schema generate --from-db` (then `exwiw schema tidy --from-db`) " \
-                   "and resolve every `needs_mask_decision` column."
+      # --fail-on=stale: a pre-extraction gate stops only on the drift that
+      # would break the export itself; the report above still carries the rest.
+      if @fail_on == "stale" && !SchemaCheck.stale?(report)
+        $stderr.puts "exwiw: the schema config has drifted, but nothing the extraction reads is stale " \
+                     "(--fail-on=stale); run `exwiw schema generate --from-db` at your leisure."
+        return
+      end
+
+      if SchemaCheck.stale?(report)
+        # Name what blocks the export, capped — a migration can drop dozens of
+        # columns, and the full list is in the report above.
+        stale = SchemaCheck::STALE_CATEGORIES.flat_map { |category| report.fetch(category, []) }
+        listed = stale.first(10)
+        listed << "and #{stale.size - listed.size} more (see the report)" if stale.size > listed.size
+        $stderr.puts "exwiw: the config still references #{listed.join(', ')} — gone from the database, " \
+                     "so an extraction SELECT would fail on them; " \
+                     "run `exwiw schema generate --from-db` (then `exwiw schema tidy --from-db`) to drop them."
+        # The default (CI) mode is a one-shot report; the gate deliberately
+        # stays quiet about mask decisions.
+        if @fail_on != "stale" && report.fetch("needs_mask_decision", []).any?
+          $stderr.puts "exwiw: the report also lists `needs_mask_decision` columns; resolve those too."
+        end
+      else
+        $stderr.puts "exwiw: the schema config is out of date or has undecided masking; " \
+                     "run `exwiw schema generate --from-db` (then `exwiw schema tidy --from-db`) " \
+                     "and resolve every `needs_mask_decision` column."
+      end
       exit SCHEMA_CHECK_DIRTY_EXIT
     end
 
@@ -639,6 +667,15 @@ module Exwiw
         exit 1
       end
 
+      if @fail_on && @schema_verb != "check"
+        $stderr.puts "--fail-on only applies to `exwiw schema check` (got `exwiw schema #{@schema_verb}`)."
+        exit 1
+      end
+      if @fail_on && !%w[any stale].include?(@fail_on)
+        $stderr.puts "--fail-on must be 'any' or 'stale' (got '#{@fail_on}')."
+        exit 1
+      end
+
       unless DbIntrospector::SUPPORTED_ADAPTERS.include?(@database_adapter)
         $stderr.puts "--from-db supports the #{DbIntrospector::SUPPORTED_ADAPTERS.join(' and ')} adapters only " \
                      "(got '#{@database_adapter}'). sqlite and mongodb schemas are not read this way."
@@ -826,6 +863,7 @@ module Exwiw
         end
         opts.on("--parallel-workers=N", Integer, "Fork N workers for the MongoDB dump's parallel schedule (mongodb + export only; N>=2 enables it, default is serial). Output is byte-identical to serial; falls back to serial where fork is unavailable.") { |v| @parallel_workers = v }
         opts.on("--mongodb-query-timeout-ms=N", Integer, "Global server-enforced timeout (ms) for every MongoDB query (mongodb only). Aborts an accidentally heavy/unscoped query past the deadline. Overridden per collection by `query_timeout_ms` in the schema config.") { |v| @mongodb_query_timeout_ms = v }
+        opts.on("--fail-on=CATEGORY", "schema check only: what makes the exit code non-zero. 'any' (default) fails on any drift or undecided masking; 'stale' fails only when the committed config references tables/columns the schema no longer has - the drift that would break an export. The full report is printed either way.") { |v| @fail_on = v }
         opts.on("--log-level=LEVEL", "Log level (debug, info). default is info") { |v| @log_level = v.to_sym }
 
         opts.on("--help", "Print this help") do

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, forward_path: [], batch_ids: nil)
-      new(table_name, table_by_name, dump_target, logger, allow_reverse: allow_reverse, forward_path: forward_path, batch_ids: batch_ids).run
+    def self.run(table_name, table_by_name, dump_target, logger, allow_reverse: true, allow_declared_reverse: true, forward_path: [], reverse_path: [], deep_chain_warned: nil, batch_ids: nil)
+      new(table_name, table_by_name, dump_target, logger, allow_reverse: allow_reverse, allow_declared_reverse: allow_declared_reverse, forward_path: forward_path, reverse_path: reverse_path, deep_chain_warned: deep_chain_warned, batch_ids: batch_ids).run
     end
 
     # Scope-column mode classification for a single table. One of
@@ -34,15 +34,25 @@ module Exwiw
       # Unscopable is reported before a bad batch_scope shape — it is the more
       # fundamental problem.
       if scope_mode?(table_by_name, dump_target)
+        # Keep each table's builder: classification records ambiguous_referencers,
+        # and this pre-flight message is what an operator actually reads.
         unscopable =
-          tables.reject(&:ignore).select do |table|
-            scope_category(table.name, table_by_name, dump_target, logger) == :unscopable
+          tables.reject(&:ignore).filter_map do |table|
+            builder = new(table.name, table_by_name, dump_target, logger)
+            next unless builder.scope_category == :unscopable
+
+            if builder.ambiguous_referencers
+              "#{table.name} (referenced by multiple constrained tables: " \
+                "#{builder.ambiguous_referencers} — declaring `reverse_scope` on it " \
+                "to union their ids is likely the fix)"
+            else
+              table.name
+            end
           end
 
         if unscopable.any?
-          names = unscopable.map(&:name).sort.join(", ")
           raise ArgumentError,
-                "scope-column mode: #{unscopable.size} table(s) cannot be scoped: #{names}. " \
+                "scope-column mode: #{unscopable.size} table(s) cannot be scoped: #{unscopable.sort.join(', ')}. " \
                 "For each, declare `scope_column: <column>` on the table to filter it directly, " \
                 "add a belongs_to path to a table that carries the scope column, mark it " \
                 "`scope_exempt: true` to export it in full, or set `ignore: true` to skip it."
@@ -58,7 +68,11 @@ module Exwiw
 
     attr_reader :table_name, :table_by_name, :dump_target
 
-    def initialize(table_name, table_by_name, dump_target, logger, allow_reverse: true, forward_path: [], batch_ids: nil)
+    # The multiple constrained referencers (comma-joined) that made the
+    # automatic reverse detection step aside, when it did.
+    attr_reader :ambiguous_referencers
+
+    def initialize(table_name, table_by_name, dump_target, logger, allow_reverse: true, allow_declared_reverse: true, forward_path: [], reverse_path: [], deep_chain_warned: nil, batch_ids: nil)
       @table_name = table_name
       @table_by_name = table_by_name
       @dump_target = dump_target
@@ -76,6 +90,19 @@ module Exwiw
       # table already on the path is not re-resolved, falling through to
       # :unscopable instead of looping forever.
       @forward_path = forward_path
+      # @reverse_path is the reverse counterpart: the chain of tables whose
+      # reverse resolution is in progress up the stack. It bounds the declared
+      # reverse_scope recursion — a table already being reverse-resolved is not
+      # resolved again, so a cycle of declarations terminates.
+      @reverse_path = reverse_path
+      # Whether this build may honor an explicit `reverse_scope` even though
+      # @allow_reverse is off: true for a reverse_scope arm build, false for the
+      # auto-detection's child builds (widening those would change the detection's
+      # candidate count and could bail a scoped table into a full dump).
+      @allow_declared_reverse = allow_declared_reverse
+      # Deep-chain warnings already emitted, keyed by chain path and shared (the
+      # same Hash) across every recursive build under one top-level run.
+      @deep_chain_warned = deep_chain_warned || {}
     end
 
     def run
@@ -91,9 +118,12 @@ module Exwiw
       # every row (see the "no relation -> dump all" case). If an extractable
       # child table references it via a foreign key (e.g. active_storage_blobs is
       # referenced by active_storage_attachments.blob_id), constrain it to just
-      # the referenced ids instead. Disabled (@allow_reverse=false) while building
-      # a child's subquery, so this never recurses.
-      if @allow_reverse && table.name != dump_target.table_name &&
+      # the referenced ids instead. The automatic detection is disabled
+      # (@allow_reverse=false) while building a child's subquery, so it never
+      # recurses; an explicit `reverse_scope` still applies inside a reverse_scope
+      # arm build (@allow_declared_reverse), with @reverse_path cutting cycles.
+      if (@allow_reverse || (@allow_declared_reverse && explicit_reverse_scope?(table))) &&
+         table.name != dump_target.table_name &&
          where_clauses.empty? && join_clauses.empty?
         reverse_clause = build_referenced_by_clause(table)
         where_clauses.push(reverse_clause) if reverse_clause
@@ -121,6 +151,19 @@ module Exwiw
         end
       end
 
+      # The reverse detection stepped aside on an ambiguity and nothing else
+      # scoped the table: at the top level of single-target mode that is a full
+      # dump, which must not happen at debug volume. Only the final outcome
+      # warns — a table the cascade rescued stays quiet.
+      if @ambiguous_referencers && where_clauses.empty? && join_clauses.empty? &&
+         @forward_path.empty? && @reverse_path.empty? && !scope_exempt?(table)
+        @logger.warn(
+          "  #{table.name} is referenced by multiple constrained tables (#{@ambiguous_referencers}), " \
+          "which the automatic reverse extraction cannot pick between, and nothing else scopes it — " \
+          "it is dumped in full. Declare `reverse_scope` on it to union their ids."
+        )
+      end
+
       QueryAst::Select.new.tap do |ast|
         ast.from(table.name)
         if table.rails_managed?
@@ -210,11 +253,20 @@ module Exwiw
       # the schema author has enumerated the referencers explicitly, constrain
       # the table to the UNION of those referencers' scoped queries instead of
       # the single-referencer auto-detection below (which bails to a full dump
-      # once two or more tables reference the table).
-      if table.reverse_scope && table.reverse_scope.via.any?
+      # once two or more tables reference the table). Unlike the auto-detection,
+      # this branch also runs during a reverse_scope arm build
+      # (@allow_declared_reverse); @reverse_path bounds the recursion.
+      if explicit_reverse_scope?(table)
+        return nil unless @allow_reverse || @allow_declared_reverse
+
         return build_reverse_scope_via_clause(table)
       end
 
+      # The automatic single-referencer detection is top-level only: during a
+      # subquery build it could recurse through a chain of FK-less tables that
+      # reference each other.
+      return nil unless @allow_reverse
+
       candidates = table_by_name.each_value.filter_map do |other|
         next if other.name == table.name
 
@@ -225,11 +277,12 @@ 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; 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])
+        # chain of FK-less tables from recursing back into each other; the grown
+        # forward_path/reverse_path stop the child from scoping back through this
+        # table. allow_declared_reverse is OFF: a child scoped only by its own
+        # reverse_scope must stay unconstrained here, or it would widen the
+        # candidate set and could bail this detection out of a scope it had.
+        child_query = self.class.run(other.name, table_by_name, dump_target, @logger, allow_reverse: false, allow_declared_reverse: false, forward_path: @forward_path + [table.name], reverse_path: @reverse_path + [table.name], deep_chain_warned: @deep_chain_warned)
 
         # Only an *already constrained* child narrows anything; an unconstrained
         # child would select every fk value (i.e. dump all) and not help.
@@ -239,11 +292,14 @@ module Exwiw
       end
 
       # Scope: only the unambiguous single-referencer case. Multiple referencers
-      # would need their subqueries OR'd together (not yet supported); falling
-      # back to dump-all preserves today's behavior for those.
+      # would need `reverse_scope` to union them; falling back preserves today's
+      # behavior for those.
       if candidates.size != 1
         if candidates.size > 1
-          @logger.debug("  #{table.name} has multiple referencing tables; skipping reverse extraction (dump all).")
+          # Whether the ambiguity deserves a warning depends on the outcome —
+          # the forward cascade may still scope the table — so `run` decides.
+          @ambiguous_referencers = candidates.map { |_, query| query.from_table_name }.sort.join(', ')
+          @logger.debug("  #{table.name} has multiple referencing tables; skipping reverse extraction.")
         end
         return nil
       end
@@ -279,7 +335,33 @@ module Exwiw
     # every row's id and union the whole table back, silently defeating the
     # prune. Returns nil when no arm survives, leaving the caller to fall back to
     # the dump-all behavior (which validate_scope! then rejects in scope mode).
+    #
+    # A referencer that is itself scoped only by its own `reverse_scope` still
+    # resolves, so declared chains nest, with @reverse_path cutting cycles.
     private def build_reverse_scope_via_clause(table)
+      if @reverse_path.include?(table.name)
+        @logger.debug(
+          "  #{table.name}.reverse_scope is already being resolved " \
+          "(#{(@reverse_path + [table.name]).join(' -> ')}); cutting the cycle."
+        )
+        return nil
+      end
+
+      # Each level of a declared chain re-embeds its referencers' subqueries, so
+      # the generated SQL grows exponentially with depth; flag chains deeper than
+      # the intended 2-3. Deduped: this build repeats once per arm per level.
+      if @reverse_path.size >= 3
+        path = (@reverse_path + [table.name]).join(' -> ')
+        unless @deep_chain_warned[path]
+          @deep_chain_warned[path] = true
+          @logger.warn(
+            "  #{table.name}.reverse_scope is nested #{@reverse_path.size + 1} declarations deep " \
+            "(#{path}); the generated SQL grows exponentially with chain depth — consider scoping " \
+            "an intermediate table another way."
+          )
+        end
+      end
+
       arms = table.reverse_scope.via.filter_map do |via|
         referencer = table_by_name[via.table]
         if referencer.nil?
@@ -287,12 +369,11 @@ module Exwiw
           next
         end
 
-        # 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])
+        # Build the referencer's own scoped extraction query. The automatic
+        # reverse detection stays off; the referencer may forward-scope through
+        # other tables and (allow_declared_reverse) resolve its own explicit
+        # reverse_scope, with the grown paths keeping it from coming back here.
+        ref_query = self.class.run(referencer.name, table_by_name, dump_target, @logger, allow_reverse: false, allow_declared_reverse: true, forward_path: @forward_path + [table.name], reverse_path: @reverse_path + [table.name], deep_chain_warned: @deep_chain_warned)
 
         unless ref_query.where_clauses.any? || ref_query.join_clauses.any?
           @logger.warn(
@@ -392,8 +473,9 @@ module Exwiw
 
           # 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)
+          # cascade multi-hop; reverse_path rides along to keep an in-progress
+          # reverse resolution from being re-entered.
+          parent_query = self.class.run(parent.name, table_by_name, dump_target, @logger, allow_reverse: true, forward_path: forward_path, reverse_path: @reverse_path, deep_chain_warned: @deep_chain_warned)
 
           # Only a constrained parent narrows anything; an unconstrained parent
           # would select every pk (i.e. dump all) and not help.
@@ -570,7 +652,7 @@ module Exwiw
         return ast
       end
 
-      if @allow_reverse
+      if @allow_reverse || (@allow_declared_reverse && explicit_reverse_scope?(table))
         # Referenced by an extractable (scoped) child: constrain via subquery.
         reverse_clause = build_referenced_by_clause(table)
         if reverse_clause
@@ -619,6 +701,11 @@ module Exwiw
       table.scope_exempt || table.rails_managed?
     end
 
+    # Whether the schema author declared how this table is reverse-scoped.
+    private def explicit_reverse_scope?(table)
+      !!(table.reverse_scope && table.reverse_scope.via.any?)
+    end
+
     private def directly_scoped?(table)
       column = resolved_scope_column(table)
       table.columns.any? { |c| c.name == column }
@@ -855,7 +942,7 @@ module Exwiw
 
       target_query = self.class.run(
         target.name, table_by_name, dump_target, @logger,
-        allow_reverse: true, forward_path: @forward_path + [table.name]
+        allow_reverse: true, forward_path: @forward_path + [table.name], reverse_path: @reverse_path, deep_chain_warned: @deep_chain_warned
       )
       # An unconstrained target selects every id, i.e. does not scope the arm at
       # all; dropping the arm is the safe outcome.
@@ -1041,11 +1128,22 @@ module Exwiw
     end
 
     private def scope_unscopable_message(table)
-      "Table '#{table.name}' cannot be scoped in scope-column mode: it carries no scope " \
+      message =
+        "Table '#{table.name}' cannot be scoped in scope-column mode: it carries no scope " \
         "column (no per-table `scope_column` is declared on it) and has no belongs_to path " \
         "to a table that does. Declare `scope_column: <column>` on it, mark it " \
         "`scope_exempt: true` to export it in full, set `ignore: true` to skip it, or add " \
         "the missing belongs_to."
+
+      # None of the generic options above is the right fix for the referencer
+      # ambiguity; give the same precise remedy the single-target warning gives.
+      if @ambiguous_referencers
+        message += " Note: it is referenced by multiple constrained tables " \
+                   "(#{@ambiguous_referencers}); declaring `reverse_scope` on it to union " \
+                   "their ids is likely the fix."
+      end
+
+      message
     end
   end
 end

data/lib/exwiw/schema_check.rb

@@ -21,6 +21,15 @@ module Exwiw
       added_tables added_columns removed_tables removed_columns changed_tables needs_mask_decision
     ].freeze
 
+    # The subset of the removals that would break an `export` run: a non-ignored
+    # config still referencing a table or column the schema no longer has, i.e.
+    # the extraction SELECT would name something that does not exist. Removals of
+    # `ignore: true` entries stay out (nothing selects them), as do additions.
+    # `--fail-on=stale` keys the exit code to these. Deliberate over-approximation:
+    # a hand-written config naming a database VIEW lands here too (tidy's stance),
+    # though a SELECT against it would succeed.
+    STALE_CATEGORIES = %w[stale_tables stale_columns].freeze
+
     def self.from_rails_application(schema_dir:)
       Rails.application.eager_load!
       new(models: ActiveRecord::Base.descendants, schema_dir: schema_dir)
@@ -81,6 +90,12 @@ module Exwiw
       CATEGORIES.all? { |category| report.fetch(category, []).empty? }
     end
 
+    # Whether the report contains drift that would break an extraction run
+    # (see STALE_CATEGORIES). Always a subset of what makes clean? false.
+    def self.stale?(report)
+      STALE_CATEGORIES.any? { |category| !report.fetch(category, []).empty? }
+    end
+
     private def regenerate_into(tmp_dir)
       FileUtils.cp_r(File.join(@schema_dir, "."), tmp_dir) if Dir.exist?(@schema_dir)
       @regenerator.call(tmp_dir)
@@ -111,7 +126,7 @@ module Exwiw
     end
 
     private def diff(committed, regenerated)
-      report = CATEGORIES.to_h { |category| [category, []] }
+      report = (CATEGORIES + STALE_CATEGORIES).to_h { |category| [category, []] }
 
       (committed.keys | regenerated.keys).sort.each do |key|
         before = committed[key]
@@ -122,7 +137,11 @@ module Exwiw
           next
         end
         if after.nil?
-          report["removed_tables"] << table_label(key, before)
+          label = table_label(key, before)
+          report["removed_tables"] << label
+          # A rails-managed table is dumped whole, so its disappearance breaks
+          # the export too; only `ignore: true` keeps a removed table out.
+          report["stale_tables"] << label unless before["ignore"]
           next
         end
         next if before == after
@@ -132,6 +151,10 @@ module Exwiw
         added, removed = column_diff(before, after)
         report["added_columns"] += added.sort.map { |column| "#{label}.#{column}" }
         report["removed_columns"] += removed.sort.map { |column| "#{label}.#{column}" }
+        if extracted?(before)
+          stale = removed & extracted_column_names(before)
+          report["stale_columns"] += stale.sort.map { |column| "#{label}.#{column}" }
+        end
       end
 
       report
@@ -148,6 +171,22 @@ module Exwiw
       (config["columns"] || config["fields"] || []).map { |column| column["name"] }
     end
 
+    # Whether the extraction SELECT names this table's columns: an `ignore: true`
+    # config only contributes DDL, and a rails-managed one is dumped as
+    # `SELECT *` — so a removed column cannot break either. (A removed
+    # rails-managed table still can; #diff handles that separately.)
+    private def extracted?(config)
+      !config["ignore"] && !TableConfig::RAILS_MANAGED_TYPES.include?(config["type"])
+    end
+
+    # The columns the extraction SELECT actually names: `ignore: true` columns
+    # are dropped when the config loads, so their staleness breaks nothing.
+    private def extracted_column_names(config)
+      (config["columns"] || config["fields"] || [])
+        .reject { |column| column["ignore"] }
+        .map { |column| column["name"] }
+    end
+
     # How a table is named in the report. The database is part of the label, or
     # the same table name in two of them collides (each has `schema_migrations`).
     private def table_label(key, config)

data/lib/exwiw/version.rb

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

metadata

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