exwiw 0.4.10 → 0.4.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a89e3da8899badc5bcccc98f58878744b9b106b31ca38af6a70b41109002d126
-  data.tar.gz: 13dd0757b0699c7865cd4c89b214288d16d017a9447c042e90c3da5cedc6f4b2
+  metadata.gz: 23b64ea4c8b3562427b3e605fc17dec1251cf6916f2be02aeed0b3a29e03a62d
+  data.tar.gz: ce8a51a31bb84c22abd164e3ec928065dff99f1dbd6eb83c72a9520e8c7e0737
 SHA512:
-  metadata.gz: b04b7e070c1215b24c6dfa6453e572bf560d77fbd9a6eb6172fbd301a8b662ebc1da815f13d5fb4ba31799a5e8e45c610c0271e810eff6c8c675e75fcf261e2d
-  data.tar.gz: 4b88cfc7ed7a758b7a82b76d9e936c251b388825411fef9c305434919b7695f6866e5011828a6a2bf00c95692d157c1f0e4e768e0dc3e9ab79b980f025e4c626
+  metadata.gz: 779684b310965b1f59a7d9bb20d20d61526435845c1c3c5d7b6a6e1c7febcb96ce82d12ebf22bcb894546d8dd9f876984d302a87a2e321a1fb3aa8de8aeb4447
+  data.tar.gz: e19d3931e974e09487e6a661e482cdeac9cf665e34d80dc82ed9fff6f099ffa7cf0a2a8fec2b7f682b301899f9121f3c6fd49680fe0a70fb300bb04d7b9c9f78

data/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [0.4.11] - 2026-06-15
+
+### Fixed
+
+- MongoDB: `schema:generate_mongoid` now resolves an embedded collection's `embedded_in` document key by locating the parent's `embeds_one` / `embeds_many` that stores the collection, instead of trusting Mongoid's computed `assoc.inverse`. Mongoid returns a `nil` inverse for many valid embeddings (when no explicit `inverse_of:` is declared and it declines to infer one), and previously such a model was wrongly reported as having an "unresolvable inverse" and skipped (or aborted the run). Matching by the embedded collection also resolves an STI subclass embedded through a relation declared against its base class. Genuinely ambiguous embeddings (the same collection stored under several keys in the parent) are still reported as unrepresentable.
+
+### Added
+
+- MongoDB: `schema:generate_mongoid` now **honors an explicit `ignore: true` on disk** and skips re-introspecting it, so a construct exwiw cannot represent that you have already triaged no longer aborts the (fail-loud, default) run — and the annotation survives regeneration. Works at two granularities: a whole **collection** marked `ignore: true` is preserved as-is without introspection, and a single **`belongs_to`** marked `ignore: true` (no `table_name` required) is preserved while the rest of its collection still generates and dumps (its foreign-key column stays an ordinary field). This lets you keep the generator strict by default while opting individual stale/unrepresentable constructs out by hand, rather than relying on `EXWIW_SKIP_UNSUPPORTED`.
+- `MongodbCollectionConfig` and `BelongsTo` gain an optional, user-owned **`ignore_type`** tag (free-form; exwiw never interprets or emits it) to record *why* something is ignored — e.g. `"need_code_fix"` for an application-side bug, `"unsupported"` for a shape exwiw cannot express. Preserved across regeneration like `comment`. `BelongsTo#table_name` is now optional so an ignored, no-longer-resolvable relation can be recorded without a target collection (a non-ignored `belongs_to` still requires one).
+
 ## [0.4.10] - 2026-06-12
 
 ### Fixed

data/README.md

