exwiw 0.9.22 → 0.9.23

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3abd99db26266c75e79f46cd0fc14a2a0344308031422385ca22dd2a77ab0130
-  data.tar.gz: 9c78446793e1c91947bcf7aa6b933d623c87d004d84fbcb3df8b86886e136482
+  metadata.gz: 9cbe5a94be08902db6990812f48eb07b3aa5cae7a507acb0f8c3cf1f90edc175
+  data.tar.gz: 19b92d8feee9e874135fc0c9f833d290aacdb1be35c6bcd3da72c7c212352327
 SHA512:
-  metadata.gz: 0406c29183e0a896ae9de40e24622239caa4cf06b898784d1aa24633d479b0e4ee5717f8d755e5c323af1dd290e18e92f201f4d2ac6f192feb71e9c1a947eee2
-  data.tar.gz: 63e754207a3c08d97d9b9ceed684b5e112c770c02e9638dd80e9ba958fd1d9ecc96784e6d0431cb27c818e254177d62b506ea587fc1ba55d7068125c889a7fd2
+  metadata.gz: 75e631242a39ba72bd16ed7d28435f935c9d591d89888632f5fd835b2b727d6f497a976b91bbcc69bdbc8c85fbfb68d2265488d3b07b19baa37001a7d832d173
+  data.tar.gz: abcfacf75eff9c74324fae77915f10b86ab7258f5251bf5fa7adbe73a3af318fd06ffc4e791e7abc00439b1007901d43e80865ff0394ada7eb8deba040707d1d

data/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [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/docs/mongodb.md

@@ -138,7 +138,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 +147,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/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.23"
 end

metadata

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