exwiw 0.3.9 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea6a0b4fda446d66766027139136320937a59319bfe28d83ee595cf062a4023a
-  data.tar.gz: 1ce3d4a7601ae6b3f1fe6ca8ed22e977389ac7ab46973c33113206911893326e
+  metadata.gz: a743c4759cdb8b292e4fdfe8ea3d4e10fa66e15a70677dd685366fb9e26a376b
+  data.tar.gz: '04048ceca802c0d418495cdf7c002bd47047beb05a53655a451c2c77a4d8270d'
 SHA512:
-  metadata.gz: '08ffcb1713110629652b4047b159613ab3d13e5fffcd092433282f28564328d1609572d8f159b1c0e7fddfab1be4fc92651b8f819ddfa44a913e18da04e4aeef'
-  data.tar.gz: 77529a1897ded0943898f60d8a55d54bfdf35f80fc512b57be7300adad9fc8c99767199de8e6d9fb9649dc2644fbcfc2252e445de2f5c38bc20aece5ae4a56d5
+  metadata.gz: 7d7a5ffca1cdae405e88fac5d72e4ed4e52ee3deec8cce0e503dcdc2b4136ec03ca2d84893c5897a3e56a78b0fa9e11dddc5f606566f32c90297815c8ade4702
+  data.tar.gz: 8e7742f720c371b41679c311d6323f8182e4f414f1ff199ac90928026ce46c2607a61a3c3a7ed91c23c97ea4b855d838bfee38b593d69c06f1dc743a17916eb0