@@ -194,20 +194,53 @@ It is a distinct task and class (`Exwiw::MongoidSchemaGenerator`) from the Activ
 - the collection name and the `_id` primary key,
 - `fields` from the declared Mongoid fields (referenced `belongs_to` foreign keys such as `shop_id`, and the `created_at` / `updated_at` columns added by `Mongoid::Timestamps`, are ordinary fields — their BSON `ObjectId` / `Date` values serialize as MongoDB Extended JSON at dump time). For an aliased field (`field :ctry, as: :country`), the generator emits the **stored** document key (`ctry`), never the Ruby accessor (`country`), so masking and projection target the key that actually appears in the document, and additionally records the accessor as `mongoid_field_name` on that field so the short key stays understandable (association aliases such as `shop => shop_id` and the built-in `id => _id` are not field renames and are not annotated),
 - `belongs_tos` from referenced `belongs_to` associations (`{ table_name, foreign_key }`). A referenced `belongs_to` declared on an *embedded* document is dropped (cross-collection refs from inside embedded subdocuments are unsupported — see [MongoDB notes](#mongodb-notes)), but its foreign-key column is still kept as an ordinary field. A `has_and_belongs_to_many` association is also dropped (its foreign keys are stored as an array field, e.g. `tag_ids`, which exwiw cannot follow as a single-valued foreign key), while that `*_ids` array column is kept as an ordinary field,
-- `embedded_in` from `embedded_in` / `embeds_many` / `embeds_one` associations. Each embedded config names its *immediate* parent collection and the document key it lives under (`store_as`, defaulting to the relation name); nested embedding is represented as a chain (`comments` → `embedded_in` `posts`, `posts` → `embedded_in` `users`) rather than a flattened dot-path, matching how the adapter recurses through array and Hash subdocuments. A *polymorphic* `embedded_in` (`embedded_in :addressable, polymorphic: true`) has no single embedding parent collection and so cannot be expressed as an `embedded_in` config; the generator raises a clear error pointing you to define that collection's config by hand. A *self-referential / cyclic* embedding (Mongoid's `recursively_embeds_many` / `recursively_embeds_one`) makes a collection both a top-level document and embedded inside documents of its own type; exwiw represents a collection as either top-level or embedded, not both, so the generator likewise raises a clear error rather than emit a config that would silently make the collection undumpable.
+- `embedded_in` from `embedded_in` / `embeds_many` / `embeds_one` associations. Each embedded config names its *immediate* parent collection and the document key it lives under (`store_as`, defaulting to the relation name); nested embedding is represented as a chain (`comments` → `embedded_in` `posts`, `posts` → `embedded_in` `users`) rather than a flattened dot-path, matching how the adapter recurses through array and Hash subdocuments. The document key is resolved by locating the parent's `embeds_one` / `embeds_many` that stores this collection. (Mongoid's computed inverse is frequently `nil` when no explicit `inverse_of:` is set, so exwiw matches by the collection the parent's embedding relations store rather than trusting that inverse — this also resolves an STI subclass embedded through a relation declared against its base class.) When the same collection is embedded under several keys in the parent, the path is ambiguous and treated as unrepresentable (see below). A *polymorphic* `embedded_in` (`embedded_in :addressable, polymorphic: true`) has no single embedding parent collection and so cannot be expressed as an `embedded_in` config. A *self-referential / cyclic* embedding (Mongoid's `recursively_embeds_many` / `recursively_embeds_one`) makes a collection both a top-level document and embedded inside documents of its own type; exwiw represents a collection as either top-level or embedded, not both, so it cannot emit an `embedded_in` config that would silently make the collection undumpable. These unrepresentable shapes are handled best-effort by default and abort only in strict mode (see below).
 
 Models in an inheritance hierarchy whose subclasses share the base's collection (Mongoid STI, distinguished by the auto-added `_type` discriminator) collapse into a single config: the generator discovers the subclasses via `descendants` (Mongoid registers only the base class in `Mongoid.models`) and unions every class's `fields` and `belongs_tos` into the collection config, so subclass-only fields and associations are not lost.
 
 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:
