exwiw 0.4.10 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a89e3da8899badc5bcccc98f58878744b9b106b31ca38af6a70b41109002d126
-  data.tar.gz: 13dd0757b0699c7865cd4c89b214288d16d017a9447c042e90c3da5cedc6f4b2
+  metadata.gz: 224bdc1d3b0f94e08463ad9e42a6e67d0592d902388b5873f5840226dbdbd3fe
+  data.tar.gz: de9ddd4a625565e0bcd28ff3f74df8da06092c443ad1f170d41c5858a24c4802
 SHA512:
-  metadata.gz: b04b7e070c1215b24c6dfa6453e572bf560d77fbd9a6eb6172fbd301a8b662ebc1da815f13d5fb4ba31799a5e8e45c610c0271e810eff6c8c675e75fcf261e2d
-  data.tar.gz: 4b88cfc7ed7a758b7a82b76d9e936c251b388825411fef9c305434919b7695f6866e5011828a6a2bf00c95692d157c1f0e4e768e0dc3e9ab79b980f025e4c626
+  metadata.gz: '08f564c07c09561a4b9b825bb7f6ca43a076df5b8262f165addad471639084fa5b5074330215edd36951ce0c427f510533f39d03e0632c1306ba4e9054391b33'
+  data.tar.gz: 2c161f236a676a15774fb097a7a2c4d66f95f38be8c465dfc29788b4c45165aa3b13dee2b1da771e317672e63f089d2496e10cf4fe2ebf16f97885e0e1c49c76

data/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-06-16
+
+### Added
+
+- A YAML **config file** (`exwiw.yml`) can now hold any option except the database connection settings, so they no longer have to be repeated on every invocation. Pass it with `--config=PATH`; when `--config` is omitted, `exwiw.yml` (or `exwiw.yaml`) is loaded automatically from the current directory if present. **Options passed on the CLI take precedence** over the file (the file only fills in options not given on the CLI). Connection settings — `host`, `port`, `user`, `database`, `uri`, `password` — are **rejected** in the file (they must come from the CLI/environment); `adapter` is the one connection-related key allowed. Relative paths in the file (`schema_dir`, `output_dir`, `after_insert_hook`) are resolved relative to the config file's own directory (so a root-level `exwiw.yml` with `schema_dir: exwiw/schema` reads naturally and an absolute `--config` works from any directory). Unknown keys are rejected to catch typos, and export-only keys (`output_dir`, `output_format`, `insert_only`, `after_insert_hook`) are ignored under `explain` so one file can be shared by both subcommands.
+
+### Changed
+
+- **BREAKING**: the `export`/`explain` CLI option `--config-dir` has been renamed to `--schema-dir` to distinguish the directory of schema JSON files from the new `--config` config file. Its short form `-c` is now `--config` (the config file); `--schema-dir` has no short form. The hook contract is renamed to match: the shell-hook environment variable `EXWIW_CONFIG_DIR` is now `EXWIW_SCHEMA_DIR`, and the Ruby-hook `cli_options[:config_dir]` is now `cli_options[:schema_dir]`. Update invocations, scripts, and hooks accordingly (`--config-dir` no longer exists). `--schema-dir` is still required and has no default unless `schema_dir` is set in the config file.
+- **BREAKING**: the env var that overrides where `schema:generate`, `schema:tidy`, and `schema:generate_mongoid` write their config has been renamed from `OUTPUT_DIR_PATH` to `EXWIW_SCHEMA_DIR_PATH`, and the default output directory is now `exwiw/schema` (previously `exwiw`). The new name disambiguates it from the dump-side `--output-dir`, and the dedicated `schema/` subdirectory leaves `exwiw/` free for other artifacts (hooks, dumps). `OUTPUT_DIR_PATH` is no longer read. Existing repositories should set `EXWIW_SCHEMA_DIR_PATH` (e.g. `EXWIW_SCHEMA_DIR_PATH=exwiw` to preserve the old flat layout) and/or move their config under `exwiw/schema/`; otherwise a `generate` run will write a fresh copy into `exwiw/schema/` and leave the old files stale. The `export`/`explain` CLI is unaffected, but examples now point at `exwiw/schema`.
+
+## [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

@@ -72,7 +72,7 @@ exwiw \
   --port=3306 \
   --user=reader \
   --database=app_production \
