exwiw 0.9.22 → 0.9.24

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3abd99db26266c75e79f46cd0fc14a2a0344308031422385ca22dd2a77ab0130
-  data.tar.gz: 9c78446793e1c91947bcf7aa6b933d623c87d004d84fbcb3df8b86886e136482
+  metadata.gz: 73740836024ec336feb7138c5a94e396df206de932de00737404d556fc403e0a
+  data.tar.gz: de53ac3f5e4c93f6761524041261c2becb65baa9bd396e528ca0ffa9b82b518e
 SHA512:
-  metadata.gz: 0406c29183e0a896ae9de40e24622239caa4cf06b898784d1aa24633d479b0e4ee5717f8d755e5c323af1dd290e18e92f201f4d2ac6f192feb71e9c1a947eee2
-  data.tar.gz: 63e754207a3c08d97d9b9ceed684b5e112c770c02e9638dd80e9ba958fd1d9ecc96784e6d0431cb27c818e254177d62b506ea587fc1ba55d7068125c889a7fd2
+  metadata.gz: ac457715cf1eaf521840903e2b2fbb6c5f503230d0abfb7cc24510067c2aa68c8b841d370d8eeed3e0c0ee009a105bea87cfe455a21c50b5bd462feb48c14f22
+  data.tar.gz: 945c4c46077e9ee6678f6fbc6e72b13186e393c4f06035dd1e9d63f10efa3c1fe6adb67a05f470e1330a48d5d8f34d008c67cb8795ba7dbda8294178f13082a0

data/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [0.9.24] - 2026-08-17
+
+### Fixed
+
+- **MongoDB: `ignore: true` is now honored on embedded configs instead of silently exporting the subdocuments raw.** An ignored embedded config keeps its path out of the parent's projection, so the whole subdocument is absent from the dump ([docs/mongodb.md](docs/mongodb.md#excluding-an-embedded-path-ignore-true)); an ignored *field* of an embedded config is deleted from each subdocument before masking runs, as on a top-level collection. That deletion also fixes a leak there: an ignored field a child `references` is fetched as a propagation key and used to be exported. A primary key marked `ignore: true` — previously a silent no-op — now raises `ArgumentError` on load: dropping `_id` would make a restore assign fresh ids and break every reference pointing at the documents.
+
+## [0.9.23] - 2026-08-13
+
+### Fixed
+
+- **A collection stored into by both a top-level and an embedded model is now generated as the top-level collection it is, instead of silently ceasing to be dumped.** `MongoidSchemaGenerator` treated a collection group as embedded as soon as *any* model in it was — and an embedded class's collection name derives from its class name alone, so it collides with any top-level model that stores into a collection of that name, with nothing declaring the two to be related and neither side wrong. The emitted config then carried an `embedded_in` and an empty `belongs_tos`, with three consequences: `MongodbAdapter#dumpable?` (`!embedded?`) silently never dumped the collection's root documents; the top-level models' `belongs_tos` — the extraction paths that reach everything scoped below them — disappeared from the config; and a hand-maintained top-level config could not survive regeneration either, because `MongodbCollectionConfig#merge` always takes the freshly generated `embedded_in`, so `schema:check_mongoid` reported that file as changed on every run with no way to resolve it. Such a collection is genuinely top-level — it has root documents that must be dumped — so it is now built from its **root** models alone (their fields, their `belongs_tos`, and safe mode's structural/unique sets), with no `embedded_in`, and the collision is named on stderr instead: the embedded documents of the same name are **not** covered by that config and are masked, as before, through a config written by hand with an `embedded_in` and a name of its own (generation and `tidy_mongoid` both leave `embedded_in` configs alone, so such a file is stable). The collision is deliberately *not* recorded as a generated `comment` on the config, since a generated comment wins the merge and would overwrite — on every run — the note a user wrote about this very situation. Only a *root* model counts as evidence of a root collection, which is the second shape this distinguishes: an **embedded family under a plain base class** (`Address` holding the shared fields and declaring no `embedded_in`, `BillingAddress < Address` declaring one and inheriting the collection name) is not mixed at all. `embedded?` answers "does this class declare an `embedded_in`", not "does this collection have root documents", and a shared base stores nothing at the root — its fields describe subdocuments. Such a family keeps generating exactly the embedded config it always did (the same field union, in the same order, with the embedding derived from a class that actually declares one), because flipping it to a top-level config would delete the config masking those subdocuments: the same worst-case failure in the opposite direction. A non-embedded model whose embedded descendants are in the group is therefore always read as their base class, conservatively so even if the application also stored root documents under it — that keeps the behavior (and the limitation) the generator always had rather than trading a silent masking regression for a silent dumping one. Collections stored into only by top-level models, or only by embedded ones, are unaffected, including the unrepresentable embedding shapes that abort or, under `EXWIW_SKIP_UNSUPPORTED=1`, emit an `ignore: true` config. Related: a model declared `store_in collection: nil` — how an application says a document class is never persisted and only wants Mongoid's casting — is now skipped entirely instead of contributing to a config for the nameless group every such class collapses into, which describes nothing and, as a top-level config, would instruct the dump to read a collection with no name. They are dropped where the generator selects the models it describes, so they leave `tidy_mongoid`'s live-collection set as well.
+
 ## [0.9.22] - 2026-08-13
 
 ### Added