+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 / ambiguous / unresolvable-parent `embedded_in` (see the cases above).
+
+#### Honoring an explicit `ignore` (the recommended way to keep these out)
+
+When you have reviewed such a construct and decided exwiw should leave it alone, mark it `ignore: true` in its config on disk. The generator **honors an explicit `ignore` and skips re-introspecting it**, so it never aborts the run on something you have already triaged — and your annotation survives regeneration. Two granularities:
+
+- A whole **collection** exwiw cannot represent (e.g. a polymorphic / ambiguous `embedded_in`) — mark the collection config `"ignore": true`. To actually dump/mask it later, define its `embedded_in` config by hand (see [Embedded documents](#embedded-documents)).
+- A single **`belongs_to`** that no longer resolves while the rest of its collection is fine (e.g. a stale relation pointing at a removed model) — mark that entry `"ignore": true`, with no `table_name`. The relation is dropped from extraction (`#reject_ignored_members!`) while its foreign-key column stays an ordinary field, and the collection keeps dumping.
+
+Record *why* with the optional **`ignore_type`** (a free-form tag exwiw never interprets — e.g. `"need_code_fix"` for an application-side bug, `"unsupported"` for a shape exwiw cannot express) and a **`comment`**. Both are user-owned and preserved across regeneration; the generator never emits `ignore_type` itself.
+
+```json
+// orders.json — a stale belongs_to flagged for a code fix; the collection still dumps
+{
+  "name": "orders",
+  "primary_key": "_id",
+  "belongs_to": [
+    { "table_name": "shops", "foreign_key": "shop_id" },
+    {
+      "foreign_key": "coupon_id",
+      "ignore": true,
+      "ignore_type": "need_code_fix",
+      "comment": "FIXME: belongs_to :coupon -> Coupon does not exist (dead relation)."
+    }
+  ],
+  "fields": [ /* ... coupon_id is kept as an ordinary field ... */ ]
+}
+```
+
+#### First bootstrap pass: `EXWIW_SKIP_UNSUPPORTED=1`
+
+For the very first pass against a large app — before any `ignore` annotations exist — set `EXWIW_SKIP_UNSUPPORTED=1` to keep going past *un-annotated* unrepresentable constructs instead of aborting one at a time:
 
 ```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.
+- 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.
+
+Review the stderr warnings, annotate the affected configs (`ignore` / `ignore_type` / `comment`), and subsequent runs complete without the flag because the generator honors those explicit ignores.
 
 ### Configuration
 

data/lib/exwiw/belongs_to.rb

@@ -5,7 +5,11 @@ module Exwiw
     include Serdes
 
     attribute :foreign_key, String
-    attribute :table_name, String
+    # Optional so an ignored, no-longer-resolvable relation (a stale
+    # `belongs_to` whose target class is gone) can be recorded with no target
+    # collection. A non-ignored belongs_to still requires it — enforced by the
+    # owning config's validation (e.g. MongodbCollectionConfig#validate_belongs_tos!).
+    attribute :table_name, optional(String), skip_serializing_if_nil: true
     # Set only for a polymorphic association. `foreign_type` is the name of the
     # column storing the type (e.g. `reviewable_type`), and `type_value` is the
     # value held in that column (e.g. `"Product"`). Both are nil for a
@@ -32,6 +36,11 @@ module Exwiw
     # extraction once the config is loaded (see #reject_ignored_members!).
     attribute :comment, optional(String), skip_serializing_if_nil: true
     attribute :ignore, Serdes::OptionalType.new(Serdes::ConcreteType.new(Boolean)), skip_serializing_if_nil: true
+    # Free-form tag recording *why* this relation is ignored (e.g.
+    # "need_code_fix" for an application-side bug, "unsupported" for a shape
+    # exwiw cannot express). exwiw never interprets or emits it; purely
+    # informational and preserved across regeneration like `comment`.
+    attribute :ignore_type, optional(String), skip_serializing_if_nil: true
 
     def self.from_symbol_keys(hash)
       from(hash.transform_keys(&:to_s))

data/lib/exwiw/mongodb_collection_config.rb

@@ -20,6 +20,11 @@ module Exwiw
     # marks an unrepresentable collection `ignore: true`, to record why extraction
     # was skipped.
     attribute :comment, optional(String), skip_serializing_if_nil: true
+    # Free-form tag recording *why* this collection is ignored (e.g.
+    # "need_code_fix" for an application-side bug, "unsupported" for a shape
+    # exwiw cannot express). exwiw never interprets or emits it; informational
+    # and preserved across regeneration like `comment`.
+    attribute :ignore_type, 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
@@ -30,6 +35,7 @@ module Exwiw
     def self.from(obj)
       instance = super
       instance.__send__(:validate_embedded!)
+      instance.__send__(:validate_belongs_tos!)
       instance
     end
 
@@ -68,6 +74,7 @@ module Exwiw
         merged.filter = filter
         merged.bulk_insert_chunk_size = bulk_insert_chunk_size
         merged.ignore = ignore
+        merged.ignore_type = ignore_type
         # 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.
@@ -84,6 +91,7 @@ module Exwiw
           if receiver_bt
             pbt.comment = receiver_bt.comment if receiver_bt.comment
             pbt.ignore = receiver_bt.ignore unless receiver_bt.ignore.nil?
+            pbt.ignore_type = receiver_bt.ignore_type if receiver_bt.ignore_type
             pbt.references = receiver_bt.references if receiver_bt.references
           end
           pbt
@@ -114,5 +122,18 @@ module Exwiw
             "belongs_tos must be empty (cross-collection refs from inside embedded arrays " \
             "are not supported)."
     end
+
+    # `table_name` is optional only so an *ignored* relation (a stale belongs_to
+    # whose target collection no longer exists) can be recorded without one. A
+    # belongs_to that still participates in extraction must name its target.
+    private def validate_belongs_tos!
+      offender = belongs_tos.find { |bt| bt.table_name.nil? && !bt.ignore }
+      return unless offender
+
+      raise ArgumentError,
+            "MongodbCollectionConfig '#{name}' has a belongs_to (foreign_key " \
+            "'#{offender.foreign_key}') with no table_name; only an `ignore: true` belongs_to " \
+            "may omit it."
+    end
   end
 end

data/lib/exwiw/mongoid_schema_generator.rb

@@ -49,7 +49,7 @@ module Exwiw
     end
 
     def generate!
-      collections = build_collections
+      collections = build_collections(existing_configs_by_name(@output_dir))
       write_files(@output_dir, collections)
       collections
     end
@@ -61,11 +61,33 @@ module Exwiw
     # subclasses share the base's collection (Mongoid STI, discriminated by the
     # auto-added `_type` field) collapses into a single config that aggregates
     # every class's fields and associations. See `expand_with_descendants`.
-    def build_collections
+    #
+    # `existing_by_name` maps a collection name to its config already on disk, so
+    # the build can honor an explicit `ignore: true` (collection- or
+    # belongs_to-level) without re-introspecting it — and thus without aborting
+    # on a construct the user has deliberately ignored. Empty (the default) when
+    # called directly without an output dir, in which case nothing is honored.
+    def build_collections(existing_by_name = {})
       models = expand_with_descendants(concrete_models)
       models
         .group_by { |model| model.collection_name.to_s }
-        .map { |collection_name, group| build_collection_for(collection_name, group) }
+        .map { |collection_name, group| build_collection_for(collection_name, group, existing_by_name[collection_name]) }
+    end
+
+    # Loads the configs already on disk so the generator can honor an explicit
+    # `ignore: true` without re-introspecting (and thus without aborting on a
+    # construct the user has deliberately ignored). A file that cannot be read or
+    # parsed is skipped — a fresh run simply has none, and write_files surfaces
+    # genuine problems when it later merges/rewrites.
+    private def existing_configs_by_name(dir)
+      return {} unless dir && File.directory?(dir)
+
+      Dir[File.join(dir, "*.json")].each_with_object({}) do |path, acc|
+        config = MongodbCollectionConfig.from(JSON.parse(File.read(path)))
+        acc[config.name] = config
+      rescue JSON::ParserError, ArgumentError
+        next
+      end
     end
 
     def write_files(dir, collections)
@@ -88,7 +110,15 @@ module Exwiw
     # belongs_tos are unioned across the group; processing least-derived first
     # keeps the base's fields leading the list and the output deterministic
     # regardless of input order or sibling subclasses.
-    private def build_collection_for(collection_name, models)
+    private def build_collection_for(collection_name, models, existing = nil)
+      # An explicit on-disk `ignore: true` means the user has triaged this
+      # collection and asked exwiw to leave it alone: preserve their config
+      # (ignore_type / comment intact) and skip introspection entirely, so a
+      # construct exwiw cannot represent never aborts a run the user has already
+      # accounted for. (A collection is never dumped while ignored, so its
+      # fields/structure need not track the model.)
+      return existing if existing&.ignore
+
       ordered = models.sort_by { |model| [model.fields.size, model.name] }
 
       attrs = {
@@ -128,7 +158,7 @@ module Exwiw
           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)
+        attrs[:belongs_tos] = aggregate_belongs_tos(ordered, existing)
       end
 
       MongodbCollectionConfig.from_symbol_keys(attrs)
@@ -200,7 +230,9 @@ module Exwiw
       end
     end
 
-    private def aggregate_belongs_tos(models)
+    private def aggregate_belongs_tos(models, existing = nil)
+      ignored_by_fk = ignored_belongs_tos_by_foreign_key(existing)
+
       belongs_to_assocs = models.flat_map do |model|
         model.relations.values.select do |assoc|
           assoc.is_a?(::Mongoid::Association::Referenced::BelongsTo)
@@ -216,10 +248,22 @@ module Exwiw
       # same belongs_to twice, so uniq them.
       belongs_to_assocs
         .reject(&:polymorphic?)
-        .filter_map { |assoc| belongs_to_for(assoc) }
+        .filter_map { |assoc| belongs_to_for(assoc, ignored_by_fk) }
         .uniq
     end
 
+    # Maps foreign_key -> the on-disk `ignore: true` belongs_to entry, so a
+    # relation the user has explicitly ignored is preserved verbatim instead of
+    # re-resolved (which, for a stale relation whose target class is gone, would
+    # otherwise abort the run).
+    private def ignored_belongs_tos_by_foreign_key(existing)
+      return {} unless existing
+
+      existing.belongs_tos.select(&:ignore).each_with_object({}) do |bt, acc|
+        acc[bt.foreign_key] = bt
+      end
+    end
+
     # Resolves a referenced belongs_to to a `{ table_name, foreign_key }` pair
     # (plus `references` when the FK points at a non-`_id` parent field).
     # `assoc.klass` raises NameError when the association's target class no longer
@@ -227,7 +271,18 @@ module Exwiw
     # 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)
+    #
+    # `ignored_by_fk` carries the on-disk `ignore: true` belongs_to entries: when
+    # this relation's foreign key is among them, the user has explicitly ignored
+    # it, so preserve their entry verbatim (its `ignore_type` / `comment`) without
+    # resolving the — possibly gone — target. The relation is dropped from
+    # extraction at load (`#reject_ignored_members!`) while its FK column stays a
+    # field, and the run never aborts on a relation already triaged.
+    private def belongs_to_for(assoc, ignored_by_fk = {})
+      if (ignored = ignored_by_fk[assoc.foreign_key])
+        return preserve_ignored_belongs_to(ignored)
+      end
+
       result = { table_name: assoc.klass.collection_name.to_s, foreign_key: assoc.foreign_key }
       # Mongoid's `belongs_to ..., primary_key: :uuid` makes the child's foreign
       # key reference that parent field rather than the parent's `_id`. Surface
@@ -245,6 +300,21 @@ module Exwiw
       nil
     end
 
+    # Re-emits a user's on-disk ignored belongs_to as a symbol-keyed hash (the
+    # shape `build_collection_for` feeds to `from_symbol_keys`), carrying its
+    # `ignore` / `ignore_type` / `comment` (and `table_name` / `references` when
+    # present) so the annotation survives regeneration untouched.
+    private def preserve_ignored_belongs_to(bt)
+      {
+        table_name: bt.table_name,
+        foreign_key: bt.foreign_key,
+        references: bt.references,
+        ignore: true,
+        ignore_type: bt.ignore_type,
+        comment: bt.comment,
+      }.compact
+    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
@@ -317,31 +387,17 @@ module Exwiw
         )
       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 =
-        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
+      # Resolve the document key (`store_as`, defaulting to the relation name)
+      # the subdocuments live under inside the parent.
+      parent_relation = embedding_relation_in(parent, assoc, model)
 
       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.
+        # No embeds_one / embeds_many on the parent stores this collection, 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 " \
+          "declares `embedded_in :#{assoc.name}` but no embeds_one/embeds_many on '#{parent.name}' " \
+          "stores this collection (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",
         )