-  --config-dir=exwiw \
+  --schema-dir=exwiw/schema \
   --target-table=shops \
   --ids=1 \ # comma separated ids
   --output-dir=dump \
@@ -81,7 +81,7 @@ exwiw \
 
 By default `--ids` are matched against the target table's primary key. `--ids-column=COLUMN` matches them against a different column instead (e.g. `--target-table=users --ids=alice@example.com --ids-column=email`). Related tables are still extracted correctly: their foreign keys are resolved through the target via a subquery (`WHERE fk IN (SELECT pk FROM target WHERE COLUMN IN (...))`), so only the target table's filter column changes. This is the SQL-adapter counterpart of the mongodb `--ids-field`; the two are mutually exclusive and each is rejected by the other adapter family. Note: if `COLUMN` is itself masked, re-running `delete-*` against an already-imported (masked) dump won't match, so prefer a stable natural key.
 
-When `--target-table` and `--ids` are omitted, exwiw dumps all tables defined in `--config-dir`:
+When `--target-table` and `--ids` are omitted, exwiw dumps all tables defined in `--schema-dir`:
 
 ```bash
 # dump all tables
@@ -91,7 +91,7 @@ exwiw \
   --port=5432 \
   --user=reader \
   --database=app_production \
-  --config-dir=exwiw \
+  --schema-dir=exwiw/schema \
   --output-dir=dump
 ```
 
@@ -123,25 +123,58 @@ exwiw explain \
   --adapter=postgresql \
   --host=localhost --port=5432 --user=reader \
   --database=app_production \
-  --config-dir=exwiw \
+  --schema-dir=exwiw/schema \
   --target-table=shops --ids=1
 ```
 
 The `--output-dir`, `--output-format`, `--insert-only`, and `--after-insert-hook` options are dump-specific and rejected when used with `explain`.
 
+### Config file (`exwiw.yml`)
+
+Options you would otherwise repeat on every run can be kept in a YAML config file. Pass it with `--config=PATH`; when `--config` is omitted, exwiw automatically loads `exwiw.yml` (or `exwiw.yaml`) from the current directory if present.
+
+**Options passed on the CLI always take precedence over the config file** — the config only fills in options you did not pass. This lets you commit the stable settings (which schema to read, output format, ...) while still varying the environment-specific connection details per invocation.
+
+```yaml
+# exwiw.yml — keep at the project root, alongside exwiw/schema/
+adapter: postgresql
+schema_dir: exwiw/schema
+output_dir: dump
+output_format: insert        # insert | copy
+insert_only: false
+after_insert_hook: hooks/seed.rb
+log_level: info              # debug | info
+# target_table / ids / ids_field / ids_column may also be set here
+```
+
+With the file above, only the connection details need to be supplied on the CLI:
+
+```bash
+DATABASE_PASSWORD=... exwiw \
+  --host=localhost --port=5432 --user=reader --database=app_production \
+  --target-table=shops --ids=1
+```
+
+Notes:
+
+- **Database connection settings stay on the CLI/environment.** `host`, `port`, `user`, `database`, `uri`, and `password` are **rejected** in the config file (exwiw exits with an error). `adapter` is the one connection-related key that *is* allowed in the file.
+- **Relative paths in the config (`schema_dir`, `output_dir`, `after_insert_hook`) are resolved relative to the config file's own directory**, not the current working directory. So with the config at the project root, `schema_dir: exwiw/schema` reads naturally, and an absolute `--config=/path/to/exwiw.yml` works no matter where you run from. (CLI path flags remain relative to the current directory — each source resolves relative to where it is written.) Absolute paths are used as-is.
+- Unknown keys are rejected so a typo surfaces immediately.
+- Export-only keys (`output_dir`, `output_format`, `insert_only`, `after_insert_hook`) are ignored when running `explain`, so a single config file can be shared by both subcommands.
+
 ### Generator
 
 The config generator is provided as a Rake task.
 
 ```bash
-# generate table schema under exwiw/
+# generate table schema under exwiw/schema/
 bundle exec rake exwiw:schema:generate
 ```
 
-By default, the schema files will be saved in the `exwiw` directory. You can specify a different output directory by setting the `OUTPUT_DIR_PATH` environment variable:
+By default, the schema files will be saved in the `exwiw/schema` directory. You can specify a different output directory by setting the `EXWIW_SCHEMA_DIR_PATH` environment variable:
 
 ```sh