data/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-06-04
+
+### Added
+
+- `MongoidSchemaGenerator` gains an opt-in `skip_unsupported:` mode (via the rake task, `EXWIW_SKIP_UNSUPPORTED=1 bundle exec rake exwiw:schema:generate_mongoid`). When enabled, generation no longer aborts on a construct exwiw cannot represent: an unresolvable `belongs_to` (whose target class no longer exists — e.g. a stale relation left behind after the model was removed) is skipped with a stderr warning while its foreign-key column is still kept as a field, and a polymorphic / self-referential-cyclic / unresolvable-parent `embedded_in` collection is emitted as a top-level `ignore: true` config annotated with a `comment` explaining why — so it is not wrongly dumped as its own collection — instead of raising. Off by default, so the existing fail-loud behavior is unchanged for callers that do not opt in. `MongodbCollectionConfig` now also carries an optional collection-level `comment` attribute, preserved across regeneration like the field / belongs_to `comment`.
+
+## [0.4.0] - 2026-06-04
+
+### Fixed
+
+- PostgreSQL: extraction no longer fails with `operator does not exist: character varying = uuid` when a `belongs_to` chain crosses a varchar foreign key and a uuid primary key. The adapter now introspects column types via `pg_attribute`/`pg_type` at query compile time and injects `::text` casts on both sides of the comparison when a uuid/varchar mismatch is detected. Covers JOIN ON conditions, WHERE IN subqueries, and bulk-delete IN clauses. ([#73](https://github.com/heyinc/exwiw/pull/73))
+
 ## [0.3.9] - 2026-06-03
 
 ### Added

data/README.md

@@ -200,6 +200,15 @@ Models in an inheritance hierarchy whose subclasses share the base's collection
 
 Regeneration preserves hand-edited `replace_with`, `filter`, `ignore`, and `bulk_insert_chunk_size` values, like the ActiveRecord generator. Indexes are not written to the config — they are introspected from the live database at dump time (see [MongoDB notes](#mongodb-notes)). Polymorphic `belongs_to` is not yet expanded by this task.
 
+By default the task **aborts** when a model uses a construct exwiw cannot represent: a `belongs_to` whose target class can no longer be resolved (a stale relation left behind after its model was removed), or a polymorphic / self-referential-cyclic / unresolvable-parent `embedded_in` (see the cases above). Set `EXWIW_SKIP_UNSUPPORTED=1` to keep going instead:
+
+```bash
+EXWIW_SKIP_UNSUPPORTED=1 bundle exec rake exwiw:schema:generate_mongoid
+```
+
+- An unresolvable `belongs_to` is dropped from the collection's `belongs_tos` (its foreign-key column is still kept as an ordinary field, like the polymorphic / HABTM cases) and a warning naming the relation is printed to stderr.
+- An unrepresentable `embedded_in` collection is emitted as a **top-level** config marked `"ignore": true` with a `comment` recording why, and a warning is printed. `ignore: true` keeps it out of extraction so it is not wrongly dumped as its own collection; to actually dump/mask such an embedded collection, define its `embedded_in` config by hand (see [Embedded documents](#embedded-documents)). This is useful for bootstrapping a config against a large app where a handful of legacy/polymorphic collections would otherwise block the whole run.
+
 ### Configuration
 
 This is an example of the one table schema:

data/lib/exwiw/adapter/postgresql_adapter.rb

@@ -177,8 +177,17 @@ module Exwiw
         end
 
         foreign_key = first_join.foreign_key
-        subquery_sql = compile_ast(subquery_ast)
-        sql += "\nWHERE #{select_query_ast.from_table_name}.#{foreign_key} IN (#{subquery_sql})"
+        outer_table = select_query_ast.from_table_name
+        inner_table = first_join.join_table_name
+        inner_column = first_join.primary_key
+        cast_to = types_need_cast?(
+          column_pg_type(outer_table, foreign_key),
+          column_pg_type(inner_table, inner_column)
+        ) ? 'text' : nil
+        subquery_sql = compile_ast(subquery_ast, select_cast_to: cast_to)
+        outer_expr = "#{outer_table}.#{foreign_key}"
+        outer_expr = "#{outer_expr}::text" if cast_to
+        sql += "\nWHERE #{outer_expr} IN (#{subquery_sql})"
 
         # first_join.base_where_clauses holds conditions on the outer
         # delete-target table (from_table_name), such as a polymorphic type
@@ -195,19 +204,30 @@ module Exwiw
         sql
       end
 
-      def compile_ast(query_ast)
+      def compile_ast(query_ast, select_cast_to: nil)
         raise NotImplementedError unless query_ast.is_a?(Exwiw::QueryAst::Select)
 
         sql = "SELECT "
         sql += if query_ast.select_all
                  "*"
                else
-                 query_ast.columns.map { |col| compile_column_name(query_ast, col) }.join(', ')
+                 cols = query_ast.columns.map { |col| compile_column_name(query_ast, col) }
+                 cols = cols.map { |c| "#{c}::#{select_cast_to}" } if select_cast_to
+                 cols.join(', ')
                end
         sql += " FROM #{query_ast.from_table_name}"
 
         query_ast.join_clauses.each do |join|
-          sql += " JOIN #{join.join_table_name} ON #{join.base_table_name}.#{join.foreign_key} = #{join.join_table_name}.#{join.primary_key}"
+          fk_expr = "#{join.base_table_name}.#{join.foreign_key}"
+          pk_expr = "#{join.join_table_name}.#{join.primary_key}"
+          if types_need_cast?(
+            column_pg_type(join.base_table_name, join.foreign_key),
+            column_pg_type(join.join_table_name, join.primary_key)
+          )
+            fk_expr = "#{fk_expr}::text"
+            pk_expr = "#{pk_expr}::text"
+          end
+          sql += " JOIN #{join.join_table_name} ON #{fk_expr} = #{pk_expr}"
 
           join.where_clauses.each do |where|
             compiled_where_condition = compile_where_condition(where, join.join_table_name)
@@ -246,23 +266,54 @@ module Exwiw
             "#{key} IN (#{values.join(', ')})"
           end
         elsif where_clause.operator == :in_subquery
-          "#{key} IN (#{compile_subquery(where_clause.value)})"
+          subquery_sql = compile_subquery(where_clause.value, outer_table: table_name, outer_column: where_clause.column_name)
+          cast_to = subquery_cast_to(where_clause.value, table_name, where_clause.column_name)
+          outer_key = cast_to ? "#{key}::#{cast_to}" : key
+          "#{outer_key} IN (#{subquery_sql})"
         else
           raise "Unsupported operator: #{where_clause.operator}"
         end
       end
 
-      private def compile_subquery(subquery)
-        # A SelectSubquery wraps a full Select (the referencing table's
-        # extraction query, projected to a foreign key); compile it as-is.
-        return compile_ast(subquery.query) if subquery.is_a?(Exwiw::QueryAst::SelectSubquery)
+      private def compile_subquery(subquery, outer_table: nil, outer_column: nil)
+        cast_to = subquery_cast_to(subquery, outer_table, outer_column)
+
+        if subquery.is_a?(Exwiw::QueryAst::SelectSubquery)
+          return compile_ast(subquery.query, select_cast_to: cast_to)
+        end
 
         inner_values = subquery.where_values.map { |v| escape_value(v) }
-        "SELECT #{subquery.table_name}.#{subquery.select_column} " \
+        select_expr = "#{subquery.table_name}.#{subquery.select_column}"
+        select_expr = "#{select_expr}::#{cast_to}" if cast_to
+        "SELECT #{select_expr} " \
           "FROM #{subquery.table_name} " \
           "WHERE #{subquery.table_name}.#{subquery.where_column} IN (#{inner_values.join(', ')})"
       end
 
+      private def subquery_select_target(subquery)
+        case subquery
+        when Exwiw::QueryAst::SelectSubquery
+          q = subquery.query
+          col = q.columns.first
+          col ? [q.from_table_name, col.name] : [nil, nil]
+        when Exwiw::QueryAst::Subquery
+          [subquery.table_name, subquery.select_column]
+        else
+          [nil, nil]
+        end
+      end
+
+      private def subquery_cast_to(subquery, outer_table, outer_column)
+        return nil if outer_table.nil? || outer_column.nil?
+
+        inner_table, inner_column = subquery_select_target(subquery)
+        return nil if inner_table.nil?
+
+        outer_type = column_pg_type(outer_table, outer_column)
+        inner_type = column_pg_type(inner_table, inner_column)
+        types_need_cast?(outer_type, inner_type) ? 'text' : nil
+      end
+
       private def escape_value(value)
         case value
         when nil
@@ -351,6 +402,36 @@ module Exwiw
         end
       end
 
+      private def column_pg_type(table_name, column_name)
+        @column_type_cache ||= {}
+        cache_key = [table_name, column_name]
+        return @column_type_cache[cache_key] if @column_type_cache.key?(cache_key)
+
+        sql = <<~SQL
+          SELECT t.typname
+          FROM pg_attribute a
+          JOIN pg_class c ON c.oid = a.attrelid
+          JOIN pg_type t  ON t.oid = a.atttypid
+          WHERE c.relname = $1
+            AND a.attname = $2
+            AND a.attnum > 0
+            AND NOT a.attisdropped
+          LIMIT 1
+        SQL
+
+        result = connection.exec_params(sql, [table_name, column_name])
+        @column_type_cache[cache_key] = result.ntuples > 0 ? result.getvalue(0, 0) : nil
+      end
+
+      private def types_need_cast?(type_a, type_b)
+        return false if type_a.nil? || type_b.nil?
+        return false if type_a == type_b
+
+        string_types = %w[varchar text bpchar name].freeze
+        (type_a == 'uuid' && string_types.include?(type_b)) ||
+          (type_b == 'uuid' && string_types.include?(type_a))
+      end
+
       private def connection
         @connection ||=
           begin

data/lib/exwiw/mongodb_collection_config.rb

@@ -14,6 +14,12 @@ module Exwiw
     attribute :fields, array(MongodbField)
     attribute :bulk_insert_chunk_size, optional(Integer), skip_serializing_if_nil: true
     attribute :ignore, Serdes::OptionalType.new(Serdes::ConcreteType.new(Boolean)), skip_serializing_if_nil: true
+    # Free-form note. Purely informational — exwiw never reads it — and preserved
+    # across `MongoidSchemaGenerator` regeneration like the field / belongs_to
+    # `comment`. The generator also emits one when, under `skip_unsupported`, it
+    # marks an unrepresentable collection `ignore: true`, to record why extraction
+    # was skipped.
+    attribute :comment, optional(String), skip_serializing_if_nil: true
 
     # Marks this config as physically embedded inside another collection's
     # documents. When set, this config is not processed as a standalone dump
@@ -62,6 +68,10 @@ module Exwiw
         merged.filter = filter
         merged.bulk_insert_chunk_size = bulk_insert_chunk_size
         merged.ignore = ignore
+        # A freshly generated comment (e.g. the skip_unsupported marker) wins so
+        # it stays accurate; otherwise a hand-added note on a normal collection
+        # is kept.
+        merged.comment = passed.comment || comment
         merged.embedded_in = passed.embedded_in
 
         # Structural facts of each belongs_to come from the freshly generated

data/lib/exwiw/mongoid_schema_generator.rb

@@ -14,14 +14,38 @@ module Exwiw
   # (`fields`, `relations`, `collection_name`), so it does not require a live
   # MongoDB connection.
   class MongoidSchemaGenerator
-    def self.from_rails_application(output_dir:)
+    # Raised when an embedded collection's `embedded_in` cannot be expressed as
+    # an exwiw config (polymorphic embedding, self-referential/cyclic embedding,
+    # or an unresolvable embedding-parent class). A subclass of ArgumentError so
+    # the historical `raise_error(ArgumentError, ...)` contract is preserved.
+    # Under `skip_unsupported` the generator rescues this and emits an
+    # `ignore: true` config instead of aborting the whole run.
+    class UnsupportedEmbedding < ArgumentError
+      # A concise phrase (as opposed to the long, actionable exception message)
+      # recorded as the generated config's `comment`.
+      attr_reader :reason
+
+      def initialize(message, reason:)
+        super(message)
+        @reason = reason
+      end
+    end
+
+    # `skip_unsupported`: when true, the generator does not abort on a construct
+    # it cannot represent. It skips an unresolvable `belongs_to` (keeping the
+    # foreign-key field) and emits an unrepresentable embedded collection as an
+    # `ignore: true` top-level config annotated with a `comment`, warning to
+    # stderr in both cases. Off by default, so the historical fail-loud behavior
+    # is unchanged unless a caller opts in.
+    def self.from_rails_application(output_dir:, skip_unsupported: false)
       Rails.application.eager_load!
-      new(models: ::Mongoid.models, output_dir: output_dir)
+      new(models: ::Mongoid.models, output_dir: output_dir, skip_unsupported: skip_unsupported)
     end
 
-    def initialize(models:, output_dir:)
+    def initialize(models:, output_dir:, skip_unsupported: false)
       @models = models
       @output_dir = output_dir
+      @skip_unsupported = skip_unsupported
     end
 
     def generate!
@@ -78,7 +102,31 @@ module Exwiw
         # supported (MongodbCollectionConfig rejects them), so embedded configs
         # always carry an empty belongs_tos and instead declare where they live.
         attrs[:belongs_tos] = []
-        attrs[:embedded_in] = embedded_in_for(ordered.find(&:embedded?))
+        begin
+          attrs[:embedded_in] = embedded_in_for(ordered.find(&:embedded?))
+        rescue => e
+          # Known-unrepresentable shapes arrive as UnsupportedEmbedding (with a
+          # concise reason). Without skip_unsupported, re-raise so the historical
+          # fail-loud behavior is preserved. The broad rescue is a deliberate
+          # safety net for skip_unsupported (a best-effort bootstrapping mode):
+          # any other error while deriving the embedding is turned into an
+          # `ignore: true` config too, so a single odd model never aborts the run.
+          raise e unless @skip_unsupported
+
+          reason =
+            if e.is_a?(UnsupportedEmbedding)
+              e.reason
+            else
+              "raised #{e.class} while deriving embedded_in (#{e.message.lines.first&.strip})"
+            end
+
+          # Emit the collection as a top-level config marked `ignore: true` so it
+          # is NOT (wrongly) dumped as its own collection, and record why. The
+          # user can hand-write its embedded_in config later to dump/mask it.
+          warn("exwiw: skip_unsupported: '#{collection_name}' #{reason}; emitting ignore:true (define embedded_in by hand to dump/mask it).")
+          attrs[:ignore] = true
+          attrs[:comment] = "exwiw could not derive embedded_in (#{reason}); marked ignore:true. Define this collection's embedded_in config by hand to dump/mask it."
+        end
       else
         attrs[:belongs_tos] = aggregate_belongs_tos(ordered)
       end
@@ -168,10 +216,25 @@ module Exwiw
       # same belongs_to twice, so uniq them.
       belongs_to_assocs
         .reject(&:polymorphic?)
-        .map { |assoc| { table_name: assoc.klass.collection_name.to_s, foreign_key: assoc.foreign_key } }
+        .filter_map { |assoc| belongs_to_for(assoc) }
         .uniq
     end
 
+    # Resolves a referenced belongs_to to a `{ table_name, foreign_key }` pair.
+    # `assoc.klass` raises NameError when the association's target class no longer
+    # exists (a stale/legacy `belongs_to`, e.g. pointing at a model removed years
+    # ago). Under `skip_unsupported` such a relation is skipped with a warning —
+    # its foreign-key column is still tracked as an ordinary field by
+    # `aggregate_fields`, mirroring how polymorphic / HABTM relations are dropped.
+    private def belongs_to_for(assoc)
+      { table_name: assoc.klass.collection_name.to_s, foreign_key: assoc.foreign_key }
+    rescue NameError, ::Mongoid::Errors::MongoidError => e
+      raise e unless @skip_unsupported
+
+      warn("exwiw: skip_unsupported: skipping belongs_to ':#{assoc.name}' that could not be resolved (#{e.class}: #{e.message.lines.first&.strip}); its foreign key '#{assoc.foreign_key}' is still kept as a field.")
+      nil
+    end
+
     # Resolves the `embedded_in` config for an embedded model. Each embedded
     # model points at its *immediate* embedding parent: the parent's collection
     # name plus the single document key (`store_as`, defaulting to the relation
@@ -196,14 +259,30 @@ module Exwiw
       # names exactly one parent collection + path, so this shape cannot be
       # represented; fail loudly with an actionable message instead of crashing.
       if assoc.polymorphic?
-        raise ArgumentError,
-              "MongoidSchemaGenerator: '#{model.name}' (collection '#{model.collection_name}') " \
-              "declares a polymorphic `embedded_in :#{assoc.name}`, which has no single embedding " \
-              "parent collection and cannot be expressed as an exwiw `embedded_in` config. " \
-              "Define the collection's config by hand, or make the relation non-polymorphic."
+        raise UnsupportedEmbedding.new(
+          "MongoidSchemaGenerator: '#{model.name}' (collection '#{model.collection_name}') " \
+          "declares a polymorphic `embedded_in :#{assoc.name}`, which has no single embedding " \
+          "parent collection and cannot be expressed as an exwiw `embedded_in` config. " \
+          "Define the collection's config by hand, or make the relation non-polymorphic.",
+          reason: "has a polymorphic embedded_in :#{assoc.name}",
+        )
       end
 
-      parent = assoc.klass
+      parent =
+        begin
+          assoc.klass
+        rescue NameError => e
+          # The embedding-parent class named by `class_name` (or inferred from
+          # the relation) does not exist — a stale/renamed parent. exwiw cannot
+          # name a parent collection it cannot resolve.
+          raise UnsupportedEmbedding.new(
+            "MongoidSchemaGenerator: '#{model.name}' (collection '#{model.collection_name}') " \
+            "declares `embedded_in :#{assoc.name}` whose parent class cannot be resolved " \
+            "(#{e.message.lines.first&.strip}). Fix the association's class_name, or define the " \
+            "collection's config by hand.",
+            reason: "has an embedded_in :#{assoc.name} whose parent class is unresolvable",
+          )
+        end
 
       # A self-referential / cyclic `embedded_in` — Mongoid's
       # `recursively_embeds_many` / `recursively_embeds_one` (which declare a
@@ -216,19 +295,47 @@ module Exwiw
       # `MongodbAdapter#dumpable?` (`!embedded?`) would silently never dump the
       # collection's root documents. Fail loudly instead.
       if parent.collection_name.to_s == model.collection_name.to_s
-        raise ArgumentError,
-              "MongoidSchemaGenerator: '#{model.name}' (collection '#{model.collection_name}') " \
-              "declares a self-referential (cyclic) `embedded_in :#{assoc.name}` that embeds the " \
-              "collection inside documents of its own type (e.g. `recursively_embeds_many` / " \
-              "`recursively_embeds_one`). " \
-              "exwiw represents a collection as either top-level or embedded, not both, so this " \
-              "cannot be expressed as an exwiw `embedded_in` config. Define the collection's config " \
-              "by hand."
+        raise UnsupportedEmbedding.new(
+          "MongoidSchemaGenerator: '#{model.name}' (collection '#{model.collection_name}') " \
+          "declares a self-referential (cyclic) `embedded_in :#{assoc.name}` that embeds the " \
+          "collection inside documents of its own type (e.g. `recursively_embeds_many` / " \
+          "`recursively_embeds_one`). " \
+          "exwiw represents a collection as either top-level or embedded, not both, so this " \
+          "cannot be expressed as an exwiw `embedded_in` config. Define the collection's config " \
+          "by hand.",
+          reason: "has a self-referential (cyclic) embedded_in :#{assoc.name}",
+        )
       end
 
       # `store_as` defaults to the relation name and is the actual document key
       # the subdocuments are stored under inside the immediate parent.
-      parent_relation = parent.relations[assoc.inverse.to_s]
+      parent_relation =
+        begin
+          parent.relations[assoc.inverse.to_s]
+        rescue ::Mongoid::Errors::MongoidError, NameError => e
+          # e.g. AmbiguousRelationship: the embedded class is embedded under
+          # several document keys in the parent (or otherwise has no single
+          # resolvable inverse), so exwiw cannot pick the one path it lives under.
+          raise UnsupportedEmbedding.new(
+            "MongoidSchemaGenerator: '#{model.name}' (collection '#{model.collection_name}') " \
+            "declares `embedded_in :#{assoc.name}` whose inverse on '#{parent.name}' is ambiguous " \
+            "or unresolvable (#{e.class}: #{e.message.lines.first&.strip}). Add an `inverse_of:` to " \
+            "disambiguate, or define the collection's config by hand.",
+            reason: "has an embedded_in :#{assoc.name} with an ambiguous/unresolvable inverse",
+          )
+        end
+
+      unless parent_relation
+        # `assoc.inverse` resolved to a name that is not an association on the
+        # parent (or to nothing), so there is no document key to embed under.
+        raise UnsupportedEmbedding.new(
+          "MongoidSchemaGenerator: '#{model.name}' (collection '#{model.collection_name}') " \
+          "declares `embedded_in :#{assoc.name}` but its inverse relation could not be located on " \
+          "'#{parent.name}' (the embedding document key is indeterminable). Add an `inverse_of:`, or " \
+          "define the collection's config by hand.",
+          reason: "has an embedded_in :#{assoc.name} whose inverse relation could not be located",
+        )
+      end
 
       { collection_name: parent.collection_name.to_s, path: parent_relation.store_as }
     end

data/lib/exwiw/version.rb

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

data/lib/tasks/exwiw.rake

@@ -32,11 +32,17 @@ namespace :exwiw do
     end
 
     desc "Generate schema from a Mongoid application"
+    # Set EXWIW_SKIP_UNSUPPORTED=1 to keep generation going past constructs exwiw
+    # cannot represent (an unresolvable `belongs_to`, or a polymorphic / cyclic /
+    # unresolvable `embedded_in`): the unresolvable belongs_to is skipped and an
+    # unrepresentable embedded collection is emitted as `ignore: true` with a
+    # `comment`, each warned to stderr, instead of aborting the whole run.
     task generate_mongoid: :environment do
       require "exwiw"
 
       Exwiw::MongoidSchemaGenerator.from_rails_application(
         output_dir: ENV["OUTPUT_DIR_PATH"] || "exwiw",
+        skip_unsupported: ENV["EXWIW_SKIP_UNSUPPORTED"] == "1",
       ).generate!
     end
   end

metadata

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