data/README.md

@@ -683,6 +683,7 @@ Constraints:
 - If another non-ignored table has a `belongs_to` entry pointing at an ignored table, exwiw raises `ArgumentError` on load. Remove the `belongs_to` entry on the referencing table, or unset `ignore` on the referenced table.
 - Specifying an ignored table as `--target-table` raises `ArgumentError`.
 - `ignore: true` is preserved by `exwiw:schema:generate` regenerations (the receiver value wins over the auto-generated config).
+- On a MongoDB [embedded config](docs/mongodb.md#excluding-an-embedded-path-ignore-true), which is masked through its parent rather than dumped on its own, `ignore: true` excludes the embedded path from the parent's projection — the subdocument is left out of the dump entirely.
 
 ### Ignore / annotate a column or `belongs_to`
 
@@ -706,6 +707,8 @@ Individual `columns` (SQL) / `fields` (MongoDB) and `belongs_tos` entries accept
 }
 ```
 
+On a MongoDB [embedded config](docs/mongodb.md#embedded-documents) an ignored field cannot be left out of the query — the subdocuments arrive as part of whatever the parent collection fetched — so it is removed from each subdocument during masking instead. The result is the same: the field is absent from the dump. A MongoDB config marking its primary key `ignore: true` is rejected on load — the dump has to keep the identifier, or a restore would assign fresh ids and break every reference pointing at the documents.
+
 The ignored entries are removed only at runtime, right after the config is loaded from file; the JSON on disk keeps them. Both `comment` and `ignore` are **preserved across `exwiw:schema:generate` / `exwiw:mongoid:schema:generate` regenerations** (the hand-edited value wins over the auto-generated config), just like `replace_with`. This applies to the MongoDB `MongodbCollectionConfig` (`fields` / `belongs_tos`) as well.
 
 ### `needs_mask_decision`

data/docs/mongodb.md

@@ -38,6 +38,7 @@ exwiw can export a MongoDB database with `--adapter=mongodb`. This document coll
 
 - `replace_with_fake_data` is supported on a field ([full reference](../README.md#replace_with_fake_data)) — its `seed` names a field of the same collection (bare or `collection.`-qualified) or the primary key (`_id`), and it derives the same fake value as the SQL adapters for the same seed. It is applied document-side after `replace_with` (so a fake seed reads the already-masked value, matching the SQL adapters where `replace_with` runs in the database first), works inside embedded subdocuments, and is exclusive with `replace_with` on the same field. Add `gem "faker"` to use it (except a config using only `ja` person types). `raw_sql` and `map` are **not** supported (the `MongodbField` schema does not declare them; such keys are rejected on load — see [Unknown keys are rejected](../README.md#unknown-keys-are-rejected)); use `replace_with` for template masking.
 - The MongoDB adapter does not support the collection-level `filter` field (it raises `NotImplementedError` if set, since the SQL-string filter cannot be applied to MongoDB).
+- A field marked [`ignore: true`](../README.md#ignore--annotate-a-column-or-belongs_to) is absent from the dump on an embedded config too, though it gets there differently: a top-level collection's ignored field is left out of the projection (unless a child references it — then it is fetched as a propagation key and dropped during masking too), while an embedded one arrives inside the parent's document and is deleted from the subdocument during masking. It is deleted before the collection's own `replace_with` / `replace_with_fake_data` run, so — as on a top-level collection — nothing masking the same subdocument can read it. The primary key cannot be marked `ignore: true` (that raises `ArgumentError` on load): dropping it would leave the dumped documents with no identifier, so a restore would assign fresh ids and break every reference pointing at them.
 
 ## `reverse_scope` on collections
 
@@ -107,6 +108,30 @@ At runtime:
 - Cross-collection references from inside an embedded subdocument (`belongs_tos` on an embedded config) are not supported and raise `ArgumentError` on load.
 - Specifying an embedded config as `--target-table` raises `NotImplementedError`; pass the top-level collection name instead.
 
+### Excluding an embedded path (`ignore: true`)
+
+A parent collection fetches an embedded path only because some config claims it, so marking the embedded config [`ignore: true`](../README.md#ignore-a-table) leaves the path out of the parent's projection: the **whole subdocument is absent from the dump**, and any embedded chain hanging off it goes with it.
+
+```jsonc
+// posts is embedded in users.posts, but its content is not wanted in the dump
+{
+  "name": "posts",
+  "primary_key": "_id",
+  "ignore": true,
+  "comment": "subdocument is environment-specific; drop it rather than mask it",
+  "embedded_in": { "collection_name": "users", "path": "posts" },
+  "belongs_tos": [],
+  "fields": [{ "name": "_id" }, { "name": "title" }]
+}
+```
+
+This is the only way to keep an embedded path out of the dump — MongoDB does not allow mixing exclusions into the inclusion projection exwiw builds — and it is how to drop a subdocument that must not survive into the restored database at all, rather than be masked into a fake value. Two consequences worth knowing:
+
+- Dropping is not masking: a field that must keep a plausible value belongs in `replace_with` / `replace_with_fake_data`, not here. An absent path also means an application reading it sees "not set", which is a different state from "set to a masked value".
+- The path is only excluded when *no* config asks for it. If the parent collection also declares the path in its own `fields`, that declaration still pulls the raw subdocument into the dump — now with no masking applied to it, since the ignored config's rules no longer run. Remove the parent's field entry (or mark it `ignore: true`) as well.
+
+Like every other `ignore`, it is preserved across `exwiw:mongoid:schema:generate` regenerations, so the exclusion survives a config refresh.
+
 ## `exwiw explain` verbosity
 
 The mongodb explain runs the server's [explain command](https://www.mongodb.com/docs/manual/reference/command/explain/) at a configurable verbosity. The default, **`queryPlanner`, only plans the query and does not execute it**, so it is safe to point at a production source. Set it with the `EXWIW_MONGODB_EXPLAIN_VERBOSITY` environment variable or the `explain_verbosity:` config key (the env var wins):
@@ -138,7 +163,7 @@ For MongoDB applications backed by [Mongoid](https://www.mongodb.com/docs/mongoi
 bundle exec rake exwiw:schema:generate_mongoid
 ```
 