@@ -350,6 +406,64 @@ module Exwiw
       { collection_name: parent.collection_name.to_s, path: parent_relation.store_as }
     end
 
+    # Locates the parent's `embeds_one` / `embeds_many` association that stores
+    # this embedded collection — i.e. the document key the subdocuments live
+    # under. Mongoid's computed `assoc.inverse` is preferred when it resolves
+    # cleanly, but it is frequently `nil` (no explicit `inverse_of:` and Mongoid
+    # declines to infer one) or raises `AmbiguousRelationship`; in those cases
+    # fall back to matching the parent's embedding relations by the collection
+    # they store. This resolves the common single-embedding case that
+    # `assoc.inverse` cannot (e.g. an `embeds_one :force_logout` / `embedded_in
+    # :customer` pair with no inverse_of). Returns the relation, `nil` when none
+    # stores this collection, and raises `UnsupportedEmbedding` when several
+    # distinct keys do (genuinely ambiguous — exwiw cannot pick one).
+    private def embedding_relation_in(parent, assoc, model)
+      inverse_name =
+        begin
+          assoc.inverse
+        rescue ::Mongoid::Errors::MongoidError, NameError
+          nil
+        end
+
+      if inverse_name
+        rel = parent.relations[inverse_name.to_s]
+        return rel if rel
+      end
+
+      candidates = parent.relations.values.select do |rel|
+        (rel.is_a?(::Mongoid::Association::Embedded::EmbedsMany) ||
+          rel.is_a?(::Mongoid::Association::Embedded::EmbedsOne)) &&
+          embeds_collection?(rel, model)
+      end
+      paths = candidates.map(&:store_as).uniq
+
+      if paths.size > 1
+        # The same collection is embedded under several document keys in the
+        # parent, so `embedded_in :#{assoc.name}` has no single resolvable path.
+        raise UnsupportedEmbedding.new(
+          "MongoidSchemaGenerator: '#{model.name}' (collection '#{model.collection_name}') " \
+          "is embedded under multiple document keys (#{paths.join(', ')}) in '#{parent.name}', so its " \
+          "`embedded_in :#{assoc.name}` is ambiguous or unresolvable — exwiw cannot pick the single path " \
+          "it lives under. 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
+
+      candidates.first
+    end
+
+    # True when `rel` (an embeds_one / embeds_many on the parent) stores the same
+    # collection as `model`. Comparing collection names (rather than class
+    # identity) also matches an STI subclass embedded through a relation declared
+    # against its base class, since both share the base's collection. A sibling
+    # embedding relation whose target class no longer resolves is treated as a
+    # non-match rather than blowing up the whole derivation.
+    private def embeds_collection?(rel, model)
+      rel.klass.collection_name.to_s == model.collection_name.to_s
+    rescue NameError, ::Mongoid::Errors::MongoidError
+      false
+    end
+
     private def embedded_in_association(model)
       model.relations.values.find do |assoc|
         assoc.is_a?(::Mongoid::Association::Embedded::EmbeddedIn)

data/lib/exwiw/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Exwiw
-  VERSION = "0.4.10"
+  VERSION = "0.4.11"
 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
+    # Fail-loud by default: the task aborts on a construct exwiw cannot represent
+    # (an unresolvable `belongs_to`, or a polymorphic / cyclic / ambiguous /
+    # unresolvable `embedded_in`). To keep a deliberately-unrepresentable
+    # collection or relation from aborting the run, mark it `ignore: true` in its
+    # config on disk (optionally with an `ignore_type` / `comment` recording why);
+    # the generator honors that and skips re-introspecting it. Set
+    # EXWIW_SKIP_UNSUPPORTED=1 to additionally keep going past *un-annotated*
+    # unrepresentable constructs (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.
+    # `comment`, each warned to stderr) — useful for the first bootstrap pass
+    # against a large app before the ignores are written.
     task generate_mongoid: :environment do
       require "exwiw"
 

metadata

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