-OUTPUT_DIR_PATH=custom_directory bundle exec rake exwiw:schema:generate
+EXWIW_SCHEMA_DIR_PATH=custom_directory bundle exec rake exwiw:schema:generate
 ```
 
 #### Tidying stale config (`schema:tidy`)
@@ -159,14 +192,14 @@ bundle exec rake exwiw:schema:tidy
 
 Because it reads the database directly, a table that still exists in the database but has lost (or never had) an ActiveRecord model is **kept** — only a table that is genuinely gone is removed. (This is the deliberate counterpart to `generate`, which is model-driven and only ever adds what the models know about.)
 
-It respects `OUTPUT_DIR_PATH` and the per-database subdirectory layout in the same way as `schema:generate`. Unlike `generate`, `tidy` never adds or regenerates entries — every surviving table/column (including hand-edited `comment` / `ignore` / `replace_with`) is left untouched, so it is safe to run on a customized config. The task prints which tables and columns it removed (or that the config was already tidy). Stale `belongs_tos` are not pruned by `tidy`; rerun `schema:generate` to refresh those.
+It respects `EXWIW_SCHEMA_DIR_PATH` and the per-database subdirectory layout in the same way as `schema:generate`. Unlike `generate`, `tidy` never adds or regenerates entries — every surviving table/column (including hand-edited `comment` / `ignore` / `replace_with`) is left untouched, so it is safe to run on a customized config. The task prints which tables and columns it removed (or that the config was already tidy). Stale `belongs_tos` are not pruned by `tidy`; rerun `schema:generate` to refresh those.
 
 #### Multiple databases
 
 If the application uses Rails' multiple-database support (`connects_to`), `schema:generate` buckets models by the database they connect to and writes each database's config files into its own subdirectory of the output directory, named after the database config name (`primary`, `analytics`, ...):
 
 ```
-exwiw/
+exwiw/schema/
   primary/
     shops.json
     users.json
@@ -194,20 +227,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
 
