handcuffs 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd48a0c4c4c2948afced7735d5f699648c000e5bbbcc3e4e795dff0f44f15c04
-  data.tar.gz: a6471b2358a4f1dae25251de3ae20665878e816e31a4f49687a6603673f69d82
+  metadata.gz: a6151bce2a0641c7d959760ed968af5ca1a6dde4961a3ac7d68182e57239ec86
+  data.tar.gz: ab80386265b6c8081bb00d1c7840860463098c0651d9022b6d129e175b489c28
 SHA512:
-  metadata.gz: 873b8306a43cc09b1c524f1b4debdf4fd96bb47ab0ac8fd80a2b14287610b15ef596c13bc4ad65741507ec4a6be686f54763de0da84eefe7b28bcc14741a0be5
-  data.tar.gz: d1395678197fd1f74847970e3145002f67c535ac6beb8912b7c7a7990da80cebfee67bf29992f48f0383b834d2d991a5a7726e9c513280ffd81a5fc31a9a157f
+  metadata.gz: 77c5b7f5cfcb95ca3136bccd62606beb0f215046900c0d1bc70568186c693eed2d7133d622d89b73bc7e8c3ba1ac417fd18e107bb263127d02891f9483cf9c2c
+  data.tar.gz: 04567d40823a197a7cc428d0146903e1254fd7c408b20a155e8c8243efa82e698cc61f9fd802a53027315c78d916636527d1a8ba14d8a776120d0aee4f3869d7

data/.github/dependabot.yaml

@@ -9,6 +9,14 @@ updates:
       - "dependabot"
       - "dependencies"
       - "github-actions"
+    commit-message:
+      prefix: "chore(deps)"
+    groups:
+      dependencies:
+        applies-to: version-updates
+        update-types:
+          - "minor"
+          - "patch"
   - package-ecosystem: "bundler"
     directory: /
     schedule:
@@ -18,3 +26,11 @@ updates:
       - "dependabot"
       - "dependencies"
       - "bundler"
+    commit-message:
+      prefix: "chore(deps)"
+    groups:
+      dependencies:
+        applies-to: version-updates
+        update-types:
+          - "minor"
+          - "patch"

data/.github/workflows/auto-assign-author.yaml

@@ -1,13 +1,15 @@
 name: 'Auto Author Assign'
-
 on:
   pull_request_target:
     types: [opened, reopened]
-
+permissions:
+  contents: read
 jobs:
   assign-author:
+    permissions:
+      pull-requests: write
     runs-on: ubuntu-latest
     steps:
-      - uses: toshimaru/auto-author-assign@v2.1.0
+      - uses: toshimaru/auto-author-assign@ebd30f10fb56e46eb0759a14951f36991426fed0 # v2.1.0
         with:
           repo-token: "${{ secrets.GITHUB_TOKEN }}"

data/.github/workflows/codeql.yaml

@@ -1,15 +1,12 @@
 name: "Custom CodeQL"
-
 on:
   workflow_dispatch:
   push:
-    branches: [ "main" ]
+    branches: ["main"]
   pull_request:
-    branches: [ "main" ]
-
+    branches: ["main"]
 permissions:
   contents: read
-
 jobs:
   analyze:
     name: Analyze
@@ -19,25 +16,20 @@ jobs:
       actions: read
       contents: read
       security-events: write
-
     strategy:
       fail-fast: false
       matrix:
-        language: [ 'ruby' ]
-
+        language: ['ruby']
     steps:
-    - name: Checkout repository
-      uses: actions/checkout@v4
-
-    - name: Initialize CodeQL
-      uses: github/codeql-action/init@v3
-      with:
-        languages: ${{ matrix.language }}
-
-    - name: Autobuild
-      uses: github/codeql-action/autobuild@v3
-
-    - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v3
-      with:
-        category: "/language:${{matrix.language}}"
+      - name: Checkout repository
+        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@23acc5c183826b7a8a97bce3cecc52db901f8251 # v3
+        with:
+          languages: ${{ matrix.language }}
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@23acc5c183826b7a8a97bce3cecc52db901f8251 # v3
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@23acc5c183826b7a8a97bce3cecc52db901f8251 # v3
+        with:
+          category: "/language:${{matrix.language}}"

