declare_schema 4.0.2 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3db1e6df4c65a27e4bd67f67792713c59ff42daa35a210046e1f3bb2e970162
-  data.tar.gz: 1f8ac6833eb61da99b86ded414b2c551296f045e238efc09cfc43ca2a6ac0812
+  metadata.gz: 515b75b80f3aec9fa977aebe9874ad015bd16def4a07ed0f7c86fee3fd51e6ac
+  data.tar.gz: 5bac16aa76fcb28b74b0beaae97c7ddd6f4e7a5f939feae9f4948f7ef1f74606
 SHA512:
-  metadata.gz: 99f97e8dc9a8819af6ef940cab00fe23a0f25c04db0beb2e463c64fadee1b8618c0410c210088e702d05f70855b3a0f8659a2dd10288f13ed5ef3eefb42b4538
-  data.tar.gz: 875a01a7b75ef5dc1cc4d4025b903cd2c0ab14ab901758fd183594a0db6c67b673357243e71efc1a1bdacb12676ee35ad226100daf10f9877155580f686b2f16
+  metadata.gz: 5db28ddddef093068697c0caf0f1797eacf82bb94e6b56353dc5b31bae8c442ccab1287eea8495e9ade030f41d1053031d6499c688e4588667b6e8748bcff2c9
+  data.tar.gz: c433348df1b1ae6db97878e2afac920f8fafff5d19995fe75a297be6d01d05ec4db1f183249457a2b5a86c7d2fd4cfa6f36b3f0db2042571960e7a19fe7056f9

data/CHANGELOG.md

@@ -4,6 +4,21 @@ 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.
+
 ## [4.0.2] - 2026-05-29
 ### Fixed
 - Fixed Rails 7.2 compatibility for the `serialize:` field option. Rails 7.2 changed

data/Gemfile.lock

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

data/README.md

@@ -89,6 +89,75 @@ create_table :companies, id: :bigint do |t|
     ...
 end
 ```
+### The `field` Macro
+Every `t.<type> :<column_name>, <options>` declaration shown above is syntactic sugar for calling the `field` macro directly:
+```ruby
+create_table :companies, id: :bigint do |t|
+  t.field :company_name, :string, null: false, limit: 100
+    ...
+end
+```
+`field(name, type, *flags, **options)` is the primitive method underlying every typed shorthand (`t.string`, `t.integer`, etc.), as well as the `timestamps` and `optimistic_lock` helpers. A call like `t.string :company_name, limit: 100` is dispatched (via `method_missing`) to `t.field :company_name, :string, limit: 100`.
+
+`field` only exists inside the `declare_schema do ... end` block, but within it, it can be called either with an explicit `t.` receiver (`t.field ...`) or bare (`field ...`), since the block is `instance_eval`'d against the DSL object -- both forms are equivalent. `field` cannot be called outside of the `declare_schema do ... end` block.
+
+Calling `field` directly is useful when you need to dynamically declare field(s) based on meta-data that is available at runtime:
+```ruby
+declare_schema do
+  [[:company_name, :string, { limit: 100 }], [:employee_count, :integer, {}]].each do |name, type, options|
+    field name, type, **options
+  end
+end
+```
+
+#### `:required` and `:unique` Flags
+In addition to keyword options, `field` (and by extension, `t.<type>`) accepts optional positional flags placed immediately after the column name:
+- `:required` - adds `validates_presence_of :<column_name>` to the model.
+- `:unique` - adds `validates_uniqueness_of :<column_name>, allow_nil: <true unless :required is also given>` to the model.
+
+For example:
+```ruby
+declare_schema do
+  string :title, :required, limit: 255
+  string :slug,  :unique,   limit: 255
+end
+```
+is equivalent to:
+```ruby
+declare_schema do
+  field :title, :string, :required, limit: 255
+  field :slug,  :string, :unique,   limit: 255
+end
+```
+
+#### Calling `declare_field` outside the block
+`field` is DSL sugar that simply calls the model's `declare_field` class method: `field(name, type, *flags, **options)` calls `declare_field(name, type, *flags, **options)`. Unlike `field`, `declare_field` is a regular class method, so it can be called directly on the model outside of a `declare_schema do ... end` block, e.g. from a shared concern that adds a field to any model that includes it:
+```ruby
+module SoftDeletable
+  extend ActiveSupport::Concern
+
+  included do
+    declare_schema { }
+    declare_field :title, :string, :required, limit: 255
+    declare_field :slug,  :string, :unique,   limit: 255
+  end
+end
+```
+which is equivalent to:
+```ruby
+module SoftDeletable
+  extend ActiveSupport::Concern
+
+  included do
+    declare_schema do
+      field :title, :string, :required, limit: 255
+      field :slug,  :string, :unique,   limit: 255
+    end
+  end
+end
+```
+**Note:** `declare_field` is only defined once `declare_schema` has been called at least once on the model (even with no block, e.g. bare `declare_schema`), since that's what mixes in the `DeclareSchema` class methods.
+
 ### Field (Column) Types
 All of the ActiveRecord field types are supported, as returned by the database driver in use at the time.
 These typically include:
@@ -307,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.2"
+  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,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: declare_schema
 version: !ruby/object:Gem::Version
-  version: 4.0.2
+  version: 4.1.0
 platform: ruby
 authors:
 - Invoca Development adapted from hobo_fields by Tom Locke
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-29 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -56,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
@@ -144,7 +145,6 @@ homepage: https://github.com/Invoca/declare_schema
 licenses: []
 metadata:
   allowed_push_host: https://rubygems.org
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -159,8 +159,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: 1.3.6
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.8
 specification_version: 4
 summary: Database schema declaration and migration generator for Rails
 test_files: []