yiffspace-fixers 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2deff4a56be5dc1abebbb670f5a509a11f4d257cc2daba5033b9bb87820fb6d4
+  data.tar.gz: b19fd72d813bc38fa5a915c876eb4e47f7c15fcf0d051ef3851a7afd9fe3eded
+SHA512:
+  metadata.gz: d1225851f6be5102fe8598353e347e1a4cbd2f771c2139e8156c850fb50d8a6c136c51a6da3ef0d8dd9f23fdc4586dbc375d129b32461163fb9bdf7b2182ffa9
+  data.tar.gz: 9c1e989b7c8f83314de5b30d6ab7e5b9499611b6bcc5569b9459156fd2761d52dcc8f391c330205c2db29d50f4bb9802209b26f6dd39d4491025d63113bd206d

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+## 0.0.1
+
+- Initial release, extracted from the `yiffspace` gem's `YiffSpace::FixTracker`/
+  `YiffSpace::FixerTemplate`/`YiffSpace::Configuration::FixerTemplates`, the
+  `yiffspace:fixer`/`yiffspace:install:fixes` generators, and the `fixes:*`
+  rake tasks.

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright Donovan_DMC
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,60 @@
+# YiffSpace::Fixers
+
+One-time `db/fixes/*.rb` scripts, tracked the same way ActiveRecord's own
+`schema_migrations` tracks migrations - for https://yiff.space and related
+projects. Lives alongside, and depends on, the [`yiffspace`](../yiffspace)
+gem in this repo.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "yiffspace-fixers"
+```
+
+And then execute:
+
+```bash
+$ bundle install
+$ bin/rails generate yiffspace:install:fixes
+$ bin/rails db:migrate
+```
+
+## Usage
+
+```bash
+$ bin/rails generate yiffspace:fixer some_description
+$ bin/rails fixes:list
+$ bin/rails fixes:migrate
+```
+
+A fix can require that a migration has already been applied, and a migration can require that a
+fix has already been applied - useful when one depends on schema or data the other provides.
+`bin/rails fixes:migrate_all` runs both `db/migrate` and `db/fixes` together, in whichever order
+those requirements demand:
+
+```ruby
+# db/fixes/12_backfill_widget_type.rb
+YiffSpace::FixTracker.requires_migration!("20260822004454")
+
+# db/migrate/20260901000000_remove_legacy_widget_column.rb
+class RemoveLegacyWidgetColumn < ActiveRecord::Migration[8.1]
+  requires_fix(12)
+
+  def change
+    ...
+  end
+end
+```
+
+See `YiffSpace::FixTracker`, `YiffSpace::FixerTemplate`, `YiffSpace::Fixers::RequiresFix`, and
+`YiffSpace::MigrationSync` for the full API.
+
+## Contributing
+
+Go away
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require("bundler/setup")
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load("rails/tasks/engine.rake")
+
+load("rails/tasks/statistics.rake")
+
+require("bundler/gem_tasks")
+
+# CI releases from an already-tagged, already-pushed commit checked out at a detached HEAD, so
+# the default release task's git tag/push step has nothing to do and fails trying to push a
+# branch ref that does not exist in that checkout.
+Rake::Task["release"].clear
+task("release" => "release:rubygem_push")

data/lib/generators/yiffspace/fixer/USAGE

@@ -0,0 +1,40 @@
+Description:
+    Generates a new one-time fix script tracked by YiffSpace::FixTracker.
+
+Example:
+    bin/rails generate yiffspace:fixer fixer_name
+
+    This will create:
+        db/fixes/<id>_fixer_name.rb
+
+    bin/rails generate yiffspace:fixer fixer_name --steps 2
+
+    This will create:
+        db/fixes/<id>_1_fixer_name.rb
+        db/fixes/<id>_2_fixer_name.rb
+
+    A host app can define named templates, auto-discovered from db/fixer_templates/*.rb (see
+    YiffSpace::FixerTemplate and YiffSpace.config.fixer_templates_path) - no registration needed,
+    just define a subclass. Each `step` block's return value becomes that step's file content:
+
+        # db/fixer_templates/elasticsearch_template.rb
+        class ElasticsearchTemplate < YiffSpace::FixerTemplate
+          short("e")
+
+          step { "# add the elasticsearch index\n" }
+          step { "# backfill the elasticsearch data\n" }
+        end
+
+    bin/rails generate yiffspace:fixer fixer_name --template elasticsearch
+    bin/rails generate yiffspace:fixer fixer_name -t elasticsearch
+    bin/rails generate yiffspace:fixer fixer_name -e
+
+    All three create the 2 steps above; `short` is optional - a template is always reachable via
+    --template/-t, the shortname flag is just a convenience.
+
+    A host app can also register a preset with just a step count (no per-step content - every
+    step falls back to the generic fixer.rb template) directly in an initializer instead:
+
+        YiffSpace.configure do |config|
+          config.fixer_templates.register(:legacy, steps: 3)
+        end

data/lib/generators/yiffspace/fixer/fixer_generator.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Yiffspace
+  # Scaffolds a new db/fixes/*.rb script for YiffSpace::FixTracker (see `rake fixes:list`).
+  #
+  # `--steps N` splits the fix into N ordered steps sharing an id, each one a copy of the generic
+  # fixer.rb template. A host app can instead define a YiffSpace::FixerTemplate subclass (see that
+  # class) to control both the step count and each step's file content, auto-discovered from
+  # YiffSpace.config.fixer_templates_path - reachable here with `--template <name>`/`-t <name>`,
+  # or with the template's own shortname flag if it registered one (e.g. `-e`).
+  class FixerGenerator < Rails::Generators::NamedBase
+    source_root(File.expand_path("templates", __dir__))
+    # No short alias - -s/-f/-p/-q are already claimed by Rails::Generators::Base's own runtime
+    # options (--skip/--force/--pretend/--quiet), and Thor silently lets the last-defined
+    # class_option win a collision instead of erroring.
+    class_option(:steps, type: :numeric, default: 1,
+                          desc: "Split the fix into N ordered steps sharing an id, e.g. 12_1_name.rb, 12_2_name.rb")
+    class_option(:template, type: :string, default: nil, aliases: ["-t"],
+                             desc: "Use a fixer template registered with YiffSpace.config.fixer_templates")
+
+    YiffSpace.config.fixer_templates.each do |template|
+      next unless template.short
+
+      class_option(template.name.to_sym, type: :boolean, default: false, aliases: ["-#{template.short}"],
+                                          desc: "Shortcut for --template #{template.name}")
+    end
+
+    def create_fixer
+      content_blocks = resolve_content_blocks
+
+      id = Dir[File.join(destination_root, "db/fixes/*.rb")].map { |f| File.basename(f, ".rb").split("_").first.to_i }.max.to_i + 1
+
+      if content_blocks.size == 1
+        create_fixer_file("db/fixes/#{id}_#{file_name}.rb", content_blocks.first)
+      else
+        content_blocks.each_with_index { |block, index| create_fixer_file("db/fixes/#{id}_#{index + 1}_#{file_name}.rb", block) }
+      end
+    end
+
+    private
+
+    # One entry per step - a block returning that step's file content, or nil to fall back to
+    # copying the generic fixer.rb template (a plain --steps N, or a manually
+    # YiffSpace.config.fixer_templates.register'd template, has no per-step content).
+    def resolve_content_blocks
+      template = resolve_template
+      return template.content_blocks if template
+
+      Array.new(steps_from_flag)
+    end
+
+    def resolve_template
+      name = template_name
+      return nil if name.nil?
+
+      template = YiffSpace.config.fixer_templates[name]
+      raise(Thor::Error, "no fixer template named #{name.inspect} is registered") unless template
+
+      template
+    end
+
+    # The template chosen via `--template <name>`, or via a registered template's own shortname
+    # flag (e.g. `-e` for a template registered with `short: "e"`) - nil if neither was passed.
+    def template_name
+      return options["template"] if options["template"]
+
+      YiffSpace.config.fixer_templates.find { |template| template.short && options[template.name] }&.name
+    end
+
+    def steps_from_flag
+      steps = options["steps"].to_i
+      raise(Thor::Error, "--steps must be at least 1") if steps < 1
+
+      steps
+    end
+
+    def create_fixer_file(path, content_block)
+      if content_block
+        create_file(path, content_block.call)
+        chmod(path, "+x")
+      else
+        copy_file("fixer.rb", path, mode: :preserve)
+      end
+    end
+  end
+end

data/lib/generators/yiffspace/fixer/templates/fixer.rb

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require(File.expand_path(File.join(File.dirname(__FILE__), "..", "..", "config", "environment")))

data/lib/generators/yiffspace/install/fixes_generator.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Yiffspace
+  module Install
+    # Installs YiffSpace::FixTracker into a host app: `bin/rails generate yiffspace:install:fixes`
+    # copies the `fixes` tracking table migration. Run `bin/rails db:migrate` afterwards.
+    class FixesGenerator < Rails::Generators::Base
+      include(Rails::Generators::Migration)
+
+      source_root(File.expand_path("templates", __dir__))
+
+      def self.next_migration_number(dirname)
+        ActiveRecord::Migration.next_migration_number(current_migration_number(dirname) + 1)
+      end
+
+      def create_migration_file
+        migration_template("create_fixes.rb.erb", "db/migrate/create_fixes.rb")
+      end
+    end
+  end
+end

data/lib/generators/yiffspace/install/templates/create_fixes.rb.erb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Tracks which db/fixes/*.rb scripts have been applied, the same way schema_migrations tracks
+# migrations - see YiffSpace::FixTracker and `rake fixes:migrate`/`rake fixes:list`.
+#
+# `id` is the fix's own leading number (e.g. 12, 23), not a surrogate key, so it isn't unique on
+# its own - a fix can be split into ordered sub-steps (12_1, 12_2, ...) that share an id and are
+# distinguished by `index`. `index` is null for fixes with no subtype.
+class CreateFixes < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_table(:fixes, id: false) do |t|
+      t.integer(:id, null: false) # not a surrogate key, this is the fix's own leading number
+      t.integer(:index)
+    end
+
+    add_index(:fixes, %i[id index], unique: true, nulls_not_distinct: true)
+  end
+end

data/lib/tasks/fixes.rake

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+# Keep structure.sql's fixes rows in sync with the database on every schema dump, the same way
+# ActiveRecord keeps schema_migrations rows in sync - not just when `fixes:migrate` runs.
+Rake::Task["db:schema:dump"].enhance do
+  YiffSpace::FixTracker.dump_structure_sql!
+end
+
+namespace(:fixes) do
+  desc("List available fix scripts in db/fixes, marking which have already been applied")
+  task(list: :environment) do
+    applied = YiffSpace::FixTracker.applied
+    YiffSpace::FixTracker.all_fixes.each do |name|
+      puts("#{applied.include?(YiffSpace::FixTracker.key_for(name)) ? '[x]' : '[ ]'} #{name}")
+    end
+  end
+
+  desc("Run a fix script from db/fixes by id or name, e.g. `rake fixes:run[1]` - re-runs even if already recorded as applied")
+  task(:run, [:name] => :environment) do |_task, args|
+    name = args[:name].to_s.delete_suffix(".rb")
+    abort("Usage: rake fixes:run[id_or_name] (see `rake fixes:list`)") if name.blank?
+
+    candidates = Dir["db/fixes/*.rb"]
+    exact = candidates.find { |path| File.basename(path, ".rb") == name }
+    matches = exact ? [exact] : candidates.select { |path| File.basename(path, ".rb").start_with?("#{name}_") || File.basename(path, ".rb").include?(name) }
+
+    if matches.empty?
+      abort("No fix matches \"#{name}\". Run `rake fixes:list` to see available fixes.")
+    elsif matches.size > 1
+      abort("Multiple fixes match \"#{name}\", be more specific:\n#{matches.map { |m| "  #{File.basename(m, '.rb')}" }.join("\n")}")
+    end
+
+    puts("Running #{File.basename(matches.first, '.rb')}...")
+    name = YiffSpace::FixTracker.run!(matches.first)
+    puts("Recorded #{name} as applied")
+  end
+
+  desc("Apply all fix scripts not yet recorded as applied, in order, then dump the schema like db:migrate does")
+  task(migrate: :environment) do
+    pending = YiffSpace::FixTracker.pending
+
+    if pending.empty?
+      puts("No pending fixes.")
+    else
+      pending.each do |name|
+        puts("Running #{name}...")
+        YiffSpace::FixTracker.run!(YiffSpace::FixTracker.fix_path(name))
+        puts("Recorded #{name} as applied")
+      end
+    end
+
+    Rake::Task["db:_dump"].invoke
+  end
+end
+
+# Split into its own namespace block, rather than growing the one above past
+# Metrics/BlockLength's max - Rake happily reopens a namespace.
+namespace(:fixes) do
+  desc("Apply all pending db/migrate migrations and db/fixes fixes together, in whichever order their requires_fix/requires_migration! declarations demand")
+  task(migrate_all: :environment) do
+    steps = YiffSpace::MigrationSync.plan
+
+    if steps.empty?
+      puts("Nothing to migrate or fix.")
+    else
+      steps.each do |step|
+        puts(YiffSpace::MigrationSync.describe(step))
+        YiffSpace::MigrationSync.apply(step)
+      end
+    end
+
+    Rake::Task["db:_dump"].invoke
+  end
+
+  desc("Record all of the current fixes as having been applied")
+  task(load: :environment) do
+    list = YiffSpace::FixTracker.all_fixes.map { YiffSpace::FixTracker.key_for(it) }
+    existing = ActiveRecord::Base.connection.select_all('SELECT id, "index" FROM fixes ORDER BY id, "index"').rows
+    list.reject! { |id, index| existing.any? { |e| e[0] == id && e[1] == index } }
+    unless list.empty?
+      values = list.map { |id, index| "(#{id}, #{index.nil? ? 'NULL' : index})" }.join(", ")
+      ActiveRecord::Base.connection.execute(%(INSERT INTO fixes (id, "index") VALUES #{values}))
+    end
+    puts("Loaded #{list.length} #{'fix'.pluralize(list.length)}")
+  end
+end

data/lib/yiffspace/configuration/fixer_templates.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module YiffSpace
+  class Configuration
+    # Named presets for `bin/rails generate yiffspace:fixer`, so `--template <name>` (or a
+    # registered shortname flag) can stand in for `--steps N`. Populated two ways:
+    #
+    # - Automatically, from YiffSpace::FixerTemplate subclasses found in
+    #   YiffSpace.config.fixer_templates_path (the common case - see FixerTemplate).
+    # - Manually, via #register, for a preset that just needs a step count and no per-step
+    #   content (every step falls back to the generic fixer.rb template).
+    #
+    # See YiffSpace::Configuration#fixer_templates and Yiffspace::FixerGenerator.
+    class FixerTemplates
+      include(Enumerable)
+
+      Template = Struct.new(:name, :short, :content_blocks, keyword_init: true) do
+        def steps
+          content_blocks.size
+        end
+      end
+
+      # -t is yiffspace:fixer's own --template flag; -f/-p/-q/-s are Rails::Generators::Base's
+      # built-in runtime options (--force/--pretend/--quiet/--skip).
+      RESERVED_SHORTS = %w[t f p q s].freeze
+
+      def initialize
+        @templates = {}
+        @discovered = false
+      end
+
+      # short is optional - a template is always reachable via `--template <name>`, a shortname
+      # flag (e.g. `-e`) is just a convenient alias for it.
+      def register(name, steps:, short: nil)
+        raise(ArgumentError, "steps must be a positive integer, got #{steps.inspect}") unless steps.is_a?(Integer) && steps.positive?
+
+        add(name.to_s, short: short, content_blocks: Array.new(steps))
+      end
+
+      def [](name)
+        discover!
+        @templates[name.to_s]
+      end
+
+      def each(&)
+        discover!
+        @templates.each_value(&)
+      end
+
+      private
+
+      def add(name, short:, content_blocks:)
+        raise(ArgumentError, "a fixer template named #{name.inspect} is already registered") if @templates.key?(name)
+
+        short = short.to_s.delete_prefix("-") if short
+        if short
+          raise(ArgumentError, "\"-#{short}\" is reserved by yiffspace:fixer's own options") if RESERVED_SHORTS.include?(short)
+
+          existing = @templates.values.find { |template| template.short == short }
+          raise(ArgumentError, "\"-#{short}\" is already registered to the #{existing.name.inspect} fixer template") if existing
+        end
+
+        @templates[name] = Template.new(name: name, short: short, content_blocks: content_blocks)
+      end
+
+      # Scans YiffSpace.config.fixer_templates_path for YiffSpace::FixerTemplate subclasses and
+      # registers each one - runs once, the first time a template is looked up (#[] or #each),
+      # so it sees whatever the host app registered manually beforehand.
+      def discover!
+        return if @discovered
+
+        @discovered = true
+        path = YiffSpace.config.fixer_templates_path
+        return unless path && Dir.exist?(path)
+
+        before = FixerTemplate.subclasses
+        Dir[File.join(path, "*.rb")].each { |file| require(file) }
+
+        (FixerTemplate.subclasses - before).each do |klass|
+          raise(ArgumentError, "#{klass.name} has no step blocks - add at least one `step { ... }`") if klass.steps.empty?
+
+          add(klass.template_name, short: klass.short, content_blocks: klass.steps)
+        end
+      end
+    end
+  end
+end

data/lib/yiffspace/fix_tracker.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module YiffSpace
+  # Tracks which db/fixes/*.rb scripts a host app has applied, in a `fixes` table (see
+  # db/migrate/*_create_fixes.rb) the same way ActiveRecord's own schema_migrations table
+  # tracks migrations. Used by the `fixes:*` rake tasks (lib/tasks/fixes.rake).
+  module FixTracker
+    # Raised by requires_migration! when the required migration hasn't been applied yet.
+    class MigrationRequired < StandardError; end
+
+    # A fix script calls this as its first statement to declare that a migration must already be
+    # applied before it can run, e.g.:
+    #
+    #   YiffSpace::FixTracker.requires_migration!("20260822004454")
+    #
+    # Written as a literal string call like that (not built dynamically) so YiffSpace::MigrationSync
+    # can also read it back out of the file with #required_migration_for, without loading/running
+    # the fix, to order `fixes:migrate_all` correctly.
+    REQUIRES_MIGRATION_PATTERN = /^\s*YiffSpace::FixTracker\.requires_migration!\(\s*["']([^"']+)["']\s*\)/
+
+    module_function
+
+    def fix_path(name)
+      Rails.root.glob("db/fixes/#{name}.rb").first
+    end
+
+    def requires_migration!(version)
+      return if migration_applied?(version)
+
+      raise(MigrationRequired, "migration #{version} must be applied before this fix can run")
+    end
+
+    def migration_applied?(version)
+      migration_context.get_all_versions.include?(version.to_i)
+    end
+
+    # Statically reads a fix script's declared requires_migration! version, if any, without
+    # loading/running it - nil if the fix has no such call.
+    def required_migration_for(name)
+      path = fix_path(name)
+      return nil unless path
+
+      path.read.match(REQUIRES_MIGRATION_PATTERN)&.captures&.first
+    end
+
+    # Resolves a YiffSpace::Fixers::RequiresFix id_or_name to the fix name(s) it refers to - an
+    # Integer id covers every step sharing that id (e.g. 2 -> %w[2_1_first_step 2_2_second_step]),
+    # a name matches that one fix file exactly.
+    def resolve(id_or_name)
+      if id_or_name.is_a?(Integer)
+        all_fixes.select { |name| key_for(name).first == id_or_name }
+      else
+        name = id_or_name.to_s.delete_suffix(".rb")
+        all_fixes.select { |candidate| candidate == name }
+      end
+    end
+
+    def migration_context
+      ActiveRecord::Tasks::DatabaseTasks.migration_connection_pool.migration_context
+    end
+
+    # db/fixes filenames are "<id>_description.rb", occasionally "<id>_<index>_description.rb"
+    # (e.g. 1_1_..., 1_2_...) for a handful of fixes split into ordered steps - the `fixes`
+    # table mirrors this as an (id, index) pair, with index null for fixes with no subtype.
+    def key_for(name)
+      id, maybe_index = name.split("_", 3)
+      index = maybe_index =~ /\A\d+\z/ ? maybe_index.to_i : nil
+      [id.to_i, index]
+    end
+
+    # Sort on the (id, index) parts, not the filename string, so 12 doesn't sort before 2_2.
+    def sort_key(name)
+      id, index = key_for(name)
+      [id, index || 0]
+    end
+
+    # Only numbered one-time fixes are tracked/auto-applied - a host app's db/fixes may also hold
+    # reusable on-demand maintenance scripts that aren't meant to run automatically as part of
+    # `fixes:migrate`. Those stay reachable via `fixes:run[name]`.
+    def all_fixes
+      Rails.root.glob("db/fixes/*.rb").map { |path| File.basename(path, ".rb") }.grep(/\A\d/).sort_by { |name| sort_key(name) }
+    end
+
+    def applied
+      ActiveRecord::Base.connection.select_rows('SELECT id, "index" FROM fixes').to_set
+    end
+
+    def applied?(name)
+      id, index = key_for(name)
+      conn = ActiveRecord::Base.connection
+      index_clause = index.nil? ? '"index" IS NULL' : %("index" = #{index})
+      conn.select_value("SELECT 1 FROM fixes WHERE id = #{id} AND #{index_clause}").present?
+    end
+
+    def pending
+      applied_keys = applied
+      all_fixes.reject { |name| applied_keys.include?(key_for(name)) }
+    end
+
+    def record!(name)
+      id, index = key_for(name)
+      conn = ActiveRecord::Base.connection
+      conn.execute(<<~SQL.squish)
+        INSERT INTO fixes (id, "index") VALUES (#{id}, #{index || 'NULL'})
+        ON CONFLICT (id, "index") DO NOTHING
+      SQL
+    end
+
+    def run!(path)
+      name = File.basename(path, ".rb")
+      load(File.expand_path(path))
+      record!(name)
+      name
+    end
+
+    # Mirrors how ActiveRecord appends `INSERT INTO "schema_migrations"` to structure.sql after
+    # a schema dump (see Connection#dump_schema_versions) - appends the currently-applied fixes
+    # the same way, so loading structure.sql into a fresh database marks them applied too instead
+    # of leaving `fixes:migrate` to re-run every historical fix. Hooked into `db:schema:dump` in
+    # lib/tasks/fixes.rake, so it runs on every schema dump, not just `fixes:migrate`.
+    def dump_structure_sql!
+      db_config = ActiveRecord::Base.connection_db_config
+      return unless db_config.schema_format == :sql
+
+      filename = ActiveRecord::Tasks::DatabaseTasks.schema_dump_path(db_config)
+      return unless filename && File.exist?(filename)
+
+      conn = ActiveRecord::Base.connection
+      return unless conn.table_exists?(:fixes)
+
+      rows = conn.select_rows('SELECT id, "index" FROM fixes ORDER BY id DESC, "index" DESC NULLS LAST')
+      return if rows.empty?
+
+      values = rows.map { |id, index| "(#{id}, #{index || 'NULL'})" }.join(",\n")
+      File.open(filename, "a") do |f|
+        f.puts(<<~TEXT)
+          INSERT INTO "fixes" (id, "index") VALUES
+          #{values};
+        TEXT
+      end
+    end
+  end
+end

data/lib/yiffspace/fixer_template.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module YiffSpace
+  # Base class for a `bin/rails generate yiffspace:fixer` template, auto-discovered from *.rb
+  # files in YiffSpace.config.fixer_templates_path (default db/fixer_templates) - no explicit
+  # registration needed, just define a subclass:
+  #
+  #   class ElasticsearchTemplate < YiffSpace::FixerTemplate
+  #     short("e")
+  #
+  #     step { "..." }
+  #     step { "..." }
+  #   end
+  #
+  # The template's name comes from the class name with a trailing "Template" dropped and
+  # kebab-cased (ElasticsearchTemplate -> "elasticsearch", OpenSearchTemplate -> "open-search"),
+  # reachable as `--template <name>` (see Yiffspace::FixerGenerator). Its step count is the
+  # number of `step` blocks - each one's return value becomes that step's fix file content,
+  # instead of the generic fixer.rb template a plain `--steps N` copies for every step.
+  class FixerTemplate
+    class << self
+      # Optional - a template is always reachable via `--template <name>`, a registered
+      # shortname flag (e.g. `-e`) is just a convenient alias for it.
+      def short(value = nil)
+        @short = value.to_s.delete_prefix("-") unless value.nil?
+        @short
+      end
+
+      def step(&block)
+        raise(ArgumentError, "#{name}.step requires a block") unless block
+
+        steps << block
+      end
+
+      def steps
+        @steps ||= []
+      end
+
+      def template_name
+        name.demodulize.delete_suffix("Template").underscore.dasherize
+      end
+    end
+  end
+end

data/lib/yiffspace/fixers/engine.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require("rails")
+
+module YiffSpace
+  module Fixers
+    # No app/ of its own - this exists so Rails::Engine's default rake_tasks block picks up
+    # lib/tasks/fixes.rake (config.root anchors where it looks for lib/tasks/**/*.rake).
+    class Engine < ::Rails::Engine
+      config.root = File.expand_path("../../..", __dir__)
+
+      initializer("yiffspace.fixers.requires_fix") do
+        ActiveRecord::Migration.include(YiffSpace::Fixers::RequiresFix)
+      end
+    end
+  end
+end

data/lib/yiffspace/fixers/requires_fix.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module YiffSpace
+  module Fixers
+    # Adds `requires_fix` to ActiveRecord::Migration - the migration-side mirror of
+    # YiffSpace::FixTracker.requires_migration! - so a migration can declare that one or more
+    # db/fixes/*.rb scripts must already be applied before it runs, e.g.:
+    #
+    #   class BackfillWidgetType < ActiveRecord::Migration[8.1]
+    #     requires_fix(3)
+    #
+    #     def change
+    #       ...
+    #     end
+    #   end
+    #
+    # Checked whenever the migration actually runs (so plain `db:migrate` still refuses to run it
+    # out of order), and read back ahead of time by YiffSpace::MigrationSync to order
+    # `fixes:migrate_all` correctly. Included into ActiveRecord::Migration by
+    # YiffSpace::Fixers::Engine.
+    module RequiresFix
+      # Raised when a migration runs before one of its required fixes has been applied.
+      class FixRequired < StandardError; end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.prepend(InstanceMethods)
+      end
+
+      module ClassMethods
+        # id_or_name: a fix's leading id (e.g. 3, covers every step sharing that id) or its full
+        # file name (e.g. "2_1_first_step") for one specific step - see YiffSpace::FixTracker#resolve.
+        def requires_fix(id_or_name)
+          required_fixes << id_or_name
+        end
+
+        def required_fixes
+          @required_fixes ||= []
+        end
+      end
+
+      module InstanceMethods
+        def migrate(direction)
+          check_required_fixes! if direction == :up
+
+          super
+        end
+
+        private
+
+        def check_required_fixes!
+          self.class.required_fixes.each do |id_or_name|
+            names = YiffSpace::FixTracker.resolve(id_or_name)
+            raise(FixRequired, "#{self.class.name} requires fix #{id_or_name.inspect}, which does not exist") if names.empty?
+
+            missing = names.reject { |name| YiffSpace::FixTracker.applied?(name) }
+            raise(FixRequired, "#{self.class.name} requires #{missing.join(', ')} to be applied first") if missing.any?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yiffspace/fixers/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module YiffSpace
+  module Fixers
+    VERSION = "0.0.1"
+  end
+end

data/lib/yiffspace/fixers.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require("yiffspace/core")
+require("zeitwerk")
+
+loader = Zeitwerk::Loader.for_gem_extension(YiffSpace)
+loader.ignore("#{__dir__}/fixers/engine.rb")
+loader.setup
+
+# Require the engine eagerly so it registers with Rails before the host app's
+# active_support.initialize_per_engine_zeitwerk_loaders initializer runs - same reasoning as
+# yiffspace's own engine.rb/yiffspace-auth's auth/engine.rb.
+require_relative("fixers/engine") if defined?(Rails)
+
+module YiffSpace
+  class Configuration
+    # Named `--steps` presets for `bin/rails generate yiffspace:fixer`. See
+    # YiffSpace::Configuration::FixerTemplates.
+    def fixer_templates
+      @fixer_templates ||= FixerTemplates.new
+    end
+
+    # Directory scanned for YiffSpace::FixerTemplate subclasses (see FixerTemplate) - defaults to
+    # db/fixer_templates in the host app.
+    attr_writer(:fixer_templates_path)
+
+    def fixer_templates_path
+      @fixer_templates_path ||= Rails.root.join("db/fixer_templates")
+    end
+  end
+end

data/lib/yiffspace/migration_sync.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module YiffSpace
+  # Computes and applies pending db/migrate/*.rb migrations and db/fixes/*.rb fixes together, in
+  # whichever order their cross requirements demand - a fix can require a migration
+  # (YiffSpace::FixTracker.requires_migration!) and a migration can require a fix
+  # (YiffSpace::Fixers::RequiresFix#requires_fix). Migrations stay ordered among themselves by
+  # version, fixes among themselves by YiffSpace::FixTracker.sort_key, and those cross
+  # requirements are woven in via a topological sort. #plan/#apply are used by `rake
+  # fixes:migrate_all` (see lib/tasks/fixes.rake).
+  module MigrationSync
+    # A single item in the computed #plan - kind is :migration (ref a MigrationProxy) or :fix
+    # (ref a fix name).
+    Step = Struct.new(:kind, :ref, :key)
+
+    # Raised when a fix/migration requires something that isn't findable, or requirements form a
+    # cycle (e.g. a fix requires a migration that itself requires that same fix).
+    class UnresolvableOrder < StandardError; end
+
+    module_function
+
+    # The ordered list of pending Steps - migrations and fixes interleaved wherever a
+    # requires_fix/requires_migration! forces it, otherwise each kept in its own natural order.
+    def plan
+      migrations = pending_migrations
+      fixes = FixTracker.pending
+
+      steps = {}
+      migrations.each { |m| steps[[:migration, m.version]] = Step.new(:migration, m, [:migration, m.version]) }
+      fixes.each { |f| steps[[:fix, f]] = Step.new(:fix, f, [:fix, f]) }
+
+      edges = Hash.new { |h, k| h[k] = [] }
+      indegree = steps.each_key.index_with(0)
+
+      link = lambda do |before, after|
+        next unless steps.key?(before) && steps.key?(after)
+
+        edges[before] << after
+        indegree[after] += 1
+      end
+
+      # Preserve each kind's own natural order as implicit dependencies.
+      migrations.each_cons(2) { |a, b| link.call([:migration, a.version], [:migration, b.version]) }
+      fixes.each_cons(2) { |a, b| link.call([:fix, a], [:fix, b]) }
+
+      link_fix_requirements(fixes, link)
+      link_migration_requirements(migrations, link)
+
+      topological_sort(steps, edges, indegree)
+    end
+
+    def link_fix_requirements(fixes, link)
+      fixes.each do |name|
+        version = FixTracker.required_migration_for(name)
+        next unless version
+        raise(UnresolvableOrder, "#{name} requires migration #{version}, which does not exist") unless migration_exists?(version)
+
+        link.call([:migration, version.to_i], [:fix, name])
+      end
+    end
+
+    def link_migration_requirements(migrations, link)
+      migrations.each do |m|
+        migration_class_for(m).required_fixes.each do |id_or_name|
+          names = FixTracker.resolve(id_or_name)
+          raise(UnresolvableOrder, "#{m.name} requires fix #{id_or_name.inspect}, which does not exist") if names.empty?
+
+          names.each { |name| link.call([:fix, name], [:migration, m.version]) }
+        end
+      end
+    end
+
+    # Kahn's algorithm - ready nodes are processed FIFO in `steps`' insertion order (migrations
+    # before fixes when both are ready at once), so requirements only ever reorder things when
+    # they actually have to.
+    def topological_sort(steps, edges, indegree)
+      ready = indegree.select { |_, count| count.zero? }.keys
+      ordered = []
+
+      until ready.empty?
+        key = ready.shift
+        ordered << steps.fetch(key)
+
+        edges[key].each do |dependent|
+          indegree[dependent] -= 1
+          ready << dependent if indegree[dependent].zero?
+        end
+      end
+
+      return ordered if ordered.size == steps.size
+
+      stuck = (steps.keys - ordered.map(&:key)).map { |kind, ref| "#{kind}:#{ref}" }
+      raise(UnresolvableOrder, "circular requirement between #{stuck.join(', ')}")
+    end
+
+    def describe(step)
+      case step.kind
+      when :migration then "Migrating #{step.ref.name} (#{step.ref.version})..."
+      when :fix then "Running #{step.ref}..."
+      end
+    end
+
+    # Applies a single Step from #plan - a migration is brought up to (and including) its own
+    # version, a fix is run and recorded, same as FixTracker.run!.
+    def apply(step)
+      case step.kind
+      when :migration
+        migration_context.up(step.ref.version) { |candidate| candidate.version == step.ref.version }
+      when :fix
+        FixTracker.run!(FixTracker.fix_path(step.ref))
+      end
+    end
+
+    def pending_migrations
+      applied = migration_context.get_all_versions
+      migration_context.migrations.reject { |m| applied.include?(m.version) }
+    end
+
+    def migration_exists?(version)
+      migration_context.migrations.any? { |m| m.version == version.to_i }
+    end
+
+    # MigrationProxy defers loading the migration class until needed, via a private #migration
+    # accessor - reading `required_fixes` off it needs that class loaded early too, so reach past
+    # that privacy rather than reimplementing Rails' own file-loading/constantizing.
+    def migration_class_for(proxy)
+      proxy.send(:migration).class
+    end
+
+    def migration_context
+      FixTracker.migration_context
+    end
+  end
+end

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: yiffspace-fixers
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Donovan_DMC
+bindir: bin
+cert_chain: []
+date: 2026-09-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: yiffspace-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: One-time db/fixes scripts and their generators, for https://yiff.space
+  and related projects
+email:
+- hewwo@yiff.rocks
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- lib/generators/yiffspace/fixer/USAGE
+- lib/generators/yiffspace/fixer/fixer_generator.rb
+- lib/generators/yiffspace/fixer/templates/fixer.rb
+- lib/generators/yiffspace/install/fixes_generator.rb
+- lib/generators/yiffspace/install/templates/create_fixes.rb.erb
+- lib/tasks/fixes.rake
+- lib/yiffspace/configuration/fixer_templates.rb
+- lib/yiffspace/fix_tracker.rb
+- lib/yiffspace/fixer_template.rb
+- lib/yiffspace/fixers.rb
+- lib/yiffspace/fixers/engine.rb
+- lib/yiffspace/fixers/requires_fix.rb
+- lib/yiffspace/fixers/version.rb
+- lib/yiffspace/migration_sync.rb
+homepage: https://yiff.space
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://yiff.space
+  source_code_uri: https://github.com/YiffSpace/Gem/tree/master/yiffspace-fixers
+  changelog_uri: https://github.com/YiffSpace/Gem/blob/master/yiffspace-fixers/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.1
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: One-time db/fixes scripts and their generators, for https://yiff.space and
+  related projects
+test_files: []