statecraft 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8c55553745396ae74c5ffdac6de4dfad3df8ed075e26ef06ac627084aa87216
-  data.tar.gz: 995e759e6a394619f991b1f6921065219a9259928f4797aa4a340f66c601e0b7
+  metadata.gz: 8e51b28a602d49b1cf5f71183e5c8b2080bd3e9f4e3a857147a65a7f5529373c
+  data.tar.gz: 2068032e1f963037d4521fbca8a02e53d5594bb5ce9902b9c809d1448ba7d9bd
 SHA512:
-  metadata.gz: 96794cd2d550849d99ccef2d9e6d0e12d12b790e585d7b8734a04a36ba55321f98bee6db237e9199e4c8ff02875900809070bc8fd295fb22dab7f5d41e71c87b
-  data.tar.gz: 6d5400fd71f2448099d9fc5c60ac71b663bbaed19b2c2d811e25172fa75148f970b9336b21fde31c09865f525dd428e2703314234bfb3e052c4dc1c5b2708085
+  metadata.gz: 4588eac402af35b053ce88660b39efb3a26694fdb9a5f3935844dedfff102f8d687f52af1c3b5da422cd7be99052bc55ef83e3f318d918746ef761bfba49a187
+  data.tar.gz: a995c7b056c6a2dd0beae23de1a06ced70f6ba3fbccce223375ea974f0fad506defd0bbf96426f10a3d2c95106be02c37c4075d569d1d8d342199bab8f8a6306

data/README.md

@@ -161,6 +161,36 @@ refused — the guards would be silently skipped. The escape hatch is explicit:
 still run) and records `event: nil` in the log, so audited bypasses stay
 visible.
 
+## Which rules belong in a guard
+
+Not every rule about a transition is a guard, and the three slots above are
+not an invitation to move form validation into the machine. One question
+draws the line: **would the rule still have to hold if the transition came
+from a job, a console or an ETL run instead of a form?**
+
+A rule about the record — this order is on credit, so it is not cancellable
+— always answers yes: it is a fact of the domain, it must hold for every
+caller, and it is checked inside the transaction where nothing can change
+under it. That is a `record_guard:`, and it is the case guards were built
+for.
+
+A rule that reads the input earns its place in two situations. The first is
+a rule that compares the input *against the record* — a refund amount that
+must not exceed the order total. One side of that comparison can change
+between a caller's check and the write, so the check belongs inside the
+transaction. The second is a rule protecting the log: metadata is write-once
+and the log is append-only, so a cancellation recorded without its reason
+stays useless forever. The last gate before something becomes permanent is
+worth having in the pipeline, whoever opened it.
+
+Everything else is the caller's job. A rule that reads only the input,
+never touches the record, and does not decide whether the log row makes
+sense — a minimum length, a format, a spelling — gains nothing from the
+machine but centralization, and it pays for that with a poorer contract: a
+guard answers with one boolean and a symbol, while a form object answers
+with several errors, attributed to fields, in the user's language. Validate
+the form in the form; hand the machine input it has already accepted.
+
 ## Callbacks and chains
 
 `before_transition`, `after_transition` and `after_commit` accept `from:`,
@@ -444,9 +474,18 @@ and parse them in the guard.
 
 Facts of the transition moment (a price snapshot, a rules version) are
 collected by the caller: `order.pay!(metadata: { price: order.total })`.