@@ -234,7 +300,7 @@ This is an example of the one table schema:
 }
 ```
 
-`--config-dir` will use all json files in the specified directory.
+`--schema-dir` will use all json files in the specified directory.
 
 ### Output format
 
@@ -274,7 +340,7 @@ SQL
 
 **Shell hook**: anything other than `.rb` is exec'd as a child process. It is a pure side-effect hook — exwiw does not capture its stdout. The hook receives these env vars and inherits `DATABASE_PASSWORD` from the parent:
 
-- `EXWIW_OUTPUT_DIR`, `EXWIW_CONFIG_DIR`
+- `EXWIW_OUTPUT_DIR`, `EXWIW_SCHEMA_DIR`
 - `EXWIW_DATABASE_ADAPTER`, `EXWIW_DATABASE_HOST`, `EXWIW_DATABASE_PORT`, `EXWIW_DATABASE_USER`, `EXWIW_DATABASE_NAME`
 - `EXWIW_TARGET_TABLE`, `EXWIW_IDS` (comma-separated), `EXWIW_OUTPUT_FORMAT`
 

data/lib/exwiw/after_insert_hook.rb

@@ -31,7 +31,7 @@ module Exwiw
     def self.run_shell(path:, cli_options:, output_dir:, logger:)
       env = {
         'EXWIW_OUTPUT_DIR'       => output_dir,
-        'EXWIW_CONFIG_DIR'       => cli_options[:config_dir].to_s,
+        'EXWIW_SCHEMA_DIR'       => cli_options[:schema_dir].to_s,
         'EXWIW_DATABASE_ADAPTER' => cli_options[:database_adapter].to_s,
         'EXWIW_DATABASE_HOST'    => cli_options[:database_host].to_s,
         'EXWIW_DATABASE_PORT'    => cli_options[:database_port].to_s,

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/cli.rb

@@ -5,6 +5,7 @@ require 'optparse'
 require 'pathname'
 
 require 'json'
+require 'yaml'
 
 require 'exwiw'
 
@@ -12,6 +13,39 @@ module Exwiw
   class CLI
     KNOWN_SUBCOMMANDS = %w[export explain].freeze
 
+    # Config file loaded automatically when --config is omitted, if one exists in
+    # the current directory. Kept at the project root (rather than under exwiw/)
+    # so that config-relative paths like `schema_dir: exwiw/schema` read naturally.
+    # Both extensions are accepted; .yml wins when both are present.
+    DEFAULT_CONFIG_PATHS = %w[exwiw.yml exwiw.yaml].freeze
+
+    # Keys accepted in the config file. Anything outside this set is rejected so
+    # a typo surfaces immediately instead of being silently ignored. These mirror
+    # the non-connection CLI options (plus `adapter`).
+    ALLOWED_CONFIG_KEYS = %w[
+      adapter
+      schema_dir
+      output_dir
+      output_format
+      insert_only
+      after_insert_hook
+      log_level
+      target_table
+      target_collection
+      ids
+      ids_field
+      ids_column
+    ].freeze
+
+    # Database connection settings are environment-specific (and sometimes
+    # secret-adjacent), so they must be passed via CLI/env, never the committed
+    # config file. `adapter` is the one connection-ish key allowed in config.
+    REJECTED_CONNECTION_KEYS = %w[host port user database uri password].freeze
+
+    # Keys that only make sense for `export`. They are skipped when merging config
+    # for `explain` so a shared config file does not trip validate_explain_only!.
+    EXPORT_ONLY_CONFIG_KEYS = %w[output_dir output_format insert_only after_insert_hook].freeze
+
     def self.start(argv)
       new(argv).run
     end
@@ -34,7 +68,8 @@ module Exwiw
       @database_password = ENV["DATABASE_PASSWORD"]
       @connection_uri = nil
       @output_dir = nil
-      @config_dir = nil
+      @schema_dir = nil
+      @config_file_path = nil
       @database_adapter = nil
       @database_name = nil
       @target_table_name = nil
@@ -45,7 +80,9 @@ module Exwiw
       @output_format = nil
       @insert_only = nil
       @after_insert_hook_path = nil
-      @log_level = :info
+      # nil (not :info) so we can tell "user passed --log-level" from the default,
+      # letting a config-file value fill in; the :info default is applied later.
+      @log_level = nil
 
       parser.parse!(@argv)
     end
@@ -82,7 +119,7 @@ module Exwiw
         Runner.new(
           connection_config: connection_config,
           output_dir: @output_dir,
-          config_dir: @config_dir,
+          schema_dir: @schema_dir,
           dump_target: dump_target,
           output_format: @output_format,
           insert_only: @insert_only,
@@ -93,7 +130,7 @@ module Exwiw
       when "explain"
         ExplainRunner.new(
           connection_config: connection_config,
-          config_dir: @config_dir,
+          schema_dir: @schema_dir,
           dump_target: dump_target,
           logger: logger,
           io: $stdout,
@@ -102,6 +139,14 @@ module Exwiw
     end
 
     private def validate_options!
+      # Fill in any options not given on the CLI from the config file. Done first
+      # so a config-provided `adapter` is in place before normalization below.
+      # CLI values always win (the merge only fills nil/empty ivars).
+      apply_config_file!
+
+      # Default log level once CLI and config have both had their say.
+      @log_level ||= :info
+
       # Fold driver/Rails adapter spellings (mysql2, sqlite3) into exwiw's
       # canonical names up front, so every check below — and the
       # EXWIW_DATABASE_ADAPTER passed to hooks — sees the canonical name.
@@ -163,18 +208,18 @@ module Exwiw
         end
       end
 
-      if @config_dir.nil?
-        $stderr.puts "Config dir is required"
+      if @schema_dir.nil?
+        $stderr.puts "Schema dir is required (pass --schema-dir or set schema_dir in the config file)"
         exit 1
       end
 
-      unless Dir.exist?(@config_dir)
-        $stderr.puts "Config dir does not exist: #{@config_dir}"
+      unless Dir.exist?(@schema_dir)
+        $stderr.puts "Schema dir does not exist: #{@schema_dir}"
         exit 1
       end
 
-      if Dir.glob(File.join(@config_dir, "*.json")).empty?
-        $stderr.puts "Config dir contains no .json files: #{@config_dir}"
+      if Dir.glob(File.join(@schema_dir, "*.json")).empty?
+        $stderr.puts "Schema dir contains no .json files: #{@schema_dir}"
         exit 1
       end
 
@@ -202,6 +247,78 @@ module Exwiw
       end
     end
 
+    # Merge settings from the config file (YAML) into any options the user did
+    # not pass on the CLI. The CLI always wins: every assignment below only fills
+    # an ivar that is still nil/empty after parsing ARGV. Connection settings
+    # (except `adapter`) are rejected here — they belong on the CLI/env.
+    private def apply_config_file!
+      path =
+        if @config_file_path
+          unless File.file?(@config_file_path)
+            $stderr.puts "Config file not found: #{@config_file_path}"
+            exit 1
+          end
+          @config_file_path
+        else
+          DEFAULT_CONFIG_PATHS.map { |p| File.expand_path(p) }.find { |p| File.file?(p) }
+        end
+      return if path.nil?
+
+      # Paths inside the config file are resolved relative to the file's own
+      # directory (not cwd), so `schema_dir: exwiw/schema` reads naturally with the
+      # config kept at the project root, and an absolute --config works from any
+      # cwd. (CLI path flags stay cwd-relative — each source resolves relative to
+      # where it is written.) `path` is always absolute here.
+      base = File.dirname(path)
+
+      config = YAML.safe_load(File.read(path)) || {}
+      unless config.is_a?(Hash)
+        $stderr.puts "Config file must be a YAML mapping (key: value): #{path}"
+        exit 1
+      end
+
+      config.each_key do |key|
+        if REJECTED_CONNECTION_KEYS.include?(key)
+          $stderr.puts "'#{key}' is a database connection setting and must be passed via the CLI/environment, not the config file (#{path})"
+          exit 1
+        end
+        unless ALLOWED_CONFIG_KEYS.include?(key)
+          $stderr.puts "Unknown config key '#{key}' in #{path}. Allowed keys: #{ALLOWED_CONFIG_KEYS.join(', ')}"
+          exit 1
+        end
+      end
+
+      # For `explain`, drop export-only keys so a config shared with `export`
+      # does not make validate_explain_only! reject the run.
+      config = config.reject { |k, _| EXPORT_ONLY_CONFIG_KEYS.include?(k) } if @subcommand == "explain"
+
+      @database_adapter ||= config["adapter"]
+      @schema_dir ||= expand_dir(config["schema_dir"], base)
+      @output_dir ||= expand_dir(config["output_dir"], base)
+      @after_insert_hook_path ||= (File.expand_path(config["after_insert_hook"], base) if config["after_insert_hook"])
+      @output_format ||= config["output_format"]
+      @insert_only = config["insert_only"] if @insert_only.nil? && config.key?("insert_only")
+      @log_level ||= config["log_level"]&.to_sym
+      @target_table_name ||= config["target_table"]
+      @target_collection_name ||= config["target_collection"]
+      if @ids.empty? && config.key?("ids")
+        raw = config["ids"]
+        # Accept either a YAML list or a "1,2" string; coerce to strings to match
+        # the CLI's `--ids=1,2` -> ["1", "2"] shape.
+        @ids = (raw.is_a?(String) ? raw.split(",") : Array(raw)).map(&:to_s)
+      end
+      @ids_field ||= config["ids_field"]
+      @ids_column ||= config["ids_column"]
+    end
+
+    # Strip a trailing slash (like the CLI's dir options) and expand relative to
+    # `base` (the config file's directory). Returns nil for a nil value.
+    private def expand_dir(value, base)
+      return nil if value.nil?
+      value = value.end_with?("/") ? value[0..-2] : value
+      File.expand_path(value, base)
+    end
+
     # `--target-collection` is a mongodb-only alias of `--target-table`. Fold it
     # into @target_table_name (the single field the rest of the CLI/runner uses)
     # after rejecting the misuses: combining it with --target-table, or using it
@@ -319,7 +436,7 @@ module Exwiw
         database_user: @database_user,
         database_password: @database_password,
         output_dir: @output_dir,
-        config_dir: @config_dir,
+        schema_dir: @schema_dir,
         database_adapter: @database_adapter,
         database_name: @database_name,
         target_table: @target_table_name,
@@ -368,9 +485,12 @@ module Exwiw
           v = v.end_with?("/") ? v[0..-2] : v
           @output_dir = File.expand_path(v)
         end
-        opts.on("-c", "--config-dir=CONFIG_DIR_PATH", "Config dir path.") do |v|
+        opts.on("--schema-dir=SCHEMA_DIR_PATH", "Directory of schema JSON files. (or set schema_dir in the config file)") do |v|
           v = v.end_with?("/") ? v[0..-2] : v
-          @config_dir = File.expand_path(v)
+          @schema_dir = File.expand_path(v)
+        end
+        opts.on("-c", "--config=CONFIG_FILE_PATH", "Path to the exwiw config YAML. Defaults to ./#{DEFAULT_CONFIG_PATHS.first} (or .#{File.extname(DEFAULT_CONFIG_PATHS.last)}) when present. CLI options take precedence; paths inside the file are resolved relative to the file.") do |v|
+          @config_file_path = File.expand_path(v)
         end
         opts.on("-a", "--adapter=ADAPTER", "Database adapter: mysql, sqlite, postgresql, mongodb (aliases: mysql2, sqlite3)") { |v| @database_adapter = v }
         opts.on("--uri=URI", "Full MongoDB connection URI (mongodb:// or mongodb+srv://). mongodb adapter only; takes precedence over --host/--port/--user. TLS, replicaSet, authSource and credentials are read from the URI.") { |v| @connection_uri = v }

data/lib/exwiw/explain_runner.rb

@@ -4,13 +4,13 @@ module Exwiw
   class ExplainRunner
     def initialize(
       connection_config:,
-      config_dir:,
+      schema_dir:,
       dump_target:,
       logger:,
       io: $stdout
     )
       @connection_config = connection_config
-      @config_dir = config_dir
+      @schema_dir = schema_dir
       @dump_target = dump_target
       @logger = logger
       @io = io
@@ -53,7 +53,7 @@ module Exwiw
     end
 
     private def load_table_config(klass)
-      Dir[File.join(@config_dir, "*.json")].map do |file|
+      Dir[File.join(@schema_dir, "*.json")].map do |file|
         json = JSON.parse(File.read(file))
         klass.from(json).reject_ignored_members!
       end

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/runner.rb

@@ -7,7 +7,7 @@ module Exwiw
     def initialize(
       connection_config:,
       output_dir:,
-      config_dir:,
+      schema_dir:,
       dump_target:,
       logger:,
       output_format: 'insert',
@@ -17,7 +17,7 @@ module Exwiw
     )
       @connection_config = connection_config
       @output_dir = output_dir
-      @config_dir = config_dir
+      @schema_dir = schema_dir
       @dump_target = dump_target
       @output_format = output_format
       @insert_only = insert_only
@@ -159,7 +159,7 @@ module Exwiw
     end
 
     private def load_table_config(klass)
-      Dir[File.join(@config_dir, "*.json")].map do |file|
+      Dir[File.join(@schema_dir, "*.json")].map do |file|
         json = JSON.parse(File.read(file))
         # Drop belongs_tos/columns(fields) flagged ignore:true so they are not
         # considered during extraction. Done here (after loading from file)

data/lib/exwiw/version.rb

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

data/lib/tasks/exwiw.rake

@@ -7,7 +7,7 @@ namespace :exwiw do
       require "exwiw"
 
       Exwiw::SchemaGenerator.from_rails_application(
-        output_dir: ENV["OUTPUT_DIR_PATH"] || "exwiw",
+        output_dir: ENV["EXWIW_SCHEMA_DIR_PATH"] || "exwiw/schema",
       ).generate!
     end
 
@@ -16,7 +16,7 @@ namespace :exwiw do
       require "exwiw"
 
       result = Exwiw::SchemaGenerator.from_rails_application(
-        output_dir: ENV["OUTPUT_DIR_PATH"] || "exwiw",
+        output_dir: ENV["EXWIW_SCHEMA_DIR_PATH"] || "exwiw/schema",
       ).tidy!
 
       if result.empty?
@@ -32,16 +32,22 @@ 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"
 
       Exwiw::MongoidSchemaGenerator.from_rails_application(
-        output_dir: ENV["OUTPUT_DIR_PATH"] || "exwiw",
+        output_dir: ENV["EXWIW_SCHEMA_DIR_PATH"] || "exwiw/schema",
         skip_unsupported: ENV["EXWIW_SKIP_UNSUPPORTED"] == "1",
       ).generate!
     end

metadata

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