declare_schema 4.0.3 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67a8ff59b5f29818efd240f2d5b07d3631f54c21bf7c0b983c045fa2b6f2d4ac
-  data.tar.gz: cf0ddc6128d5f0e2e3f0d867c3a384942ce35c561f38a35ca58090369c0ab25f
+  metadata.gz: 515b75b80f3aec9fa977aebe9874ad015bd16def4a07ed0f7c86fee3fd51e6ac
+  data.tar.gz: 5bac16aa76fcb28b74b0beaae97c7ddd6f4e7a5f939feae9f4948f7ef1f74606
 SHA512:
-  metadata.gz: edb10d4c1b0018a198007a8a9862455991e62df80e786b141a870ac998ed7f2dc7653cbdff14bab4615649fbe45d9caa3be1f3c8ae420f863f28c6ba09b2a06b
-  data.tar.gz: 2b916bf151cbf69d55c52f071fc4a6006e1906e918231ae4f973982034fcae35af3da1b05f19174a741f9461e47998d1c0cd8cdd30e9b88ef0a30f6e6c20109a
+  metadata.gz: 5db28ddddef093068697c0caf0f1797eacf82bb94e6b56353dc5b31bae8c442ccab1287eea8495e9ade030f41d1053031d6499c688e4588667b6e8748bcff2c9
+  data.tar.gz: c433348df1b1ae6db97878e2afac920f8fafff5d19995fe75a297be6d01d05ec4db1f183249457a2b5a86c7d2fd4cfa6f36b3f0db2042571960e7a19fe7056f9

data/CHANGELOG.md

@@ -4,6 +4,17 @@ Inspired by [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 Note: this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.1.0] - 2026-07-07
+### Added
+- `::DeclareSchema.ignore_tables` and `::DeclareSchema.ignore_models` as the new public
+  settings for ignoring tables/models during migration generation.
+
+### Deprecated
+- `Generators::DeclareSchema::Migration::Migrator.ignore_tables` and `.ignore_models` in
+  favor of `DeclareSchema.ignore_tables` and `DeclareSchema.ignore_models` above. The
+  `Migrator` accessors still work but emit a deprecation warning; they will not be
+  removed without a major version bump.
+
 ## [4.0.3] - 2026-07-01
 ### Changed
 - Documented the `field` DSL macro and the underlying `declare_field` class method.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    declare_schema (4.0.3)
+    declare_schema (4.1.0)
       rails (>= 7.0)
 
 GEM

data/README.md

@@ -376,23 +376,43 @@ infers foreign keys (and the intersection table).
 
 ## Ignored Tables
 If a table's schema or metadata are managed elsewhere, `declare_schema` can be instructed to ignore it
-by adding those table names to the array assigned to `Generators::DeclareSchema::Migration::Migrator.ignore_tables`.
+by adding those table names to the array assigned to `DeclareSchema.ignore_tables`.
 For example:
 
 ```ruby
-::Generators::DeclareSchema::Migration::Migrator.ignore_tables = [
+::DeclareSchema.ignore_tables = [
   "delayed_jobs",
   "my_snowflake_table",
   ...
 ]
 ```
 
+**Deprecated:** `Generators::DeclareSchema::Migration::Migrator.ignore_tables` is a deprecated alias for
+`DeclareSchema.ignore_tables` above. New code should use `DeclareSchema.ignore_tables` directly;
+`Migrator.ignore_tables` will be removed in version 5.0.
+
 Note: `declare_schema` always ignores these tables:
 - The ActiveRecord `schema_info` table
 - The ActiveRecord schema migrations table (generally named `schema_migrations`)
 - The ActiveRecord internal metadata table (generally named `ar_internal_metadata`)
 - If defined/configured, the CGI ActiveRecordStore session table
 
+## Ignored Models
+Similarly, `declare_schema` can be instructed to ignore specific models (so that no migration is
+generated for their table) by adding the model's underscored name to the array assigned to
+`DeclareSchema.ignore_models`. For example:
+
+```ruby
+::DeclareSchema.ignore_models = [
+  "my_legacy_model",
+  ...
+]
+```
+
+**Deprecated:** `Generators::DeclareSchema::Migration::Migrator.ignore_models` is a deprecated alias for
+`DeclareSchema.ignore_models` above. New code should use `DeclareSchema.ignore_models` directly;
+`Migrator.ignore_models` will be removed in version 5.0.
+
 ## Maximum Length of Index and Constraint Names
 
 MySQL limits the length of index and constraint names to 64 characters.

data/docs/superpowers/plans/2026-07-03-ignore-tables-ignore-models-deprecation.md

