exwiw 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 568620ee295b1822c2606a42be450bbe5601aabb874606b6773b72619261cbba
-  data.tar.gz: 46f7b6f97c6b77b7046dfb19117734286ecb5d88001214f9d6e1995560f0b50a
+  metadata.gz: a743c4759cdb8b292e4fdfe8ea3d4e10fa66e15a70677dd685366fb9e26a376b
+  data.tar.gz: '04048ceca802c0d418495cdf7c002bd47047beb05a53655a451c2c77a4d8270d'
 SHA512:
-  metadata.gz: 8800c7adfa78ea01fb513eb3dbbe2b3fbfa98b13916d5b4e5a205232851b73e1bbef8cd9d0190abe5a9375d073c753d2f92be583c3a2a96d898cb757cd883a0a
-  data.tar.gz: 02f0ebd17ed423dfffbba3aefe2fbba01b533c23672d680ccce7c21edf2b36dbfc0c66ee72b8f4433af3af643aaea126861233a99d2222a2d347f407c8ab5c27
+  metadata.gz: 7d7a5ffca1cdae405e88fac5d72e4ed4e52ee3deec8cce0e503dcdc2b4136ec03ca2d84893c5897a3e56a78b0fa9e11dddc5f606566f32c90297815c8ade4702
+  data.tar.gz: 8e7742f720c371b41679c311d6323f8182e4f414f1ff199ac90928026ce46c2607a61a3c3a7ed91c23c97ea4b855d838bfee38b593d69c06f1dc743a17916eb0

data/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [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

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/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.4.0"
+  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.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Shia