-It is a distinct task and class (`Exwiw::MongoidSchemaGenerator`) from the ActiveRecord generator because the two ORMs expose entirely different metadata. From each model it derives:
+It is a distinct task and class (`Exwiw::MongoidSchemaGenerator`) from the ActiveRecord generator because the two ORMs expose entirely different metadata. Every application document model is described, except one declared `store_in collection: nil` — the way an application says a document class is never persisted and only wants Mongoid's casting: it has no collection name to describe, so it is skipped (and does not count as a live collection when tidying). From each remaining model it derives:
 
 - 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),
@@ -147,6 +172,13 @@ It is a distinct task and class (`Exwiw::MongoidSchemaGenerator`) from the Activ
 
 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.
 
+A collection name can also be shared by embedded and non-embedded models, in two shapes the generator tells apart. `embedded?` only answers "does this class declare an `embedded_in`", which is not the same question as "does this collection have root documents":
+
+- **An embedded family under a plain base class** — `Address` holding the shared fields and declaring no `embedded_in`, with `BillingAddress < Address` declaring one and inheriting the collection name. Nothing is stored at the root under the base; it is part of the embedded family, and its fields describe subdocuments. The collection stays **embedded**, exactly as before: one `embedded_in` config unioning the base's fields with its subclasses', derived from a class that actually declares the embedding. (A non-embedded model whose embedded descendants are in the same group is always read as their base — conservatively so, even if the application also stored root documents under it, since the alternative would silently delete the config masking those subdocuments.)
+- **A genuine collision** — an unrelated top-level model stores into a collection whose name an embedded class derives from its own class name. Such a collection is genuinely **top-level**: it has root documents that must be dumped, so its config is built from the root models only (their fields and `belongs_tos`) with no `embedded_in`. An embedded base in the same group does not contribute its fields. Representing the group as embedded would make `dumpable?` skip the collection and silently drop those documents from the export.
+
+The collision is reported on stderr, because the embedded documents of the same name are **not** covered by that config: to mask them, add a config by hand with an `embedded_in` and a `name` / file name of your own choosing (generation and `tidy_mongoid` both leave `embedded_in` configs alone, so a hand-written one is stable). This is deliberately not recorded as a `comment` on the generated config — a generated comment takes precedence when merging, so it would overwrite a note you wrote about this very situation on every run.
+
 Regeneration preserves hand-edited `replace_with`, `filter`, `ignore`, `bulk_insert_chunk_size`, and `query_timeout_ms` values, like the ActiveRecord generator. Indexes are not written to the config — they are introspected from the live database at dump time (see [Output](#output)). Polymorphic `belongs_to` is not yet expanded by this task.
 
 ### Safe mode, `tidy_mongoid` and `check_mongoid`

data/lib/exwiw/adapter/mongodb_adapter.rb

@@ -383,9 +383,18 @@ module Exwiw
               "collection-level `filter` is not supported by MongodbAdapter (collection: #{config.name})"
       end
 
+      # Index the embedded configs by the collection they are embedded in, so
+      # the parent's projection can pull their paths in and its mask plan can
+      # descend into them.
+      #
+      # An `ignore: true` child is left out, which keeps its path out of the
+      # parent's inclusion projection and so out of the dump — the only way to
+      # exclude an embedded path (see docs/mongodb.md). Its own embedded
+      # children need no handling: they are never reached.
       private def index_embedded_children(config_by_name)
         config_by_name.each_value.with_object({}) do |child, acc|
           next unless child.embedded?
+          next if child.ignore
 
           (acc[child.embedded_in.collection_name] ||= []) << child
         end
@@ -706,9 +715,10 @@ module Exwiw
       # document of that collection. `masked_fields` is `[field_name,
       # template_segments]` for each field carrying a `replace_with`;
       # `faked_fields` is `[field_name, deriver, seed_field]` for each field
-      # carrying a `replace_with_fake_data`; `embedded` is one EmbeddedMask per
-      # embedded child.
-      MaskPlan = Struct.new(:masked_fields, :faked_fields, :embedded)
+      # carrying a `replace_with_fake_data`; `dropped_fields` is the name of each
+      # field marked `ignore:true`; `embedded` is one EmbeddedMask per embedded
+      # child.
+      MaskPlan = Struct.new(:masked_fields, :faked_fields, :dropped_fields, :embedded)
 
       # A pre-resolved embedded-child mask: the parent path split once into
       # `prefix` (the containers to descend into) and `last` (the field holding
@@ -741,11 +751,15 @@ module Exwiw
           acc << [field.name, mask]
         end
         faked_fields = build_faked_fields(config)
+        # Mostly for an embedded config, but a top-level one fetches an ignored
+        # field too when it is a propagation key (a child's `references`), and
+        # this is what keeps it out of the dump.
+        dropped_fields = config.ignored_field_names
         embedded = embedded_children_of(config).map do |child|
           *prefix, last = child.embedded_in.path.split(".")
           EmbeddedMask.new(prefix, last, build_mask_plan(child))
         end
-        MaskPlan.new(masked_fields, faked_fields, embedded)
+        MaskPlan.new(masked_fields, faked_fields, dropped_fields, embedded)
       end
 
       # Compile each `replace_with_fake_data` field into `[field_name, deriver,
@@ -775,13 +789,19 @@ module Exwiw
         end
       end
 
-      # Apply a precompiled MaskPlan to a document in place: render each
-      # `replace_with` field, then each `replace_with_fake_data` field, then
-      # descend into each embedded child (recursing into its own plan). Fake
-      # fields are applied after replace_with so a fake seed reads the already-
-      # masked value — matching the SQL adapters, where replace_with runs in the
-      # database before the Ruby-side fake transform sees the row.
+      # Apply a precompiled MaskPlan to a document in place: drop each
+      # `ignore:true` field, then render each `replace_with` field, then each
+      # `replace_with_fake_data` field, then descend into each embedded child
+      # (recursing into its own plan). Fake fields are applied after replace_with
+      # so a fake seed reads the already-masked value — matching the SQL
+      # adapters, where replace_with runs in the database before the Ruby-side
+      # fake transform sees the row.
+      #
+      # Dropping comes first so an ignored field is invisible to the masking that
+      # follows, as on a top-level collection — normally not fetched, and dropped
+      # here when the projection pulled it in as a propagation key.
       private def apply_mask_plan!(doc, plan)
+        plan.dropped_fields.each { |name| doc.delete(name) }
         plan.masked_fields.each do |name, mask|
           # Preserve a NULL / absent source value instead of clobbering it into a
           # masked literal. `doc[name].nil?` is true for both an explicit nil and

data/lib/exwiw/mongodb_collection_config.rb

@@ -67,6 +67,7 @@ module Exwiw
       instance.__send__(:validate_embedded!)
       instance.__send__(:validate_belongs_tos!)
       instance.__send__(:validate_fake_data!)
+      instance.__send__(:validate_ignored_fields!)
       instance
     end
 
@@ -78,11 +79,20 @@ module Exwiw
       !embedded_in.nil?
     end
 
+    # The names of the fields flagged `ignore:true`, kept answerable after
+    # #reject_ignored_members! has dropped the entries: an embedded config's
+    # subdocuments arrive inside the parent's document, so masking is the only
+    # place they can be removed (see MongodbAdapter#build_mask_plan).
+    def ignored_field_names
+      @ignored_field_names ||= fields.select(&:ignore).map(&:name)
+    end
+
     # Drop the belongs_tos/fields flagged `ignore:true` so they are excluded from
     # extraction. The config files on disk keep these entries; this is applied to
     # the runtime config right after it is loaded (see Runner#load_table_config).
     def reject_ignored_members!
       self.belongs_tos = belongs_tos.reject(&:ignore)
+      ignored_field_names # memoize before the entries are dropped
       self.fields = fields.reject(&:ignore)
       self
     end
@@ -197,6 +207,21 @@ module Exwiw
       end
     end
 
+    # A primary key marked `ignore: true` is rejected on load. Honoring it
+    # would delete the identifier from every dumped document — restore assigns
+    # fresh ids, breaking every reference pointing at them, and a `{_id}` mask
+    # template renders empty on every row — and silently not honoring it (the
+    # historical behavior, since the projection always fetches the key) would
+    # leave the config lying about what the dump contains.
+    private def validate_ignored_fields!
+      return unless fields.any? { |f| f.ignore && f.name == primary_key }
+
+      raise ArgumentError,
+            "MongodbCollectionConfig '#{name}': the primary key '#{primary_key}' must not be " \
+            "marked ignore: true (the dump has to keep the identifier; remove the ignore, " \
+            "or use ignore: true on the collection to exclude it entirely)."
+    end
+
     private def validate_embedded!
       return unless embedded?
 

data/lib/exwiw/mongoid_schema_generator.rb

@@ -275,50 +275,108 @@ module Exwiw
       return existing if existing&.ignore
 
       ordered = models.sort_by { |model| [model.fields.size, model.name] }
+      embedded_models, non_embedded_models = ordered.partition(&:embedded?)
+
+      return top_level_collection(collection_name, ordered, existing) if embedded_models.empty?
+
+      # `embedded?` means "declares an `embedded_in`", not "has root documents":
+      # a plain base class of embedded documents declares none but stores nothing
+      # at the root either. Reading it as a root model would flip the family to a
+      # top-level config and delete the `embedded_in` that masks its subdocuments,
+      # so a non-embedded model with embedded descendants in the group counts as
+      # their base — even if root documents were also stored under it (keeps the
+      # generator's historical behavior rather than risking a masking regression).
+      root_models = non_embedded_models.reject do |model|
+        embedded_models.any? { |embedded| embedded < model }
+      end
 
-      attrs = {
+      # A root model left after that is a genuine name collision (an embedded
+      # class derives its collection name from the class name alone). The
+      # collection has root documents that must keep being dumped, so generate it
+      # as top-level from the root models only — emitting `embedded_in` here would
+      # make `MongodbAdapter#dumpable?` skip it silently, and #merge would force
+      # that shape back onto a hand-maintained config on every run. The embedded
+      # namesakes are masked by a hand-written `embedded_in` config under a
+      # synthetic name (which generation and tidy leave alone); the warning says
+      # so instead of a generated `comment`, which would overwrite the user's own
+      # note via #merge.
+      if root_models.any?
+        warn_mixed_embedding(collection_name, embedded_models)
+        return top_level_collection(collection_name, root_models, existing)
+      end
+
+      # Purely embedded (possibly under a plain base, whose fields keep being
+      # unioned in as before).
+      embedded_collection(collection_name, ordered)
+    end
+
+    # The config for a collection dumped in its own right: its models' fields and
+    # the belongs_tos its extraction follows.
+    private def top_level_collection(collection_name, models, existing)
+      MongodbCollectionConfig.from_symbol_keys(
         name: collection_name,
         primary_key: PRIMARY_KEY,
-        fields: aggregate_fields(ordered),
-      }
+        belongs_tos: aggregate_belongs_tos(models, existing),
+        fields: aggregate_fields(models),
+      )
+    end
 
-      if ordered.any?(&:embedded?)
+    # The config for a collection that exists only inside another's documents.
+    # `models` is the whole group, which may include the embedded documents' plain
+    # base class — its fields belong in the union, but only a class that declares
+    # an `embedded_in` can say where the collection lives, hence the `find`.
+    private def embedded_collection(collection_name, models)
+      attrs = {
+        name: collection_name,
+        primary_key: PRIMARY_KEY,
+        fields: aggregate_fields(models),
         # Cross-collection references from inside an embedded array are not
         # supported (MongodbCollectionConfig rejects them), so embedded configs
         # always carry an empty belongs_tos and instead declare where they live.
-        attrs[:belongs_tos] = []
-        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, existing)
+        belongs_tos: [],
+      }
+
+      begin
+        attrs[:embedded_in] = embedded_in_for(models.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
 
       MongodbCollectionConfig.from_symbol_keys(attrs)
     end
 
+    # Names the collision on stderr, once per affected collection.
+    private def warn_mixed_embedding(collection_name, embedded_models)
+      warn(
+        "exwiw: collection '#{collection_name}' is stored into by both top-level and embedded models " \
+        "(embedded: #{embedded_models.map(&:name).sort.join(', ')}); generating it as a TOP-LEVEL collection " \
+        "from its non-embedded model(s) only, so its root documents keep being dumped. The embedded " \
+        "documents of the same name are NOT covered by this config: to mask them, add a config by hand " \
+        "with an `embedded_in` and a distinct `name`/file name of your choosing (generation and tidy leave " \
+        "embedded configs alone)."
+      )
+    end
+
     # Mongoid registers only the base class of an inheritance hierarchy in
     # `Mongoid.models`; subclasses that store into the base's collection
     # (STI-style, distinguished by the auto-added `_type` discriminator) are
@@ -339,11 +397,20 @@ module Exwiw
       concrete(@models)
     end
 
+    # The single place a model is judged fit to describe (used by generate! and
+    # tidy! alike): Mongoid's internal helper classes are dropped, and so is any
+    # class with an empty `collection_name` — `store_in collection: nil` is the
+    # never-persisted-model idiom, and a config for the nameless group such
+    # classes collapse into describes nothing (as top-level it would even
+    # instruct the dump to read a collection with no name). The emptiness test
+    # stays last: the preceding conditions establish that calling
+    # `collection_name` is meaningful.
     private def concrete(models)
       models.select do |model|
         model.respond_to?(:collection_name) &&
           model.name &&
-          !model.name.start_with?("Mongoid::")
+          !model.name.start_with?("Mongoid::") &&
+          !model.collection_name.to_s.empty?
       end
     end
 

data/lib/exwiw/version.rb

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

metadata

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