data/.github/workflows/release.yaml

@@ -6,35 +6,38 @@ on:
     branches: [main]
   workflow_dispatch: # allow manual deployment through GitHub Action UI
 jobs:
-  release:
+  version-check:
     runs-on: ubuntu-latest
     if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
+    outputs:
+      changed: ${{ steps.check.outputs.any_changed }}
     steps:
-      - uses: actions/checkout@v4
-      - name: Version file changed
-        id: version-file-changed
-        uses: tj-actions/changed-files@v42
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4
+      - name: Check if version has been updated
+        id: check
+        uses: tj-actions/changed-files@d6babd6899969df1a11d14c368283ea4436bca78 # v44
         with:
           files: lib/handcuffs/version.rb
+  release:
+    runs-on: ubuntu-latest
+    needs: version-check
+    if: ${{ github.event_name == 'workflow_dispatch' || needs.version-check.outputs.changed == 'true' }}
+    steps:
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4
       - name: Set up Ruby
-        if: ${{ github.event_name == 'workflow_dispatch' || steps.version-file-changed.outputs.any_changed == 'true' }}
-        uses: ruby/setup-ruby@v1
+        uses: ruby/setup-ruby@3783f195e29b74ae398d7caca108814bbafde90e # v1
         with:
           ruby-version: 3.2
           bundler-cache: true
       - name: Installing dependencies
-        if: ${{ github.event_name == 'workflow_dispatch' || steps.version-file-changed.outputs.any_changed == 'true' }}
         run: bundle check --path=vendor/bundle || bundle install --path=vendor/bundle
       - name: Build gem file
-        if: ${{ github.event_name == 'workflow_dispatch' || steps.version-file-changed.outputs.any_changed == 'true' }}
         run: bundle exec rake build
-      - uses: fac/ruby-gem-setup-credentials-action@v2
-        if: ${{ github.event_name == 'workflow_dispatch' || steps.version-file-changed.outputs.any_changed == 'true' }}
+      - uses: fac/ruby-gem-setup-credentials-action@5f62d5f2f56a11c7422a92f81fbb29af01e1c00f # v2
         with:
           user: ""
           key: rubygems
           token: ${{secrets.RUBY_GEMS_API_KEY}}
-      - uses: fac/ruby-gem-push-action@v2
-        if: ${{ github.event_name == 'workflow_dispatch' || steps.version-file-changed.outputs.any_changed == 'true' }}
+      - uses: fac/ruby-gem-push-action@81d77bf568ff6659d7fae0f0c5a036bb0aeacb1a # v2
         with:
           key: rubygems

data/.github/workflows/stale.yaml

@@ -2,37 +2,33 @@
 name: Mark stale issues and pull requests
 on:
   schedule:
-  - cron: "30 1 * * *"
-
+    - cron: "30 1 * * *"
 permissions:
   contents: read
-
 jobs:
   stale:
     permissions:
-      issues: write  # for actions/stale to close stale issues
-      pull-requests: write  # for actions/stale to close stale PRs
+      issues: write # for actions/stale to close stale issues
+      pull-requests: write # for actions/stale to close stale PRs
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/stale@v9
-      with:
-        repo-token: ${{ secrets.GITHUB_TOKEN }}
-        # Number of days of inactivity before an issue becomes stale
-        days-before-stale: 60
-        # Number of days of inactivity before a stale issue is closed
-        days-before-close: 7
-        # Issues with these labels will never be considered stale
-        exempt-issue-labels: "on-hold,pinned,security"
-        exempt-pr-labels: "on-hold,pinned,security"
-        # Comment to post when marking an issue as stale.
-        stale-issue-message: >
-          This issue has been automatically marked as stale because it has not had
-          recent activity. It will be closed if no further activity occurs. Thank you
-          for your contributions.
-        stale-pr-message: >
-          This pull request has been automatically marked as stale because it has not had
-          recent activity. It will be closed if no further activity occurs. Thank you
-          for your contributions.
-        # Label to use when marking an issue as stale
-        stale-issue-label: 'no-issue-activity'
-        stale-pr-label: 'no-pr-activity'
+      - uses: actions/stale@28ca1036281a5e5922ead5184a1bbf96e5fc984e # v9
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          # Number of days of inactivity before an issue becomes stale
+          days-before-stale: 60
+          # Number of days of inactivity before a stale issue is closed
+          days-before-close: 7
+          # Issues with these labels will never be considered stale
+          exempt-issue-labels: "on-hold,pinned,security"
+          exempt-pr-labels: "on-hold,pinned,security"
+          # Comment to post when marking an issue as stale.
+          stale-issue-message: >
+            This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.
+
+          stale-pr-message: >
+            This pull request has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.
+
+          # Label to use when marking an issue as stale
+          stale-issue-label: 'no-issue-activity'
+          stale-pr-label: 'no-pr-activity'