-There is no metadata schema mechanism — required fields are enforced by
-guards — and the shape evolves by convention: carry a `v:` key when you need
-versioned readers.
+There is no metadata schema mechanism, and the shape evolves by convention:
+carry a `v:` key when you need versioned readers.
+
+A guard can require a key, but that is a narrow licence rather than the
+schema mechanism in disguise: the reason to enforce a field here is that
+the row is about to become permanent — metadata is write-once and the log
+is append-only, so a field missing at insert time is missing for good. Note
+what such a guard does *not* buy: metadata is frozen at the pipeline
+entrance, before the transaction opens, so checking it inside a guard is no
+more atomic than checking it in the caller. Shape and format belong to
+whoever assembled the hash — see
+[which rules belong in a guard](#which-rules-belong-in-a-guard).
 
 ## Initial state is not a transition
 
@@ -575,6 +614,52 @@ statesman never had: see [Stale transitions](#stale-transitions-versioning-again
 — the version column is a constant default, so adding it costs a
 metadata-only migration on PostgreSQL 11+.
 
+## Migrating from aasm
+
+aasm already keeps the current state in a column, so this move is the
+opposite shape of the statesman one: nothing is backfilled, and the
+conversion adds the history aasm never had.
+
+```sh
+bin/rails generate statecraft:from_aasm Order
+```
+
+The generator reads the live aasm machine off the model (pass a second
+argument to name one machine of a model that declares several) and writes
+the machine skeleton, the log-table migration and the mounting line. More
+survives the trip than from statesman: aasm has real event names, and its
+state column arrives as the mounting's `column:`.
+
+Guards come over by nature. An aasm guard judges the record and never sees
+what the caller submitted, which is exactly statecraft's `record_guard:` —
+so a symbol `guard:`/`if:` becomes a `record_guard:` plus a generated
+one-line delegate (`def payable?(record) = record.payable?`, because a
+guard symbol resolves on the machine here, not on the record), and
+`unless: :locked?` becomes a negating delegate. A lambda guard carries its
+own closure and cannot be moved: it arrives as a TODO with its `file:line`.
+
+One graph shape is refused rather than guessed. aasm lets one event branch
+from a single state and picks the first transition whose guard passes;
+statecraft makes an event a partial function, so `from` is unique within an
+event. The generator stops, names the branching events, and asks you to
+split them in aasm first — the `pay` / `fail_payment` pattern. Naming the
+halves is a domain decision, and a bad name would outlive the migration.
+
+The migration creates the log table and adds an index on the existing state
+column. It deliberately does **not** tighten that column: `NOT NULL`, a
+default and a `CHECK` on a live table mean long locks and an explosion on
+any legacy row outside the state list. The recipe for doing it later, in
+the `NOT VALID` → `VALIDATE CONSTRAINT` style, sits in the migration's own
+header.
+
+Then finish by hand (the generator prints the list): drop `include AASM`
+and the `aasm do ... end` block. Event calls keep their names under
+`helpers: true`, but their semantics sharpen — a lost race now raises
+`TransitionConflict` where aasm quietly answered `false` or, without an
+explicit lock, silently overwrote the column. aasm's state predicates
+(`order.paid?`) are not generated: use `in_state?(:paid)` or the `paid`
+scope.
+
 ## PII and erasure
 
 Metadata is the only place personal data can live — `from_state`, `to_state`

data/lib/generators/statecraft/from_aasm/USAGE

@@ -0,0 +1,34 @@
+Description:
+    Migrates a model off aasm. aasm already keeps the current state in a
+    column, so nothing is backfilled: the conversion adds the append-only
+    history aasm never had, indexes the existing column and generates a
+    machine skeleton from the live aasm reflection.
+
+    Copied over: the states, the initial state, the real event names (unlike
+    statesman, aasm has them) and the state column, which becomes the
+    mounting's `column:`. Symbol guards (guard:/if:/unless:) come over as
+    record_guard: with a generated one-line delegate — aasm calls a guard on
+    the record, and statecraft resolves a guard symbol on the machine.
+    Lambda guards carry their own closure and cannot be moved: each becomes
+    a TODO comment with its source location.
+
+    The second argument names an aasm machine when the model declares
+    several (`aasm(:shipment)`); without it the unnamed machine is read.
+    An event that branches from one state (aasm picks the first transition
+    whose guard passes) is refused: statecraft makes an event a partial
+    function, so split it into two named events in aasm first.
+
+Example:
+    bin/rails generate statecraft:from_aasm Order
+
+    Creates (when missing) and edits:
+        app/state_machines/application_machine.rb
+        app/state_machines/order_flow.rb    (skeleton: states, events, guards)
+        app/models/order.rb                 (state_machine mounting line)
+        db/migrate/XXX_create_order_transitions.rb
+
+    The migration creates the log table and indexes the state column; the
+    column is otherwise left alone, with the NOT NULL / default / CHECK
+    recipe in its header. After running it, follow the printed cleanup list:
+    drop `include AASM` and the aasm block, and replace aasm's state
+    predicates (`order.paid?`) with `in_state?(:paid)` or the scope.

data/lib/generators/statecraft/from_aasm/from_aasm_generator.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Statecraft
+  module Generators
+    # `rails generate statecraft:from_aasm Order [machine_name]` — the door
+    # off aasm. Reads the live aasm machine through reflection (states, the
+    # initial state, real event names, the state column and the symbol
+    # guards), generates the machine skeleton, the log table migration and
+    # the mounting line. aasm keeps state in a column already, so nothing is
+    # backfilled: the conversion adds the history aasm never had.
+    class FromAasmGenerator < Rails::Generators::NamedBase
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      argument :aasm_machine_name, type: :string, required: false,
+                                   desc: "The named aasm machine (default: the unnamed one)"
+
+      def load_aasm_machine
+        @aasm_machine = resolve_aasm_machine
+        assert_graph_present
+        assert_no_branching_events
+      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_aasm.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_log_migration
+        migration_template "create_log_table.rb.tt",
+                           "#{migration_directory}/create_#{migration_slug}_transitions.rb"
+      end
+
+      def print_cleanup_instructions
+        say "\nOne migration: it creates the log table aasm never had and indexes " \
+            "the existing #{state_column} column.", :green
+        say "The column itself is left alone — NOT NULL, a default and a CHECK on a live"
+        say "table are locks and legacy-row explosions; the migration header carries the recipe."
+        say "\nAfter it runs, finish the move by hand:", :green
+        say "  * #{class_name}: drop `include AASM` and the whole `aasm do ... end` block."
+        say "  * Event calls keep their names with helpers: true (`order.pay!`), but a losing"
+        say "    race now raises TransitionConflict instead of quietly answering false."
+        say "  * aasm state predicates (`order.paid?`) are not generated: use `in_state?(:paid)`"
+        say "    or the `#{class_name}.paid` scope."
+        say "  * Guards that were lambdas are TODO comments in the skeleton — port them by hand."
+      end
+
+      private
+
+      def resolve_aasm_machine
+        unless model_class.respond_to?(:aasm)
+          raise Thor::Error, "#{class_name} does not respond to .aasm — " \
+                             "point the generator at the model that includes AASM"
+        end
+
+        machine = aasm_machine_name ? model_class.aasm(aasm_machine_name.to_sym) : model_class.aasm
+        unless machine.respond_to?(:states) && machine.respond_to?(:events)
+          raise Thor::Error, "#{class_name}.aasm does not look like an aasm machine (no .states/.events)"
+        end
+
+        machine
+      end
+
+      def model_class
+        @model_class ||= class_name.safe_constantize ||
+                         raise(Thor::Error, "model class #{class_name} not found — " \
+                                            "the generator reads the live aasm machine off it")
+      end
+
+      # A model with named machines answers the unnamed `.aasm` with the
+      # :default machine, which holds no states at all — a silently empty
+      # graph. Name the machines instead of generating a skeleton of nothing.
+      def assert_graph_present
+        return unless states.empty?
+
+        raise Thor::Error, "#{class_name}'s #{machine_label} declares no states#{named_machines_hint}"
+      end
+
+      def named_machines_hint
+        names = declared_machine_names - ["default"]
+        return "" if names.empty?
+
+        " — it declares named machines: #{names.join(", ")}; " \
+          "pass one: rails g statecraft:from_aasm #{name} #{names.first}"
+      end
+
+      def declared_machine_names
+        store = defined?(AASM::StateMachineStore) && AASM::StateMachineStore.fetch(model_class)
+        store.respond_to?(:machine_names) ? store.machine_names.map(&:to_s) : []
+      rescue StandardError
+        []
+      end
+
+      # aasm picks the first transition of an event whose guard passes, so one
+      # event may branch from a single state; statecraft compiles an event as a
+      # partial function (from is unique within an event) and refuses such a
+      # graph. The split is a domain decision, so the door stops here.
+      def assert_no_branching_events
+        branching = event_descriptors.filter_map do |event|
+          froms = event[:transitions].map { |transition| transition[:from] }
+          duplicated = froms.tally.select { |_from, count| count > 1 }.keys
+          "#{event[:name]} (from #{duplicated.join(", ")})" unless duplicated.empty?
+        end
+        return if branching.empty?
+
+        raise Thor::Error,
+              "these aasm events branch from one state: #{branching.join("; ")}. " \
+              "statecraft makes an event a partial function — within one event, from is unique. " \
+              "Split each into two named events (the pay / fail_payment pattern) in aasm first, " \
+              "then rerun this generator."
+      end
+
+      def event_descriptors
+        @event_descriptors ||= @aasm_machine.events.map do |event|
+          {
+            name: event.name,
+            transitions: event.transitions.map { |transition| describe_transition(event, transition) }
+          }
+        end
+      end
+
+      def describe_transition(event, transition)
+        options = transition.respond_to?(:opts) ? transition.opts : {}
+        { from: transition.from, to: transition.to, guard: guard_descriptor(event, transition, options) }
+      end
+
+      # aasm spells the record-level guard three ways and calls it on the
+      # record; statecraft's record_guard: is the same nature (arity 1) but
+      # resolves on the machine, so every symbol becomes a one-line delegate.
+      # A lambda carries its own closure and cannot be moved — it is reported.
+      def guard_descriptor(event, transition, options)
+        positive = options[:guard] || options[:if]
+        negative = options[:unless]
+        return symbol_guard(positive, negated: false) if positive.is_a?(Symbol)
+        return symbol_guard(negative, negated: true) if negative.is_a?(Symbol)
+
+        lambda_note(event, transition, positive || negative)
+      end
+
+      def symbol_guard(name, negated:)
+        { kind: :delegate, source: name, method_name: negated ? "not_#{name.to_s.delete_suffix("?")}?" : name.to_s,
+          negated: negated }
+      end
+
+      def lambda_note(event, transition, callable)
+        return nil if callable.nil?
+
+        location = callable.respond_to?(:source_location) ? callable.source_location&.join(":") : nil
+        origin = location ? " — defined at #{location}" : ""
+        { kind: :todo, note: "#{event.name} (#{transition.from} -> #{transition.to})#{origin}" }
+      end
+
+      def states
+        @states ||= @aasm_machine.states.map { |state| state.name.to_s }
+      end
+
+      def initial_state
+        @aasm_machine.initial_state.to_s
+      end
+
+      def events
+        event_descriptors.flat_map do |event|
+          event[:transitions].map do |transition|
+            { name: event[:name], from: transition[:from], to: transition[:to],
+              guard: delegate_guard(transition) }
+          end
+        end
+      end
+
+      def guard_delegates
+        events.filter_map { |event| event[:guard] }.uniq { |guard| guard[:method_name] }
+      end
+
+      def guard_todos
+        all_guards.filter_map { |guard| guard[:note] if guard[:kind] == :todo }
+      end
+
+      def delegate_guard(transition)
+        guard = transition[:guard]
+        guard if guard && guard[:kind] == :delegate
+      end
+
+      def all_guards
+        event_descriptors.flat_map { |event| event[:transitions].filter_map { |t| t[:guard] } }
+      end
+
+      def state_column
+        @aasm_machine.respond_to?(:attribute_name) ? @aasm_machine.attribute_name.to_s : "state"
+      end
+
+      def machine_label
+        aasm_machine_name ? "aasm machine #{aasm_machine_name}" : "unnamed aasm machine"
+      end
+
+      def mounting_line
+        column = state_column == "state" ? "" : "column: :#{state_column}, "
+        "  state_machine #{class_name}Flow, #{column}changed_at: true, helpers: true, scopes: true\n"
+      end
+
+      def model_file
+        "app/models/#{file_path}.rb"
+      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 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
+        "Create#{migration_slug.camelize}Transitions"
+      end
+    end
+  end
+end

data/lib/generators/statecraft/from_aasm/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_aasm/templates/create_log_table.rb.tt

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# aasm kept the state in <%= table_name %>.<%= state_column %> and kept no history at
+# all, so this migration adds only what the gem needs: the append-only log and
+# an index on the column the scopes will read.
+#
+# The column itself is deliberately left as aasm made it. To tighten it later
+# without blocking writes on a live table:
+#   ALTER TABLE <%= table_name %> ALTER COLUMN <%= state_column %> SET DEFAULT '<%= initial_state %>';
+#   -- backfill NULLs, then --
+#   ALTER TABLE <%= table_name %> ALTER COLUMN <%= state_column %> SET NOT NULL;
+#   ALTER TABLE <%= table_name %> ADD CONSTRAINT <%= table_name %>_<%= state_column %>_check
+#     CHECK (<%= state_column %> IN (<%= states.map { |state| "'#{state}'" }.join(", ") %>)) NOT VALID;
+#   -- clean the data --
+#   ALTER TABLE <%= table_name %> VALIDATE CONSTRAINT <%= table_name %>_<%= state_column %>_check;
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :<%= log_table_name.pluralize %> do |t|
+      t.references :<%= file_name %>,
+                   null: false, index: false,
+                   foreign_key: { to_table: :<%= table_name %>, on_delete: :cascade }
+      t.string :from_state, null: false
+      t.string :to_state, null: false
+      t.string :event
+      t.column :metadata, metadata_column_type, null: false, default: {}
+      t.datetime :created_at, null: false
+      t.index %i[<%= foreign_key_column %> id]
+    end
+
+    add_index :<%= table_name %>, :<%= state_column %> unless index_exists?(:<%= table_name %>, :<%= state_column %>)
+  end
+
+  private
+
+  # jsonb where the database has it, json elsewhere: the adapter is known
+  # only when the migration actually runs, never at generation time.
+  def metadata_column_type
+    connection.adapter_name.match?(/postg/i) ? :jsonb : :json
+  end
+end

data/lib/generators/statecraft/from_aasm/templates/machine_from_aasm.rb.tt

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Skeleton generated from <%= class_name %>'s <%= machine_label %>: the graph and
+# the event names are copied, the semantics are yours to port.
+#
+# - aasm guards judge the record and see no input, so every symbol guard came
+#   over as record_guard: with a one-line delegate below. A guard that reads
+#   what the caller submits belongs on guard: (arity 2) instead.
+# - lambda guards carry their own closure and cannot be moved; each is a TODO
+#   with its original location.
+class <%= class_name %>Flow < ApplicationMachine
+<% states.each do |state_name| -%>
+  state :<%= state_name %><%= state_name == initial_state ? ", initial: true" : "" %>
+<% end -%>
+
+<% events.each do |event| -%>
+  event :<%= event[:name] %>, from: :<%= event[:from] %>, to: :<%= event[:to] %><%= event[:guard] ? ", record_guard: :#{event[:guard][:method_name]}" : "" %>
+<% end -%>
+<% unless guard_todos.empty? -%>
+
+<% guard_todos.each do |note| -%>
+  # TODO(guard): <%= note %>
+<% end -%>
+<% end -%>
+<% unless guard_delegates.empty? -%>
+
+  private
+
+  # The machine keeps the registry "event -> predicate" and delegates the
+  # domain facts to the record, exactly where aasm called them.
+<% guard_delegates.each do |guard| -%>
+  def <%= guard[:method_name] %>(record) = <%= guard[:negated] ? "!record.#{guard[:source]}" : "record.#{guard[:source]}" %>
+<% end -%>
+<% end -%>
+end

data/lib/statecraft/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: statecraft
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Igor Pugachev
@@ -60,6 +60,11 @@ extra_rdoc_files: []
 files:
 - LICENSE.txt
 - README.md
+- lib/generators/statecraft/from_aasm/USAGE
+- lib/generators/statecraft/from_aasm/from_aasm_generator.rb
+- lib/generators/statecraft/from_aasm/templates/application_machine.rb.tt
+- lib/generators/statecraft/from_aasm/templates/create_log_table.rb.tt
+- lib/generators/statecraft/from_aasm/templates/machine_from_aasm.rb.tt
 - 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