@@ -0,0 +1,431 @@
+# DeclareSchema.ignore_tables/ignore_models Deprecation Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Move the `ignore_tables` and `ignore_models` settings from the internal `Generators::DeclareSchema::Migration::Migrator` class to the public `::DeclareSchema` module, keeping the old `Migrator` accessors working but deprecated.
+
+**Architecture:** Reuse the exact pattern already used in this codebase for `default_charset`/`default_collation` (see `lib/generators/declare_schema/migration/migrator.rb`): the setting becomes a plain `attr_accessor` on `::DeclareSchema`, and `Migrator` gets `delegate ... to: ::DeclareSchema` + `deprecate ...` for the old names, sharing the existing `ActiveSupport::Deprecation.new('1.0', 'declare_schema')` instance.
+
+**Tech Stack:** Ruby, Rails/ActiveSupport (`Module#delegate`, `Module#deprecate`, `ActiveSupport::Deprecation`), RSpec.
+
+## Global Constraints
+
+- No removal of `Migrator.ignore_tables`/`ignore_models` — deprecate only, so no major version bump is required.
+- Version bump: `4.0.3` → `4.1.0` (minor).
+- Spec reference: [OCTO-893](https://invoca.atlassian.net/browse/OCTO-893).
+- Design doc: `docs/superpowers/specs/2026-07-03-ignore-tables-deprecation-design.md`.
+- Work happens on branch `OCTO-893/deprecate-migrator-ignore-tables` (already created, already has 1 commit with the design doc).
+- No gem release/publish and no push to `origin` as part of this plan — local commits only.
+
+---
+
+### Task 1: Move `ignore_tables`/`ignore_models` to `::DeclareSchema`, deprecate on `Migrator`
+
+**Files:**
+- Modify: `lib/declare_schema.rb`
+- Modify: `lib/generators/declare_schema/migration/migrator.rb`
+- Test: `spec/lib/generators/declare_schema/migration/migrator_spec.rb`
+- Modify: `spec/lib/declare_schema/migration_generator_spec.rb:64`
+
+**Interfaces:**
+- Produces: `::DeclareSchema.ignore_tables` / `::DeclareSchema.ignore_tables=` (Array, default `[]`)
+- Produces: `::DeclareSchema.ignore_models` / `::DeclareSchema.ignore_models=` (Array, default `[]`)
+- Produces (deprecated but functional): `Generators::DeclareSchema::Migration::Migrator.ignore_tables` / `.ignore_tables=` / `.ignore_models` / `.ignore_models=`, all delegating to the `::DeclareSchema` versions above and emitting an `ActiveSupport::Deprecation` warning.
+
+- [ ] **Step 1: Write the failing tests for the new deprecation behavior**
+
+In `spec/lib/generators/declare_schema/migration/migrator_spec.rb`, insert these two new `describe` blocks immediately after the existing `describe '#default_collation'` block (which ends right before `describe '#load_rails_models'` at line 59):
+
+```ruby
+        describe '#ignore_tables' do
+          subject { described_class.ignore_tables }
+
+          context 'when not explicitly set' do
+            it { should eq([]) }
+          end
+
+          context 'when explicitly set' do
+            before { described_class.ignore_tables = ["green_fishes"] }
+            after  { described_class.ignore_tables = [] }
+            it     { should eq(["green_fishes"]) }
+          end
+
+          it 'should output deprecation warning' do
+            expect { described_class.ignore_tables = ["green_fishes"] }.to output(/DEPRECATION WARNING: ignore_tables= is deprecated/).to_stderr
+            expect { subject }.to output(/DEPRECATION WARNING: ignore_tables is deprecated/).to_stderr
+          end
+
+          after { ::DeclareSchema.ignore_tables = [] }
+        end
+
+        describe '#ignore_models' do
+          subject { described_class.ignore_models }
+
+          context 'when not explicitly set' do
+            it { should eq([]) }
+          end
+
+          context 'when explicitly set' do
+            before { described_class.ignore_models = ["Fish"] }
+            after  { described_class.ignore_models = [] }
+            it     { should eq(["Fish"]) }
+          end
+
+          it 'should output deprecation warning' do
+            expect { described_class.ignore_models = ["Fish"] }.to output(/DEPRECATION WARNING: ignore_models= is deprecated/).to_stderr
+            expect { subject }.to output(/DEPRECATION WARNING: ignore_models is deprecated/).to_stderr
+          end
+
+          after { ::DeclareSchema.ignore_models = [] }
+        end
+```
+
+The outer `after` hooks in each block are a safety net so a failure mid-example (e.g. in the deprecation-warning test, which sets a non-default value but has no matching `after` of its own) can't leak state into later examples/spec files.
+
+- [ ] **Step 2: Run the new tests to verify they fail**
+
+Run: `bundle exec rspec spec/lib/generators/declare_schema/migration/migrator_spec.rb -e "#ignore_tables" -e "#ignore_models"`
+Expected: FAIL — `NoMethodError: undefined method 'ignore_tables=' for Generators::DeclareSchema::Migration::Migrator` (the setter currently exists as a plain `attr_accessor`, so it won't yet raise a deprecation warning, so the "should output deprecation warning" examples fail with no output matching `/DEPRECATION WARNING/`).
+
+- [ ] **Step 3: Add `ignore_tables`/`ignore_models` to `::DeclareSchema`**
+
+In `lib/declare_schema.rb`, change:
+
+```ruby
+  @default_charset                      = "utf8mb4"
+  @default_collation                    = "utf8mb4_bin"
+  @default_text_limit                   = 0xffff_ffff
+  @default_string_limit                 = nil
+  @default_null                         = false
+  @default_generate_foreign_keys        = true
+  @default_generate_indexing            = true
+  @db_migrate_command                   = "bundle exec rails db:migrate"
+
+  class << self
+    attr_writer :mysql_version
+    attr_reader :default_text_limit, :default_string_limit, :default_null,
+                :default_generate_foreign_keys, :default_generate_indexing, :db_migrate_command
+```
+
+to:
+
+```ruby
+  @default_charset                      = "utf8mb4"
+  @default_collation                    = "utf8mb4_bin"
+  @default_text_limit                   = 0xffff_ffff
+  @default_string_limit                 = nil
+  @default_null                         = false
+  @default_generate_foreign_keys        = true
+  @default_generate_indexing            = true
+  @db_migrate_command                   = "bundle exec rails db:migrate"
+  @ignore_tables                        = []
+  @ignore_models                        = []
+
+  class << self
+    attr_writer :mysql_version
+    attr_accessor :ignore_tables, :ignore_models
+    attr_reader :default_text_limit, :default_string_limit, :default_null,
+                :default_generate_foreign_keys, :default_generate_indexing, :db_migrate_command
+```
+
+- [ ] **Step 4: Delegate and deprecate on `Migrator`, remove its own accessors**
+
+In `lib/generators/declare_schema/migration/migrator.rb`, change:
+
+```ruby
+        @ignore_models                        = []
+        @ignore_tables                        = []
+        @before_generating_migration_callback = nil
+        @active_record_class                  = ActiveRecord::Base
+
+        class << self
+          attr_accessor :ignore_models, :ignore_tables
+          attr_reader :active_record_class, :before_generating_migration_callback
+```
+
+to:
+
+```ruby
+        @before_generating_migration_callback = nil
+        @active_record_class                  = ActiveRecord::Base
+
+        class << self
+          attr_reader :active_record_class, :before_generating_migration_callback
+```
+
+Then change:
+
+```ruby
+          delegate :default_charset=, :default_collation=, :default_charset, :default_collation, to: ::DeclareSchema
+          deprecate :default_charset=, :default_collation=, :default_charset, :default_collation, deprecator: ActiveSupport::Deprecation.new('1.0', 'declare_schema')
+        end
+```
+
+to:
+
+```ruby
+          delegate :default_charset=, :default_collation=, :default_charset, :default_collation,
+                   :ignore_tables=, :ignore_tables, :ignore_models=, :ignore_models, to: ::DeclareSchema
+          deprecate :default_charset=, :default_collation=, :default_charset, :default_collation,
+                    :ignore_tables=, :ignore_tables, :ignore_models=, :ignore_models,
+                    deprecator: ActiveSupport::Deprecation.new('1.0', 'declare_schema')
+        end
+```
+
+- [ ] **Step 5: Update the internal caller to avoid triggering the new deprecation warning**
+
+Still in `lib/generators/declare_schema/migration/migrator.rb`, in `models_and_tables`, change:
+
+```ruby
+        def models_and_tables
+          ignore_model_names = Migrator.ignore_models.map { |model| model.to_s.underscore }
+          all_models = table_model_classes
+          declare_schema_models = all_models.select do |m|
+            (m.name['HABTM_'] ||
+              (m.include_in_migration if m.respond_to?(:include_in_migration))) && !m.name.underscore.in?(ignore_model_names)
+          end
+          non_declare_schema_models = all_models - declare_schema_models
+          db_tables = connection.tables - Migrator.ignore_tables.map(&:to_s) - non_declare_schema_models.map(&:table_name)
+          [declare_schema_models, db_tables]
+        end
+```
+
+to:
+
+```ruby
+        def models_and_tables
+          ignore_model_names = ::DeclareSchema.ignore_models.map { |model| model.to_s.underscore }
+          all_models = table_model_classes
+          declare_schema_models = all_models.select do |m|
+            (m.name['HABTM_'] ||
+              (m.include_in_migration if m.respond_to?(:include_in_migration))) && !m.name.underscore.in?(ignore_model_names)
+          end
+          non_declare_schema_models = all_models - declare_schema_models
+          db_tables = connection.tables - ::DeclareSchema.ignore_tables.map(&:to_s) - non_declare_schema_models.map(&:table_name)
+          [declare_schema_models, db_tables]
+        end
+```
+
+- [ ] **Step 6: Run the new tests to verify they pass**
+
+Run: `bundle exec rspec spec/lib/generators/declare_schema/migration/migrator_spec.rb -e "#ignore_tables" -e "#ignore_models"`
+Expected: PASS (6 examples, 0 failures)
+
+- [ ] **Step 7: Update the pre-existing spec that used the now-deprecated setter**
+
+In `spec/lib/declare_schema/migration_generator_spec.rb:64`, change:
+
+```ruby
+      Generators::DeclareSchema::Migration::Migrator.ignore_tables = ["green_fishes"]
+```
+
+to:
+
+```ruby
+      ::DeclareSchema.ignore_tables = ["green_fishes"]
+```
+
+This avoids emitting an unrelated deprecation warning every time this (large, pre-existing) integration test runs.
+
+- [ ] **Step 8: Run the full test suite**
+
+Run: `bundle exec rspec`
+Expected: All examples pass, 0 failures (same pass count as before this task, plus the 6 new examples from Step 1).
+
+- [ ] **Step 9: Run Rubocop**
+
+Run: `bundle exec rubocop lib/declare_schema.rb lib/generators/declare_schema/migration/migrator.rb spec/lib/generators/declare_schema/migration/migrator_spec.rb spec/lib/declare_schema/migration_generator_spec.rb`
+Expected: No offenses.
+
+- [ ] **Step 10: Commit**
+
+```bash
+git add lib/declare_schema.rb lib/generators/declare_schema/migration/migrator.rb spec/lib/generators/declare_schema/migration/migrator_spec.rb spec/lib/declare_schema/migration_generator_spec.rb
+git commit -m "OCTO-893: Deprecate Migrator.ignore_tables/ignore_models
+
+Move ignore_tables and ignore_models to ::DeclareSchema, following the
+same delegate+deprecate pattern already used for default_charset and
+default_collation. The Migrator accessors keep working but emit an
+ActiveSupport deprecation warning; nothing is removed."
+```
+
+---
+
+### Task 2: Document the new settings in the README
+
+**Files:**
+- Modify: `README.md:377-394` (existing "Ignored Tables" section)
+
+**Interfaces:**
+- Consumes: `::DeclareSchema.ignore_tables` / `::DeclareSchema.ignore_models` from Task 1 (must already exist and work).
+
+- [ ] **Step 1: Update the "Ignored Tables" section and add a new "Ignored Models" section**
+
+In `README.md`, change:
+
+```markdown
+## Ignored Tables
+If a table's schema or metadata are managed elsewhere, `declare_schema` can be instructed to ignore it
+by adding those table names to the array assigned to `Generators::DeclareSchema::Migration::Migrator.ignore_tables`.
+For example:
+
+```ruby
+::Generators::DeclareSchema::Migration::Migrator.ignore_tables = [
+  "delayed_jobs",
+  "my_snowflake_table",
+  ...
+]
+```
+
+Note: `declare_schema` always ignores these tables:
+- The ActiveRecord `schema_info` table
+- The ActiveRecord schema migrations table (generally named `schema_migrations`)
+- The ActiveRecord internal metadata table (generally named `ar_internal_metadata`)
+- If defined/configured, the CGI ActiveRecordStore session table
+```
+
+to:
+
+```markdown
+## Ignored Tables
+If a table's schema or metadata are managed elsewhere, `declare_schema` can be instructed to ignore it
+by adding those table names to the array assigned to `DeclareSchema.ignore_tables`.
+For example:
+
+```ruby
+::DeclareSchema.ignore_tables = [
+  "delayed_jobs",
+  "my_snowflake_table",
+  ...
+]
+```
+
+**Deprecated:** `Generators::DeclareSchema::Migration::Migrator.ignore_tables` is a deprecated alias for
+`DeclareSchema.ignore_tables` above. It still works, but new code should use `DeclareSchema.ignore_tables`
+directly.
+
+Note: `declare_schema` always ignores these tables:
+- The ActiveRecord `schema_info` table
+- The ActiveRecord schema migrations table (generally named `schema_migrations`)
+- The ActiveRecord internal metadata table (generally named `ar_internal_metadata`)
+- If defined/configured, the CGI ActiveRecordStore session table
+
+## Ignored Models
+Similarly, `declare_schema` can be instructed to ignore specific models (so that no migration is
+generated for their table) by adding the model's underscored name to the array assigned to
+`DeclareSchema.ignore_models`. For example:
+
+```ruby
+::DeclareSchema.ignore_models = [
+  "my_legacy_model",
+  ...
+]
+```
+
+**Deprecated:** `Generators::DeclareSchema::Migration::Migrator.ignore_models` is a deprecated alias for
+`DeclareSchema.ignore_models` above. It still works, but new code should use `DeclareSchema.ignore_models`
+directly.
+```
+
+- [ ] **Step 2: Verify the README's fenced code blocks are balanced**
+
+Run: `grep -c '^```' README.md`
+Expected: An even number (each opened fence is closed).
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add README.md
+git commit -m "OCTO-893: Document DeclareSchema.ignore_tables and ignore_models
+
+Update the README's Ignored Tables section to point at the new public
+DeclareSchema.ignore_tables setting, and add a new Ignored Models
+section documenting DeclareSchema.ignore_models. Both note that the
+old Migrator-based settings are deprecated aliases."
+```
+
+---
+
+### Task 3: Bump version and update CHANGELOG
+
+**Files:**
+- Modify: `lib/declare_schema/version.rb`
+- Modify: `Gemfile.lock`
+- Modify: `CHANGELOG.md`
+
+**Interfaces:**
+- Consumes: nothing new — this is a release-metadata-only task, done after Tasks 1 and 2 are committed.
+
+- [ ] **Step 1: Bump the version**
+
+In `lib/declare_schema/version.rb`, change:
+
+```ruby
+module DeclareSchema
+  VERSION = "4.0.3"
+end
+```
+
+to:
+
+```ruby
+module DeclareSchema
+  VERSION = "4.1.0"
+end
+```
+
+- [ ] **Step 2: Update Gemfile.lock**
+
+Run: `bundle install`
+Expected: `Gemfile.lock`'s `PATH` section updates from `declare_schema (4.0.3)` to `declare_schema (4.1.0)`, and the `DEPENDENCIES`/lockfile line for `declare_schema (= 4.1.0)` (if present) updates to match.
+
+- [ ] **Step 3: Add the CHANGELOG entry**
+
+In `CHANGELOG.md`, change:
+
+```markdown
+Note: this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [4.0.3] - 2026-07-01
+```
+
+to (using today's actual date when this step is executed):
+
+```markdown
+Note: this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [4.1.0] - 2026-07-03
+### Added
+- `::DeclareSchema.ignore_tables` and `::DeclareSchema.ignore_models` as the new public
+  settings for ignoring tables/models during migration generation.
+
+### Deprecated
+- `Generators::DeclareSchema::Migration::Migrator.ignore_tables` and `.ignore_models` in
+  favor of `DeclareSchema.ignore_tables` and `DeclareSchema.ignore_models` above. The
+  `Migrator` accessors still work but emit a deprecation warning; they will not be
+  removed without a major version bump.
+
+## [4.0.3] - 2026-07-01
+```
+
+- [ ] **Step 4: Run the full test suite one more time**
+
+Run: `bundle exec rspec`
+Expected: All examples pass, 0 failures.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lib/declare_schema/version.rb Gemfile.lock CHANGELOG.md
+git commit -m "Bump version to 4.1.0
+
+Adds DeclareSchema.ignore_tables/ignore_models (OCTO-893), deprecating
+the old Migrator-based settings without removing them."
+```
+
+---
+
+## After This Plan
+
+- Do **not** push the branch, open a PR, or run `rake release` — those are explicit go/no-go decisions for the user, out of scope for this plan.
+- Once the user reviews the local commits, they can decide whether to push `OCTO-893/deprecate-migrator-ignore-tables` and open a PR.

data/docs/superpowers/specs/2026-07-03-ignore-tables-deprecation-design.md

@@ -0,0 +1,99 @@
+# Design: Deprecate `Migrator.ignore_tables`/`ignore_models` in favor of `DeclareSchema.ignore_tables`/`ignore_models`
+
+Jira: [OCTO-893](https://invoca.atlassian.net/browse/OCTO-893)
+
+## Problem
+
+`declare_schema`'s ignore-tables and ignore-models settings are currently configured
+through an internal implementation class:
+
+```ruby
+::Generators::DeclareSchema::Migration::Migrator.ignore_tables = [...]
+::Generators::DeclareSchema::Migration::Migrator.ignore_models = [...]
+```
+
+This leaks an internal `Migrator` class as public config API, inconsistent with the
+gem's public `DeclareSchema` namespace. The two settings are exact parallels of each
+other in the current code — same declaration, same init pattern, same usage style —
+so this design treats them identically.
+
+## Precedent
+
+This exact situation was already solved once before, for `default_charset` and
+`default_collation`, back in v0.10.0 (see `CHANGELOG.md`):
+
+> Moved and deprecated default settings for `default_charset` and `default_collation`
+> from `Generators::DeclareSchema::Migration::Migrator` to `::DeclareSchema`
+
+The implementation lives in
+`lib/generators/declare_schema/migration/migrator.rb`:
+
+```ruby
+delegate :default_charset=, :default_collation=, :default_charset, :default_collation, to: ::DeclareSchema
+deprecate :default_charset=, :default_collation=, :default_charset, :default_collation, deprecator: ActiveSupport::Deprecation.new('1.0', 'declare_schema')
+```
+
+This design reuses that same pattern for both `ignore_tables` and `ignore_models`.
+
+## Design
+
+1. **`lib/declare_schema.rb`**
+   - Add `@ignore_tables = []` and `@ignore_models = []` to the module's default instance
+     variables.
+   - Add `:ignore_tables, :ignore_models` to the module's `attr_accessor` list in `class << self`.
+
+2. **`lib/generators/declare_schema/migration/migrator.rb`**
+   - Remove `attr_accessor :ignore_models, :ignore_tables` entirely from `Migrator` (both
+     settings move to `::DeclareSchema`; nothing is left behind on `Migrator`).
+   - Add `:ignore_tables=, :ignore_tables, :ignore_models=, :ignore_models` to the existing
+     `delegate ... to: ::DeclareSchema` line.
+   - Add the same four methods to the existing `deprecate ...` line, reusing the same
+     `ActiveSupport::Deprecation.new('1.0', 'declare_schema')` instance (no new deprecator).
+   - Update the two internal callers in `models_and_tables` (currently `Migrator.ignore_tables`
+     at line ~111 and `Migrator.ignore_models` at line ~104) to call `::DeclareSchema.ignore_tables`
+     / `::DeclareSchema.ignore_models` directly, so normal migration generation doesn't trigger a
+     deprecation warning on every run — matching how `default_charset`/`default_collation` are
+     already called directly via `::DeclareSchema` elsewhere in this file.
+
+3. **Tests** — `spec/lib/generators/declare_schema/migration/migrator_spec.rb`
+   - Add `#ignore_tables` and `#ignore_models` describe blocks mirroring the existing
+     `#default_charset` block: value passthrough (default `[]`, explicit set/reset) and
+     deprecation-warning assertions for both the reader and writer of each.
+   - Update `spec/lib/declare_schema/migration_generator_spec.rb` (the one existing spec that
+     sets `Generators::DeclareSchema::Migration::Migrator.ignore_tables = ["green_fishes"]`)
+     to use `::DeclareSchema.ignore_tables = [...]` instead, so that unrelated test doesn't
+     emit deprecation noise.
+
+4. **README.md**
+   - Update the existing "Ignored Tables" section: primary documented setting becomes
+     `::DeclareSchema.ignore_tables`, with a note that `Migrator.ignore_tables` is deprecated
+     (still works, not removed).
+   - Add a new "Ignored Models" section (not previously documented) covering
+     `::DeclareSchema.ignore_models`, with the same deprecation note for
+     `Migrator.ignore_models`.
+
+5. **CHANGELOG.md**
+   - New `## [4.1.0]` entry:
+     - `### Added` — `::DeclareSchema.ignore_tables` and `::DeclareSchema.ignore_models` as
+       the new public settings.
+     - `### Deprecated` — `Generators::DeclareSchema::Migration::Migrator.ignore_tables` and
+       `.ignore_models` in favor of the above; still function, will not be removed without a
+       major version bump.
+
+6. **Versioning**
+   - Bump `4.0.3` → `4.1.0` (minor: new backward-compatible public API + non-breaking
+     deprecation, nothing removed).
+   - Separate commit touching only `lib/declare_schema/version.rb`, `Gemfile.lock`,
+     `CHANGELOG.md`, matching the repo's existing release-commit convention (see `40f47e3`).
+
+## Out of Scope
+
+- No changes to any application code that consumes this gem (follow-up, not part of this ticket).
+- No gem release / publish — implementation + local commits only, pending explicit
+  go-ahead to push/release.
+
+## Testing Plan
+
+- Unit tests per above (delegation + deprecation warning) for both settings.
+- Full existing spec suite must still pass (`bundle exec rspec`).
+- `bundle exec rubocop` clean.

data/lib/declare_schema/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DeclareSchema
-  VERSION = "4.0.3"
+  VERSION = "4.1.0"
 end

data/lib/declare_schema.rb

@@ -32,10 +32,12 @@ module DeclareSchema
   @default_generate_foreign_keys        = true
   @default_generate_indexing            = true
   @db_migrate_command                   = "bundle exec rails db:migrate"
+  @ignore_tables                        = []
+  @ignore_models                        = []
 
   class << self
     attr_writer :mysql_version
-    attr_reader :default_text_limit, :default_string_limit, :default_null,
+    attr_reader :ignore_tables, :ignore_models, :default_text_limit, :default_string_limit, :default_null,
                 :default_generate_foreign_keys, :default_generate_indexing, :db_migrate_command
 
     def to_class(type)
@@ -122,6 +124,16 @@ module DeclareSchema
       @default_generate_indexing = generate_indexing
     end
 
+    def ignore_tables=(ignore_tables)
+      ignore_tables.nil? or ignore_tables.is_a?(Array) or raise ArgumentError, "ignore_tables must be an array or nil (got #{ignore_tables.inspect})"
+      @ignore_tables = ignore_tables || []
+    end
+
+    def ignore_models=(ignore_models)
+      ignore_models.nil? or ignore_models.is_a?(Array) or raise ArgumentError, "ignore_models must be an array or nil (got #{ignore_models.inspect})"
+      @ignore_models = ignore_models || []
+    end
+
     def default_schema(&block)
       if block.nil?
         @default_schema # equivalent to attr_reader :default_schema

data/lib/generators/declare_schema/migration/migrator.rb

@@ -11,13 +11,10 @@ module Generators
       class Migrator
         class Error < RuntimeError; end
 
-        @ignore_models                        = []
-        @ignore_tables                        = []
         @before_generating_migration_callback = nil
         @active_record_class                  = ActiveRecord::Base
 
         class << self
-          attr_accessor :ignore_models, :ignore_tables
           attr_reader :active_record_class, :before_generating_migration_callback
 
           def active_record_class
@@ -43,8 +40,11 @@ module Generators
             @before_generating_migration_callback = block
           end
 
-          delegate :default_charset=, :default_collation=, :default_charset, :default_collation, to: ::DeclareSchema
-          deprecate :default_charset=, :default_collation=, :default_charset, :default_collation, deprecator: ActiveSupport::Deprecation.new('1.0', 'declare_schema')
+          delegate :default_charset=, :default_collation=, :default_charset, :default_collation,
+                   :ignore_tables=, :ignore_tables, :ignore_models=, :ignore_models, to: ::DeclareSchema
+          deprecate :default_charset=, :default_collation=, :default_charset, :default_collation,
+                    :ignore_tables=, :ignore_tables, :ignore_models=, :ignore_models,
+                    deprecator: ActiveSupport::Deprecation.new('5.0', 'declare_schema')
         end
 
         def initialize(renames: nil, &block)
@@ -101,14 +101,14 @@ module Generators
         # Returns an array of model classes and an array of table names
         # that generation needs to take into account
         def models_and_tables
-          ignore_model_names = Migrator.ignore_models.map { |model| model.to_s.underscore }
+          ignore_model_names = ::DeclareSchema.ignore_models.map { |model| model.to_s.underscore }
           all_models = table_model_classes
           declare_schema_models = all_models.select do |m|
             (m.name['HABTM_'] ||
               (m.include_in_migration if m.respond_to?(:include_in_migration))) && !m.name.underscore.in?(ignore_model_names)
           end
           non_declare_schema_models = all_models - declare_schema_models
-          db_tables = connection.tables - Migrator.ignore_tables.map(&:to_s) - non_declare_schema_models.map(&:table_name)
+          db_tables = connection.tables - ::DeclareSchema.ignore_tables.map(&:to_s) - non_declare_schema_models.map(&:table_name)
           [declare_schema_models, db_tables]
         end
 

data/spec/lib/declare_schema/migration_generator_spec.rb

@@ -51,6 +51,8 @@ RSpec.describe 'DeclareSchema Migration Generator' do
   end
 
   context 'Using declare_schema' do
+    after { ::DeclareSchema.ignore_tables = [] }
+
     # DeclareSchema - Migration Generator
     it 'generates migrations' do
       ## The migration generator -- introduction
@@ -61,7 +63,7 @@ RSpec.describe 'DeclareSchema Migration Generator' do
 
       expect(Generators::DeclareSchema::Migration::Migrator.run).to migrate_up("").and migrate_down("")
 
-      Generators::DeclareSchema::Migration::Migrator.ignore_tables = ["green_fishes"]
+      ::DeclareSchema.ignore_tables = ["green_fishes"]
 
       Advert.connection.schema_cache.clear!
       Advert.reset_column_information

data/spec/lib/declare_schema_spec.rb

@@ -193,6 +193,58 @@ RSpec.describe DeclareSchema do
     end
   end
 
+  describe '#ignore_tables' do
+    subject { described_class.ignore_tables }
+
+    context 'when not explicitly set' do
+      it { is_expected.to eq([]) }
+    end
+
+    context 'when explicitly set to an array' do
+      before { described_class.ignore_tables = ["green_fishes"] }
+      after  { described_class.ignore_tables = [] }
+      it     { is_expected.to eq(["green_fishes"]) }
+    end
+
+    context 'when explicitly set to nil' do
+      before { described_class.ignore_tables = nil }
+      after  { described_class.ignore_tables = [] }
+      it     { is_expected.to eq([]) }
+    end
+
+    context 'when set to a non-Array' do
+      it 'raises ArgumentError' do
+        expect { described_class.ignore_tables = "green_fishes" }.to raise_error(ArgumentError, /ignore_tables must be an array or nil/)
+      end
+    end
+  end
+
+  describe '#ignore_models' do
+    subject { described_class.ignore_models }
+
+    context 'when not explicitly set' do
+      it { is_expected.to eq([]) }
+    end
+
+    context 'when explicitly set to an array' do
+      before { described_class.ignore_models = ["Fish"] }
+      after  { described_class.ignore_models = [] }
+      it     { is_expected.to eq(["Fish"]) }
+    end
+
+    context 'when explicitly set to nil' do
+      before { described_class.ignore_models = nil }
+      after  { described_class.ignore_models = [] }
+      it     { is_expected.to eq([]) }
+    end
+
+    context 'when set to a non-Array' do
+      it 'raises ArgumentError' do
+        expect { described_class.ignore_models = "Fish" }.to raise_error(ArgumentError, /ignore_models must be an array or nil/)
+      end
+    end
+  end
+
   describe '#max_index_and_constraint_name_length' do
     subject { described_class.max_index_and_constraint_name_length }
 

data/spec/lib/generators/declare_schema/migration/migrator_spec.rb

@@ -56,6 +56,48 @@ module Generators
           end
         end
 
+        describe '#ignore_tables' do
+          subject { described_class.ignore_tables }
+
+          context 'when not explicitly set' do
+            it { should eq([]) }
+          end
+
+          context 'when explicitly set' do
+            before { described_class.ignore_tables = ["green_fishes"] }
+            after  { described_class.ignore_tables = [] }
+            it     { should eq(["green_fishes"]) }
+          end
+
+          it 'should output deprecation warning' do
+            expect { described_class.ignore_tables = ["green_fishes"] }.to output(/DEPRECATION WARNING: ignore_tables= is deprecated/).to_stderr
+            expect { subject }.to output(/DEPRECATION WARNING: ignore_tables is deprecated/).to_stderr
+          end
+
+          after { ::DeclareSchema.ignore_tables = [] }
+        end
+
+        describe '#ignore_models' do
+          subject { described_class.ignore_models }
+
+          context 'when not explicitly set' do
+            it { should eq([]) }
+          end
+
+          context 'when explicitly set' do
+            before { described_class.ignore_models = ["Fish"] }
+            after  { described_class.ignore_models = [] }
+            it     { should eq(["Fish"]) }
+          end
+
+          it 'should output deprecation warning' do
+            expect { described_class.ignore_models = ["Fish"] }.to output(/DEPRECATION WARNING: ignore_models= is deprecated/).to_stderr
+            expect { subject }.to output(/DEPRECATION WARNING: ignore_models is deprecated/).to_stderr
+          end
+
+          after { ::DeclareSchema.ignore_models = [] }
+        end
+
         describe '#load_rails_models' do
           before do
             expect(Rails.application).to receive(:eager_load!)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: declare_schema
 version: !ruby/object:Gem::Version
-  version: 4.0.3
+  version: 4.1.0
 platform: ruby
 authors:
 - Invoca Development adapted from hobo_fields by Tom Locke
@@ -55,6 +55,8 @@ files:
 - catalog-info.yaml
 - config/brakeman.ignore
 - declare_schema.gemspec
+- docs/superpowers/plans/2026-07-03-ignore-tables-ignore-models-deprecation.md
+- docs/superpowers/specs/2026-07-03-ignore-tables-deprecation-design.md
 - gemfiles/.bundle/config
 - gemfiles/rails_7_0.gemfile
 - gemfiles/rails_7_1.gemfile