data/.github/workflows/test.yaml

@@ -10,11 +10,12 @@ jobs:
   test:
     strategy:
       matrix:
-        ruby: ['2.7', '3.0', '3.1', '3.2', '3.3']
+        os: ['ubuntu-latest']
+        ruby: ['3.0', '3.1', '3.2', '3.3']
         postgres: ['16-bullseye', '15-bullseye', '14-bullseye', '13-bullseye', '12-bullseye']
     name: Ruby ${{ matrix.ruby }} - PostgreSQL ${{ matrix.postgres }}
     # https://docs.github.com/en/actions/learn-github-actions/expressions#example
-    runs-on: ${{ matrix.ruby == '2.7' && 'ubuntu-20.04' || 'ubuntu-latest' }}
+    runs-on: ${{ matrix.os }}
     services:
       postgres:
         image: postgres:${{ matrix.postgres }}
@@ -23,10 +24,7 @@ jobs:
           POSTGRES_DB: handcuffs_test
           POSTGRES_HOST_AUTH_METHOD: trust
         options: >-
-          --health-cmd pg_isready
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
+          --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5
         ports:
           - 5432:5432
     env:
@@ -35,9 +33,9 @@ jobs:
       RAILS_ENV: test
       BUNDLER_VERSION: 2.4.22
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4
       - name: Set up Ruby ${{ matrix.ruby }}
-        uses: ruby/setup-ruby@v1
+        uses: ruby/setup-ruby@3783f195e29b74ae398d7caca108814bbafde90e # v1
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler: ${{ env.BUNDLER_VERSION }}

data/CHANGELOG.md

