statecraft 0.3.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a49958ae3b97e963ada9ee0cb6f719bd0fa5a784704d7f1479f0b045a921ec1
-  data.tar.gz: e6fe7115b639e25d33e752800af3324822497413865236be7f53e01dc56674bb
+  metadata.gz: f62004e4153d3351bda79f2cf1f09db95e42b83302d016909cbe7d8d081ef3ba
+  data.tar.gz: e005456aca83c931019db903ff6a860efff9111da2de5bbe35fe7021192e1f28
 SHA512:
-  metadata.gz: 92730425ebca1937db4f9e53bac01020102a7c6c90bc76fd5518697394bec18720cb70dd826017ca9b36d4e873cd0817a6399399565098e0dfc687db853ad68b
-  data.tar.gz: f7511de223aa42b0f44c5fc0b14a0be53965887262b01bb62c9a1954abb9e4e98b4a2b5688ee967ca672cd19514ddc2357fbcd796139074612ee2ac588975357
+  metadata.gz: 8c8bd36f37d3c0392cfc4c17562f071f66e8e3252253e2237bc84283418dea222db32327e30aab4f3cd10b408e37852f6cddf3f93171a026194f1a6787f26c83
+  data.tar.gz: f1a14781c925c5bc72da7e7120fc8e1e0a4809b17f36f03f8e55b72e6a8a1163056b730804bb871d0961d1139428bd1084cffa5437f03847674e1dd49c989c9d

data/README.md

@@ -337,6 +337,63 @@ rolling rename recipe on the column:
    after the cleanup.
 3. Drop the old state and its edges; narrow the CHECK back.
 
+## Migrating from statesman
+
+The names already match: statesman's `order_transitions` table and
+`OrderTransition` class are exactly what statecraft's log convention expects,
+so the move is an in-place conversion of the table you already have — history
+stays where it is, nothing is copied.
+
+```sh
+bin/rails generate statecraft:from_statesman Order
+```
+
+The generator reads the live statesman machine through reflection (pass the
+class as a second argument when it is not `OrderStateMachine`; point at the
+class that declares the DSL — statesman graphs are not inherited) and writes
+three things: the conversion migration, a machine skeleton, and the
+`state_machine` mounting line. Two things it honestly cannot write: statesman
+has no events, so every edge arrives as a bare `transition` for you to name,
+and guard bodies are anonymous blocks — each becomes a TODO comment carrying
+the original `file:line`.
+
+The migration converts in this order:
+
+1. The model gains its `state` column, backfilled from the **last transition
+   by `sort_key`** — deliberately not `most_recent`, which drifts out of sync
+   often enough that statesman ships a repair task for it. Rows with no
+   transitions get the initial state; a CHECK constraint pins the value set.
+2. The transitions table gains `from_state` (a `LAG` window along the
+   `sort_key` chain, the first hop starting from the initial state) and a
+   nullable `event` — imported history reads as direct transitions, which is
+   the honest description of what statesman recorded.
+3. A text `metadata` column becomes native json(b) in one indivisible move
+   with removing `serialize` from the model: neither library works in the
+   half-converted state, so the type change and the code change ship
+   together.
+4. The foreign key is re-created with `ON DELETE CASCADE` (statesman's
+   default one carries no action), statesman's unique indexes go, and the
+   `[foreign_key, id]` index that serves statecraft's history reads arrives.
+5. `sort_key`, `most_recent` and `updated_at` are dropped last — the first
+   two would break the log INSERT outright, being NOT NULL without defaults.
+
+The migration's header names two pre-flight checks on live data — that the
+id order agrees with the `sort_key` order (statecraft reads history by id),
+and that a text `metadata` column holds valid JSON in every row (rows written
+by raw SQL may not survive the cast). Run both before migrating.
+
+After the migration, finish by hand (the generator prints this list): drop
+`Statesman::Adapters::ActiveRecordTransition` and the
+`after_destroy :update_most_recent` callback from the transition model — they
+read dropped columns — plus `ActiveRecordQueries` from the model and the
+`Statesman.configure` initializer once no machine is left; then name your
+events in the skeleton. One guarantee moves rather than disappears: the
+race safety statesman derived from its unique `(parent, sort_key)` index is
+statecraft's CAS on the state column.
+
+Outside Rails, the same steps work by hand — pair the migration order above
+with the reference schema in [Outside Rails](#outside-rails).
+
 ## PII and erasure
 
 Metadata is the only place personal data can live — `from_state`, `to_state`
@@ -649,6 +706,8 @@ AR_VERSION=7.2 RUBY_VERSION=3.3 docker compose run --rm test-postgres
 ## Links
 
 - Landing page: <https://supostat.github.io/statecraft/>
+- Benchmarks vs statesman/aasm: <https://supostat.github.io/statecraft/compare.html>
+  (reproducible scripts in [`benchmark/`](benchmark/))
 - RubyGems: <https://rubygems.org/gems/statecraft>
 - Issues: <https://github.com/supostat/statecraft/issues>
 

data/lib/generators/statecraft/from_statesman/USAGE

@@ -0,0 +1,30 @@
+Description:
+    Migrates a model off statesman: converts its transitions table into the
+    statecraft log IN PLACE (the names already match the gem's convention),
+    gives the model its state column with a backfill from the last
+    transition, generates a machine skeleton from the statesman class's
+    reflection, and mounts the machine.
+
+    The statesman machine is read through reflection: states, the initial
+    state and the transition graph are copied; events and guard bodies
+    cannot be — statesman has no events (name them yourself in the skeleton)
+    and guard bodies are anonymous blocks (each becomes a TODO comment with
+    its original source location).
+
+    The second argument names the statesman machine class; without it the
+    <Model>StateMachine convention is assumed. Statesman graphs are not
+    inherited — point at the class that declares the DSL.
+
+Example:
+    bin/rails generate statecraft:from_statesman Order
+
+    Creates (when missing) and edits:
+        app/state_machines/application_machine.rb
+        app/state_machines/order_flow.rb        (skeleton: graph + TODOs)
+        app/models/order.rb                     (state_machine mounting line)
+        db/migrate/XXX_convert_order_transitions_to_statecraft.rb
+
+    The migration header lists two pre-flight checks on live data (id order
+    vs sort_key order; text metadata holding valid JSON) — read it before
+    running. After migrating, follow the printed cleanup list: drop the
+    statesman includes, the configure initializer, and name your events.

data/lib/generators/statecraft/from_statesman/from_statesman_generator.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Statecraft
+  module Generators
+    # `rails generate statecraft:from_statesman Order [OrderStateMachine]` —
+    # the migration path off statesman. Reads the live statesman machine
+    # through reflection (states, initial state, transition graph, guard
+    # locations), generates the in-place conversion migration that turns the
+    # statesman transitions table into this gem's log, a machine skeleton
+    # whose events and guards are left for the human, and mounts the machine
+    # into the model. The statesman class itself is never loaded by name
+    # magic beyond the optional second argument's default.
+    class FromStatesmanGenerator < Rails::Generators::NamedBase
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      argument :statesman_machine_name, type: :string, required: false,
+                                        desc: "The statesman machine class (default: <Model>StateMachine)"
+
+      def load_statesman_machine
+        @statesman_machine = resolve_statesman_machine
+        @initial_state = @statesman_machine.initial_state
+        return unless @initial_state.nil?
+
+        raise Thor::Error, "#{statesman_class_name} declares no initial state; " \
+                           "statecraft requires exactly one — declare `state ..., initial: true` first"
+      end
+
+      def create_application_machine
+        application_machine_path = "app/state_machines/application_machine.rb"
+        return if File.exist?(File.join(destination_root, application_machine_path))
+
+        template "application_machine.rb.tt", application_machine_path
+      end
+
+      def create_machine_skeleton
+        template "machine_from_statesman.rb.tt", "app/state_machines/#{file_path}_flow.rb"
+      end
+
+      def mount_model
+        unless File.exist?(File.join(destination_root, model_file))
+          say_status :skip, "#{model_file} not found — mount the machine yourself: #{mounting_line.strip}", :yellow
+          return
+        end
+
+        inject_into_class model_file, class_name, mounting_line
+      end
+
+      def create_conversion_migration
+        migration_template "convert_transitions_migration.rb.tt",
+                           "#{migration_directory}/convert_#{migration_slug}_transitions_to_statecraft.rb"
+      end
+
+      def print_cleanup_instructions
+        say "\nAfter running the migration, finish the move by hand:", :green
+        say "  * #{log_class_name}: drop `include Statesman::Adapters::ActiveRecordTransition` and"
+        say "    the `after_destroy :update_most_recent` callback (they read dropped columns);"
+        say "    consider adding `def readonly? = persisted?` — the pipeline inserts around it."
+        say "  * #{class_name}: drop `include Statesman::Adapters::ActiveRecordQueries` and the"
+        say "    state_machine/transition helper methods that wrapped statesman."
+        say "  * Delete the `Statesman.configure` initializer once no machine is left."
+        say "  * Name your events in app/state_machines/#{file_path}_flow.rb — statesman had none."
+      end
+
+      private
+
+      def resolve_statesman_machine
+        machine_class = statesman_class_name.safe_constantize
+        if machine_class.nil?
+          raise Thor::Error, "statesman machine class #{statesman_class_name} not found — " \
+                             "pass it explicitly: rails g statecraft:from_statesman #{name} YourMachineClass"
+        end
+
+        unless machine_class.respond_to?(:states) && machine_class.respond_to?(:successors)
+          raise Thor::Error, "#{statesman_class_name} does not look like a statesman machine " \
+                             "(no .states/.successors); note that statesman graphs are not inherited — " \
+                             "point at the class that declares the DSL"
+        end
+
+        machine_class
+      end
+
+      def statesman_class_name
+        statesman_machine_name || "#{class_name}StateMachine"
+      end
+
+      attr_reader :initial_state
+
+      def states
+        @statesman_machine.states.map(&:to_s)
+      end
+
+      # statesman accumulates successors without deduplication and statecraft
+      # refuses a duplicate edge at compile time, so uniq is load-bearing.
+      def edges
+        @statesman_machine.successors.flat_map do |from, destinations|
+          Array(destinations).map { |to| [from.to_s, to.to_s] }
+        end.uniq
+      end
+
+      def guard_notes
+        return [] unless @statesman_machine.respond_to?(:callbacks)
+
+        Array(@statesman_machine.callbacks[:guards]).map do |guard|
+          origin = guard.callback.respond_to?(:source_location) ? guard.callback.source_location&.join(":") : nil
+          from_label = guard.from || "any"
+          to_label = Array(guard.to).empty? ? "any" : Array(guard.to).join("/")
+          note = "#{from_label} -> #{to_label}"
+          origin ? "#{note} (defined at #{origin})" : note
+        end
+      end
+
+      def mounting_line
+        "  state_machine #{class_name}Flow, changed_at: true, helpers: true, scopes: true\n"
+      end
+
+      def model_file
+        "app/models/#{file_path}.rb"
+      end
+
+      def model_class
+        class_name.safe_constantize
+      end
+
+      def table_name
+        @table_name ||= model_class.respond_to?(:table_name) ? model_class.table_name : super
+      end
+
+      def log_table_name
+        "#{table_name.singularize}_transitions"
+      end
+
+      def log_class_name
+        "#{class_name}Transition"
+      end
+
+      def foreign_key_column
+        "#{file_name}_id"
+      end
+
+      def migration_directory
+        db_config = model_class.respond_to?(:connection_db_config) && model_class.connection_db_config
+        configured = db_config && Array(db_config.migrations_paths).first
+        configured || "db/migrate"
+      end
+
+      def migration_slug
+        file_path.tr("/", "_")
+      end
+
+      def migration_class_name
+        "Convert#{migration_slug.camelize}TransitionsToStatecraft"
+      end
+    end
+  end
+end

data/lib/generators/statecraft/from_statesman/templates/application_machine.rb.tt

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Shared home for private guard helpers used by several machines. Keep it
+# free of DSL declarations (states, transitions, events): machine definitions
+# are NOT inherited — each machine declares its own graph.
+class ApplicationMachine
+  include Statecraft::Machine
+end

data/lib/generators/statecraft/from_statesman/templates/convert_transitions_migration.rb.tt

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+# Converts the statesman transitions table <%= log_table_name %> into the
+# statecraft log IN PLACE and gives <%= table_name %> its state column.
+#
+# BEFORE RUNNING — two checks on live data, both cheap:
+#
+# 1. statecraft reads history ordered by id, statesman ordered by sort_key.
+#    They almost always agree; prove it for your data (must return 0 rows):
+#
+#      SELECT t.<%= foreign_key_column %> FROM <%= log_table_name %> t
+#      JOIN <%= log_table_name %> later ON later.<%= foreign_key_column %> = t.<%= foreign_key_column %>
+#        AND later.sort_key > t.sort_key AND later.id < t.id LIMIT 1;
+#
+# 2. If your metadata column is text, every row must hold valid JSON (rows
+#    written by raw SQL may not) — the jsonb cast below dies on the first
+#    invalid one.
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def up
+    convert_parent_table
+    convert_transitions_table
+    convert_metadata_column
+    rebuild_indexes_and_foreign_key
+    drop_statesman_columns
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration
+  end
+
+  private
+
+  def convert_parent_table
+    add_column :<%= table_name %>, :state, :string
+    add_column :<%= table_name %>, :state_changed_at, :datetime
+
+    # The current state is the to_state of the LAST transition by sort_key —
+    # deliberately not most_recent, which statesman itself ships a repair
+    # rake task for; rows without transitions are in the initial state.
+    execute <<~SQL
+      UPDATE <%= table_name %> SET state = COALESCE(
+        (SELECT t.to_state FROM <%= log_table_name %> t
+         WHERE t.<%= foreign_key_column %> = <%= table_name %>.id
+         ORDER BY t.sort_key DESC LIMIT 1),
+        '<%= initial_state %>'
+      )
+    SQL
+
+    # The mounting says changed_at: true, so the column must exist — and the
+    # conversion knows the honest value: the moment of the last recorded
+    # transition. Rows that never transitioned stay NULL, exactly like a
+    # freshly created record.
+    execute <<~SQL
+      UPDATE <%= table_name %> SET state_changed_at =
+        (SELECT MAX(t.created_at) FROM <%= log_table_name %> t
+         WHERE t.<%= foreign_key_column %> = <%= table_name %>.id)
+    SQL
+
+    change_column_default :<%= table_name %>, :state, "<%= initial_state %>"
+    change_column_null :<%= table_name %>, :state, false
+
+    return unless connection.supports_check_constraints?
+
+    # add new states here when the machine grows
+    if postgresql?
+      add_check_constraint :<%= table_name %>, state_check_expression,
+                           name: "<%= table_name %>_state_check", validate: false
+      validate_check_constraint :<%= table_name %>, name: "<%= table_name %>_state_check"
+    else
+      add_check_constraint :<%= table_name %>, state_check_expression,
+                           name: "<%= table_name %>_state_check"
+    end
+  end
+
+  def convert_transitions_table
+    add_column :<%= log_table_name %>, :from_state, :string
+    add_column :<%= log_table_name %>, :event, :string
+
+    # from_state is the previous to_state along the sort_key chain; the
+    # chain's first hop starts from the initial state. Runs while sort_key
+    # is still alive — order matters.
+    execute <<~SQL
+      UPDATE <%= log_table_name %> SET from_state = COALESCE(prev.prev_state, '<%= initial_state %>')
+      FROM (SELECT id, LAG(to_state) OVER (
+              PARTITION BY <%= foreign_key_column %> ORDER BY sort_key
+            ) AS prev_state
+            FROM <%= log_table_name %>) prev
+      WHERE prev.id = <%= log_table_name %>.id
+    SQL
+
+    change_column_null :<%= log_table_name %>, :from_state, false
+    # event stays NULL for the imported history: statesman had no events, and
+    # statecraft reads NULL as a direct transition.
+  end
+
+  # Statesman's default schema serializes metadata into a text column; the
+  # statecraft pipeline wants native json(b). Converting the type and
+  # removing `serialize :metadata` from the transition model are ONE move —
+  # neither library works in the half-converted state.
+  def convert_metadata_column
+    metadata_type = connection.columns(:<%= log_table_name %>).find { |column| column.name == "metadata" }&.sql_type.to_s
+    return unless metadata_type.match?(/text|char/i)
+
+    if postgresql?
+      change_column_default :<%= log_table_name %>, :metadata, nil
+      execute "ALTER TABLE <%= log_table_name %> ALTER COLUMN metadata TYPE jsonb USING metadata::jsonb"
+      execute "UPDATE <%= log_table_name %> SET metadata = '{}'::jsonb WHERE metadata IS NULL"
+      change_column_default :<%= log_table_name %>, :metadata, {}
+      change_column_null :<%= log_table_name %>, :metadata, false
+    else
+      # SQLite types dynamically and serialize already stored JSON text —
+      # the change is declarative (a table rebuild under the hood).
+      change_column :<%= log_table_name %>, :metadata, :json, null: false, default: {}
+    end
+  end
+
+  def rebuild_indexes_and_foreign_key
+    # If your foreign key column is NOT named <%= foreign_key_column %>
+    # (check the has_many on your model), rename it first — statecraft
+    # derives the name from the model class and offers no override:
+    #   rename_column :<%= log_table_name %>, :your_column, :<%= foreign_key_column %>
+
+    remove_index :<%= log_table_name %>, column: %i[<%= foreign_key_column %> sort_key], if_exists: true
+    remove_index :<%= log_table_name %>, column: %i[<%= foreign_key_column %> most_recent], if_exists: true
+    add_index :<%= log_table_name %>, %i[<%= foreign_key_column %> id]
+
+    # An audit without its subject is not an audit: the statecraft contract
+    # is ON DELETE CASCADE (statesman's default foreign key, when present,
+    # carries no action).
+    if foreign_key_exists?(:<%= log_table_name %>, :<%= table_name %>)
+      remove_foreign_key :<%= log_table_name %>, :<%= table_name %>
+    end
+    add_foreign_key :<%= log_table_name %>, :<%= table_name %>,
+                    column: :<%= foreign_key_column %>, on_delete: :cascade
+  end
+
+  # sort_key and most_recent are NOT NULL without defaults — the first
+  # statecraft insert would die on them; updated_at is merely absent from
+  # the statecraft schema.
+  def drop_statesman_columns
+    remove_column :<%= log_table_name %>, :sort_key
+    remove_column :<%= log_table_name %>, :most_recent if column_exists?(:<%= log_table_name %>, :most_recent)
+    remove_column :<%= log_table_name %>, :updated_at if column_exists?(:<%= log_table_name %>, :updated_at)
+  end
+
+  def state_check_expression
+    "state IN ('<%= initial_state %>'<% (states - [initial_state]).each do |state_name| %>, '<%= state_name %>'<% end %>)"
+  end
+
+  def postgresql?
+    connection.adapter_name.match?(/postg/i)
+  end
+end

data/lib/generators/statecraft/from_statesman/templates/machine_from_statesman.rb.tt

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Skeleton generated from <%= statesman_class_name %>: the graph is copied,
+# the semantics are yours to port.
+#
+# - statesman has no events, so every edge below is a bare transition. Where
+#   an edge is really a command in your domain, name it:
+#     event :pay, from: :pending, to: :paid
+# - statesman guard bodies cannot be extracted; each is listed as a TODO with
+#   its original location. Port a guard that judges the record alone as
+#   record_guard: (arity 1), one that reads the input as guard:.
+class <%= class_name %>Flow < ApplicationMachine
+<% states.each do |state_name| -%>
+  state :<%= state_name %><%= state_name == initial_state ? ", initial: true" : "" %>
+<% end -%>
+
+<% edges.each do |from, to| -%>
+  transition from: :<%= from %>, to: :<%= to %>
+<% end -%>
+<% unless guard_notes.empty? -%>
+
+<% guard_notes.each do |note| -%>
+  # TODO(guard): <%= note %>
+<% end -%>
+<% end -%>
+end

data/lib/statecraft/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Statecraft
-  VERSION = "0.3.0"
+  VERSION = "0.4.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: statecraft
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Igor Pugachev
@@ -60,6 +60,11 @@ extra_rdoc_files: []
 files:
 - LICENSE.txt
 - README.md
+- lib/generators/statecraft/from_statesman/USAGE
+- lib/generators/statecraft/from_statesman/from_statesman_generator.rb
+- lib/generators/statecraft/from_statesman/templates/application_machine.rb.tt
+- lib/generators/statecraft/from_statesman/templates/convert_transitions_migration.rb.tt
+- lib/generators/statecraft/from_statesman/templates/machine_from_statesman.rb.tt
 - lib/generators/statecraft/machine/USAGE
 - lib/generators/statecraft/machine/machine_generator.rb
 - lib/generators/statecraft/machine/templates/add_migration.rb.tt