@@ -5,9 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [Unreleased] [diff](https://github.com/procore-oss/handcuffs/compare/v2.1.0..main)
 
-## 2.0.0
+## 2.1.0 : 2025-01-24 [diff](https://github.com/procore-oss/handcuffs/compare/v2.0.0..v2.1.0)
+
+### Added
+
+- Ability to specify prerequisite phases in a non-linear order
+
+### Changed
+
+- (internal) bumped rspec-rails gem version in development dependencies
+- (internal) bumped minimum gem versions in test Rails app
+- (internal) update github workflow
+
+
+## 2.0.0 : 2024-02-20 [diff](https://github.com/procore-oss/handcuffs/compare/v1.4.1..v2.0.0)
+
+### Removed
+
+- **BREAKING CHANGE**: Removed support for Ruby < 2.7, Rails < 6.1, PostgreSQL < 12.
 
 ### Added
 
@@ -24,7 +41,3 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Updated Bundler to 2.4.22.
 - Added Appraisal for dummy app testing.
 - Moved repo to procore-oss
-
-### Removed
-
-- BREAKING CHANGE: Removed support for Ruby < 2.7, Rails < 6.1, PostgreSQL < 12.

data/README.md

@@ -2,59 +2,110 @@
 
 [![Test](https://github.com/procore-oss/handcuffs/actions/workflows/test.yaml/badge.svg?branch=main)](https://github.com/procore-oss/handcuffs/actions/workflows/test.yaml)
 [![Gem Version](https://badge.fury.io/rb/handcuffs.svg)](https://badge.fury.io/rb/handcuffs)
-[![Discord](https://img.shields.io/badge/Chat-EDEDED?logo=discord)](https://discord.gg/PbntEMmWws) 
+[![Discord](https://img.shields.io/badge/Chat-EDEDED?logo=discord)](https://discord.gg/PbntEMmWws)
 
-Handcuffs provides an easy way to run migrations in phases in your [Ruby on Rails](https://rubyonrails.org/) application.
+Handcuffs provides an easy way to run [Ruby on Rails](https://rubyonrails.org/) migrations in phases using a simple process:
 
-To configure, first create a handcuff initializer and define a configuration
+1. Define a set of named phases in the order in which they should be run
+2. Tag migrations with one of the defined phase names
+3. Run migrations by phase at start, end or outside of application deployment
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'handcuffs'
+```
+
+And then execute:
+
+```bash
+bundle
+```
+
+Or install it directly on the current system using:
+
+```bash
+gem install handcuffs
+```
+
+## Usage
+
+### Configuration
+
+Create a handcuffs initializer and define the migration phases in the order in which they should be run. You should also define a default phase for pre-existing "untagged" migrations, or if you want the option to tag only custom phases.
+
+The most basic configuration is an array of phase names, and using the first one as the default:
 
 ```ruby
 # config/initializers/handcuffs.rb
 
 Handcuffs.configure do |config|
+  # pre_restart migrations will/must run before post_restart migrations
   config.phases = [:pre_restart, :post_restart]
+  config.default_phase = :pre_restart
 end
 ```
 
-Then call `phase` from inside your migrations
+If you have more complex or asynchrous workflows, you can use an alternate hash notation that allows prerequisite stages to be specified explicitly:
 
 ```ruby
-# db/migrate/20160318230933_add_on_sale_column.rb
+# config/initializers/handcuffs.rb
 
-class AddOnSaleColumn < ActiveRecord::Migration
+Handcuffs.configure do |config|
+  config.phases = {
+    # Prevent running post_restart migrations if there are outstanding
+    # pre_restart migrations
+    post_restart: [:pre_restart],
+    # Require pre_restarts before data_migrations, but do not enforce ordering
+    # between data_migrations and post_restarts
+    data_migrations: [:pre_restart],
+    # pre_restarts have no prerequisite phases
+    pre_restart: []
+  }
+end
+```
+The default phase order in this case is determined by [Tsort](https://github.com/ruby/tsort) (topological sort). In order to validate the configuration and expected phase order it is recommended that you check the phase configuration after any changes using the rake task:
+
+```ruby
+rake handcuffs:phase_order
+```
+
+This will display the default order in which phases will be run and list the prerequisites of each phase. It will raise an error if there are any circular dependencies or if any prerequisite is not a valid phase name.
+
+### Tagging Migrations
+
+Once configured, you can assign each migration to one of the defined phases using the `phase` setter method:
+
+```ruby
+# db/migrate/20240318230933_add_on_sale_column.rb
+
+class AddOnSaleColumn < ActiveRecord::Migration[7.0]
 
   phase :pre_restart
 
-  def up
+  def change
     add_column :products, :on_sale, :boolean
   end
-
-  def down
-    remove_column :products, :on_sale
-  end
-
 end
 ```
 
 ```ruby
-# db/migrate/20160318230988_add_on_sale_index
+# db/migrate/20240318230988_add_on_sale_index
 
-class AddOnSaleIndex < ActiveRecord::Migration
+class AddOnSaleIndex < ActiveRecord::Migration[7.0]
 
   phase :post_restart
 
-  def up
+  def change
     add_index :products, :on_sale, algorithm: :concurrently
   end
-
-  def down
-    remove_index :products, :on_sale
-  end
-
 end
 ```
+### Running Migrations In Phases
 
-You can then run your migrations in phases using
+After Handcuffs is configured and migrations are properly tagged, you can then run migrations in phases using the `handcuffs:migrate` rake task with the specific phase to be run:
 
 ```bash
 rake 'handcuffs:migrate[pre_restart]'
@@ -66,53 +117,32 @@ or
 rake 'handcuffs:migrate[post_restart]'
 ```
 
-You can run all migrations using
+*Note:* If you run phases out of order, or attempt to run a phase before outstanding migrations with a prerequisite phase have been run, a `HandcuffsPhaseOutOfOrderError` will be raised.
 
-```bash
-rake 'handcuffs:migrate[all]'
-```
+### Running All Migrations
 
-This differs from running `rake db:migrate` in that migrations will be run in the _order that the phases are defined in the handcuffs config_.
+In CI and local developement you may want to run all phases at one time.
 
-If you run a handcuffs rake task and any migration does not have a phase defined, an error will be raised before any migrations are run. To prevent this error, you can define a default phase for migrations that don't define one.
-
-```ruby
-# config/initializers/handcuffs.rb
-
-Handcuffs.configure do |config|
-  config.phases = [:pre_restart, :post_restart]
-  config.default_phase = :pre_restart
-end
-```
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'handcuffs'
-```
-
-And then execute:
-
-```bash
-bundle
-```
-
-Or install it yourself as:
+Handcuffs offers a single command that will run all migrations in phases and in the configured order:
 
 ```bash
-gem install handcuffs
+rake 'handcuffs:migrate[all]'
 ```
 
-## Running specs
+This differs from running `rake db:migrate` in that migrations will be run in batches corresponding to the _order that the phases are defined in the handcuffs config_. Again, you can use `rake handcuffs:phase_order` to preview the order ahead of time.
 
-The specs for handcuffs are in the dummy application at `/spec/dummy/spec`. The spec suite requires PostgreSQL. To run it you will have to set the environment variables `POSTGRES_DB_USERNAME` and `POSTGRES_DB_PASSWORD`. You can then run the suite using `rake spec`
+Of course, you can always run `rake db:migrate` at any time to run all migrations using the Rails default ordering and without regard to Handcuffs phase if you wish.
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at <https://github.com/procore-oss/handcuffs>. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
+## Running Tests Locally
+
+The specs for handcuffs are in the dummy application at `/spec/dummy/spec`. The spec suite requires PostgreSQL. To run it you will have to set the environment variables `POSTGRES_DB_USERNAME` and `POSTGRES_DB_PASSWORD`.
+
+We use [appraisal](https://github.com/thoughtbot/appraisal) to run our test suite against all Rails versions that we support, as a means of quickly identifying potential regressions. To do this locally, first run `bundle exec appraisal install` to ensure all required dependencies are setup, and then run `bundle exec appraisal rspec`.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
@@ -120,8 +150,8 @@ The gem is available as open source under the terms of the [MIT License](http://
 ## About Procore
 
 <img
-  src="https://www.procore.com/images/procore_logo.png"
-  alt="Procore Logo"
+  src="https://raw.githubusercontent.com/procore-oss/.github/main/procorelightlogo.png"
+  alt="Procore Open Source"
   width="250px"
 />
 

data/SECURITY.md

@@ -6,11 +6,11 @@ Ruby versions that are currently being supported with security updates.
 
 | Version | Supported          |
 | ------- | ------------------ |
-| <=2.6   | :x:                |
-| 2.7     | :white_check_mark: |
+| <=2.7   | :x:                |
 | 3.0     | :white_check_mark: |
 | 3.1     | :white_check_mark: |
 | 3.2     | :white_check_mark: |
+| 3.3     | :white_check_mark: |
 
 ## Reporting a Vulnerability
 

data/handcuffs.gemspec

@@ -13,6 +13,7 @@ Gem::Specification.new do |spec|
   spec.description   = %q{Allows you to define a phase on Active Record migrations and provides rake tasks for running only migrations tagged with a certain phase}
   spec.homepage      = "https://github.com/procore-oss/handcuffs/"
   spec.license       = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new('>= 3.0')
 
   # Prevent pushing this gem to RubyGems.org by setting 'allowed_push_host', or
   # delete this section to allow pushing this gem to any host.
@@ -33,7 +34,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "pg"
   spec.add_development_dependency "pry"
   spec.add_development_dependency "pry-byebug"
-  spec.add_development_dependency "rspec-rails", "~> 3.0"
+  spec.add_development_dependency "rspec-rails", "~> 6.1"
   spec.add_development_dependency "simplecov"
 
   spec.add_runtime_dependency "rails", ">= 6.1"

data/lib/handcuffs/configuration.rb

@@ -10,7 +10,7 @@ module Handcuffs
   end
 
   class Configurator
-    attr_accessor :phases
+    attr_reader :phases
     attr_accessor :default_phase
 
     def initialize
@@ -18,7 +18,9 @@ module Handcuffs
       @default_phase = nil
     end
 
+    def phases=(phases)
+      @phases = Phases.new(phases)
+    end
   end
-
 end
 

data/lib/handcuffs/extensions.rb

@@ -1,12 +1,12 @@
+# frozen_string_literal: true
+
 module Handcuffs
+  # Extended by ActiveRecord::Migrator in order to track the current phase
   module Extensions
-
-    attr_reader :handcuffs_phase
+    attr_accessor :handcuffs_phase
 
     def phase(phase)
       @handcuffs_phase = phase
     end
-
   end
 end
-

data/lib/handcuffs/pending_filter_ext.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Handcuffs
+  # PendingFilter is prepended to ActiveRecord::Migrator in the rake tasks
+  # in order to check the current phase before it is run
+  module PendingFilterExt
+    def runnable
+      attempted_phase = self.class.handcuffs_phase
+      if @direction == :up
+        Handcuffs::PhaseFilter.new(attempted_phase, @direction).filter(super)
+      else
+        phase_migrations = Handcuffs::PhaseFilter.new(attempted_phase, @direction).filter(migrations)
+        runnable = phase_migrations[start..finish]
+        runnable.pop if target
+        runnable.find_all { |m| ran?(m) }
+      end
+    end
+  end
+end

data/lib/handcuffs/phase_filter.rb

@@ -41,7 +41,7 @@ class Handcuffs::PhaseFilter
   end
 
   def check_order_up!(by_phase, defined_phases)
-    defined_phases.take_while { |defined_phase| defined_phase != attempted_phase }
+    defined_phases.prereqs(attempted_phase)
       .detect { |defined_phase| by_phase.key?(defined_phase) }
       .tap do |defined_phase|
         raise HandcuffsPhaseOutOfOrderError.new(defined_phase, attempted_phase) if defined_phase
@@ -58,7 +58,7 @@ class Handcuffs::PhaseFilter
   end
 
   def all_phases_by_configuration_order(by_phase, defined_phases)
-    defined_phases.reduce([]) do |acc, phase|
+    defined_phases.in_order.reduce([]) do |acc, phase|
       acc | Array(by_phase[phase])
     end.map { |mh| mh[:proxy] }
   end

data/lib/handcuffs/phases.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'tsort'
+
+module Handcuffs
+  # Phases encapsulates the list of phases and any interdependencies
+  class Phases
+    def initialize(phases)
+      @phases = case phases
+                when Hash
+                  phases.each_with_object({}) do |phase, acc|
+                    acc[phase[0].to_sym] = Array(phase[1]).map(&:to_sym)
+                  end
+                else
+                  # Assume each entry depends on all entries before it
+                  phases.map(&:to_sym).each_with_object({}) do |phase, acc|
+                    acc[phase] = phases.take_while { |defined_phase| defined_phase != phase }
+                  end
+                end
+    end
+
+    def to_sentence
+      @phases.keys.to_sentence
+    end
+
+    def include?(phase)
+      @phases.include?(phase)
+    end
+
+    def in_order
+      TSort.tsort(
+        @phases.method(:each_key),
+        ->(phase, &block) { @phases.fetch(phase).each(&block) }
+      )
+    end
+
+    def prereqs(attempted_phase)
+      @phases.fetch(attempted_phase, [])
+    end
+  end
+end

data/lib/handcuffs/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Handcuffs
-  VERSION = "2.0.0"
+  VERSION = '2.1.0'
 end

data/lib/tasks/handcuffs.rake

@@ -1,56 +1,51 @@
+# frozen_string_literal: true
+
 namespace :handcuffs do
-  task :migrate, [:phase] => :environment do |t,args|
+  task :migrate, [:phase] => :environment do |_t, args|
     phase = setup(args, 'handcuffs:migrate')
     patch_migrator!(phase)
     run_task('db:migrate')
   end
 
-  task :rollback, [:phase] => :environment do |t,args|
+  task :rollback, [:phase] => :environment do |_t, args|
     phase = setup(args, 'handcuffs:rollback')
     patch_migrator!(phase)
     run_task('db:rollback')
   end
 
+  task phase_order: :environment do
+    raise HandcuffsNotConfiguredError unless Handcuffs.config
+
+    puts 'Configured Handcuffs phases, in order, are:'
+    phases = Handcuffs.config.phases || return
+
+    phases.in_order.each_with_index do |phase, idx|
+      puts (idx + 1).to_s.rjust(3) + ". #{phase}, requires: #{phases.prereqs(phase).join(', ').presence || '(nothing)'}"
+    end
+  end
+
   def setup(args, task)
-    phase = args.phase
+    phase = args.phase.presence&.to_sym
+
     raise RequiresPhaseArgumentError.new(task) unless phase.present?
-    raise HandcuffsNotConfiguredError.new unless Handcuffs.config
-    phase = phase.to_sym
-    unless Handcuffs.config.phases.include?(phase) || phase == :all
-      raise HandcuffsUnknownPhaseError.new(phase, Handcuffs.config.phases)
-    end
-    phase
+
+    raise HandcuffsNotConfiguredError unless Handcuffs.config
+
+    return phase if Handcuffs.config.phases.include?(phase) || phase == :all
+
+    raise HandcuffsUnknownPhaseError.new(phase, Handcuffs.config.phases)
   end
 
   def patch_migrator!(phase)
-    ActiveRecord::Migrator.prepend(PendingFilter)
-    ActiveRecord::Migrator.extend(PhaseAccessor)
+    ActiveRecord::Migrator.extend(Handcuffs::Extensions)
+    ActiveRecord::Migrator.prepend(Handcuffs::PendingFilterExt)
     ActiveRecord::Migrator.handcuffs_phase = phase
   end
 
   def run_task(name)
     Rake::Task.clear # necessary to avoid tasks being loaded several times in dev mode
-    Rails.application.load_tasks 
+    Rails.application.load_tasks
     Rake::Task[name].reenable # in case you're going to invoke the same task second time.
     Rake::Task[name].invoke
   end
-
-  module PendingFilter
-    def runnable
-      attempted_phase = self.class.handcuffs_phase
-      if(@direction == :up)
-        Handcuffs::PhaseFilter.new(attempted_phase, @direction).filter(super)
-      else
-        phase_migrations = Handcuffs::PhaseFilter.new(attempted_phase, @direction).filter(migrations)
-        runnable = phase_migrations[start..finish]
-        runnable.pop if target
-        runnable.find_all { |m| ran?(m) }
-      end
-    end
-  end
-
-  module PhaseAccessor
-    attr_accessor :handcuffs_phase
-  end
-
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: handcuffs
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Procore Technologies, Inc.
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-02-20 00:00:00.000000000 Z
+date: 2025-01-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: appraisal
@@ -72,14 +72,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '6.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '6.1'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -152,7 +152,9 @@ files:
 - lib/handcuffs/errors.rb
 - lib/handcuffs/errors/configuration_block_missing_error.rb
 - lib/handcuffs/extensions.rb
+- lib/handcuffs/pending_filter_ext.rb
 - lib/handcuffs/phase_filter.rb
+- lib/handcuffs/phases.rb
 - lib/handcuffs/railtie.rb
 - lib/handcuffs/version.rb
 - lib/tasks/handcuffs.rake
@@ -163,7 +165,7 @@ metadata:
   allowed_push_host: https://rubygems.org
   rubygems_mfa_required: 'true'
   homepage_uri: https://github.com/procore-oss/handcuffs/
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -171,7 +173,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -179,7 +181,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.4.19
-signing_key: 
+signing_key:
 specification_version: 4
 summary: A Ruby gem for running Active Record migrations in phases
 test_files: []