igniter 0.5.0 → 0.5.2

data/examples/order_pipeline.rb

@@ -1,163 +0,0 @@
-# frozen_string_literal: true
-
-# Order Pipeline — guard + collection + branch + export
-#
-# Flow:
-#   1. guard      — require in_stock == true before proceeding
-#   2. collection — compute subtotal per line item (LineItemContract per item)
-#   3. compute    — aggregate item subtotals into order_subtotal
-#   4. branch     — choose domestic or international shipping strategy
-#   5. export     — pull shipping_cost and eta out of the selected branch
-#   6. output     — order_subtotal, shipping_cost, eta, grand_total
-#
-# Run: ruby examples/order_pipeline.rb
-
-$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
-require "igniter"
-
-# ── Line Item ────────────────────────────────────────────────────────────────
-
-class LineItemContract < Igniter::Contract
-  define do
-    input :sku,        type: :string
-    input :quantity,   type: :numeric
-    input :unit_price, type: :numeric
-
-    compute :subtotal, depends_on: %i[quantity unit_price] do |quantity:, unit_price:|
-      (quantity * unit_price).round(2)
-    end
-
-    output :sku
-    output :subtotal
-  end
-end
-
-# ── Shipping Strategies ──────────────────────────────────────────────────────
-
-class DomesticShippingContract < Igniter::Contract
-  define do
-    input :country,  type: :string
-    input :subtotal, type: :numeric
-
-    compute :shipping_cost, depends_on: :subtotal do |subtotal:|
-      subtotal >= 100 ? 0.0 : 9.99
-    end
-
-    compute :eta, depends_on: :country do |country:|
-      country == "US" ? "2-3 business days" : "3-5 business days"
-    end
-
-    output :shipping_cost
-    output :eta
-  end
-end
-
-class InternationalShippingContract < Igniter::Contract
-  define do
-    input :country,  type: :string
-    input :subtotal, type: :numeric
-
-    compute :shipping_cost, depends_on: :subtotal do |subtotal:|
-      (subtotal * 0.15).round(2)
-    end
-
-    compute :eta, depends_on: :country do |**|
-      "7-14 business days"
-    end
-
-    output :shipping_cost
-    output :eta
-  end
-end
-
-# ── Order Pipeline ────────────────────────────────────────────────────────────
-
-class OrderPipelineContract < Igniter::Contract
-  define do # rubocop:disable Metrics/BlockLength
-    input :line_items, type: :array
-    input :country,    type: :string
-    input :in_stock,   type: :boolean
-
-    # Guard fires before anything else is computed
-    guard :stock_available,
-          with: :in_stock,
-          eq: true,
-          message: "Order cannot be placed: items are out of stock"
-
-    # Gate node: depends on the guard — if guard fails, this node fails too,
-    # which blocks the collection and all downstream nodes from running.
-    compute :gated_items, depends_on: %i[line_items stock_available] do |line_items:, **|
-      line_items
-    end
-
-    # Fan-out: one LineItemContract per item hash
-    collection :items,
-               with: :gated_items,
-               each: LineItemContract,
-               key: :sku,
-               mode: :collect
-
-    # Sum succeeded item subtotals
-    compute :order_subtotal, depends_on: :items do |items:|
-      items.successes.values.sum { |item| item.result.subtotal }.round(2)
-    end
-
-    # Route to the right shipping strategy based on country
-    branch :shipping,
-           with: :country,
-           inputs: { country: :country, subtotal: :order_subtotal } do
-      on "US", contract: DomesticShippingContract
-      on "CA", contract: DomesticShippingContract
-      default contract: InternationalShippingContract
-    end
-
-    # Lift shipping outputs up to the top-level graph
-    # export calls output internally, so no separate output declarations needed
-    export :shipping_cost, :eta, from: :shipping
-
-    compute :grand_total, depends_on: %i[order_subtotal shipping_cost] do |order_subtotal:, shipping_cost:|
-      (order_subtotal + shipping_cost).round(2)
-    end
-
-    output :items
-    output :order_subtotal
-    output :grand_total
-  end
-end
-
-# ── Run ───────────────────────────────────────────────────────────────────────
-
-line_items = [
-  { sku: "ruby-book",    quantity: 2, unit_price: 29.99 },
-  { sku: "rails-course", quantity: 1, unit_price: 49.99 },
-  { sku: "keyboard",     quantity: 1, unit_price: 89.99 }
-]
-
-# US order — free shipping over $100
-us_order = OrderPipelineContract.new(line_items: line_items, country: "US", in_stock: true)
-us_order.resolve_all
-
-puts "=== US Order ==="
-puts "items_summary=#{us_order.result.items.summary.inspect}"
-puts "order_subtotal=#{us_order.result.order_subtotal}"
-puts "shipping_cost=#{us_order.result.shipping_cost}"
-puts "eta=#{us_order.result.eta}"
-puts "grand_total=#{us_order.result.grand_total}"
-
-# International order — 15% shipping
-intl_order = OrderPipelineContract.new(line_items: line_items, country: "DE", in_stock: true)
-intl_order.resolve_all
-
-puts "\n=== International Order (DE) ==="
-puts "shipping_cost=#{intl_order.result.shipping_cost}"
-puts "eta=#{intl_order.result.eta}"
-puts "grand_total=#{intl_order.result.grand_total}"
-
-# Out of stock — guard fires and raises ResolutionError
-oos_order = OrderPipelineContract.new(line_items: line_items, country: "US", in_stock: false)
-begin
-  oos_order.resolve_all
-rescue Igniter::ResolutionError => e
-  puts "\n=== Out of Stock ==="
-  puts "error=#{e.message.split(" [").first}"
-end

data/examples/provenance.rb

@@ -1,122 +0,0 @@
-# frozen_string_literal: true
-
-# Provenance — data lineage for Igniter contracts
-#
-# After a contract resolves, provenance answers:
-#   "How was this output computed, and which inputs influenced it?"
-#
-# Run: ruby examples/provenance.rb
-
-$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
-require "igniter"
-require "igniter/extensions/provenance"
-
-# ── Contracts ─────────────────────────────────────────────────────────────────
-
-class TierDiscountContract < Igniter::Contract
-  TIERS = { bronze: 0, silver: 10, gold: 20, platinum: 30 }.freeze
-
-  define do
-    input :user_tier, type: :symbol
-
-    compute :discount_pct, depends_on: :user_tier do |user_tier:|
-      TierDiscountContract::TIERS.fetch(user_tier, 0)
-    end
-
-    output :discount_pct
-  end
-end
-
-class PricingContract < Igniter::Contract
-  define do
-    input :base_price,     type: :numeric
-    input :quantity,       type: :numeric
-    input :user_tier,      type: :symbol
-
-    compute :unit_price, depends_on: :base_price do |base_price:|
-      (base_price * 1.08).round(2) # +8% margin
-    end
-
-    compute :subtotal, depends_on: %i[unit_price quantity] do |unit_price:, quantity:|
-      (unit_price * quantity).round(2)
-    end
-
-    compose :tier_info, contract: TierDiscountContract,
-                        inputs: { user_tier: :user_tier }
-
-    compute :discount_amount, depends_on: %i[subtotal tier_info] do |subtotal:, tier_info:|
-      (subtotal * tier_info.discount_pct / 100.0).round(2)
-    end
-
-    compute :grand_total, depends_on: %i[subtotal discount_amount] do |subtotal:, discount_amount:|
-      (subtotal - discount_amount).round(2)
-    end
-
-    output :unit_price
-    output :subtotal
-    output :discount_amount
-    output :grand_total
-  end
-end
-
-# ── Run ───────────────────────────────────────────────────────────────────────
-
-puts "=== Provenance Demo ==="
-puts
-
-contract = PricingContract.new(
-  base_price: 100.0,
-  quantity: 3,
-  user_tier: :gold
-)
-contract.resolve_all
-
-puts "grand_total=#{contract.result.grand_total}"
-puts
-
-# ── ASCII tree ────────────────────────────────────────────────────────────────
-
-puts "--- explain(:grand_total) ---"
-puts contract.explain(:grand_total)
-puts
-
-# ── Query API ─────────────────────────────────────────────────────────────────
-
-lin = contract.lineage(:grand_total)
-
-puts "--- contributing_inputs ---"
-lin.contributing_inputs.each do |input_name, val|
-  puts "  #{input_name} = #{val.inspect}"
-end
-puts
-
-puts "--- sensitive_to? ---"
-puts "sensitive_to?(:base_price)  = #{lin.sensitive_to?(:base_price)}"
-puts "sensitive_to?(:quantity)    = #{lin.sensitive_to?(:quantity)}"
-puts "sensitive_to?(:user_tier)   = #{lin.sensitive_to?(:user_tier)}"
-puts "sensitive_to?(:unknown_key) = #{lin.sensitive_to?(:unknown_key)}"
-puts
-
-puts "--- path_to(:base_price) ---"
-puts lin.path_to(:base_price).inspect
-puts
-
-puts "--- path_to(:user_tier) ---"
-puts lin.path_to(:user_tier).inspect
-puts
-
-# ── Composition output lineage ────────────────────────────────────────────────
-
-puts "--- explain(:discount_amount) ---"
-puts contract.explain(:discount_amount)
-puts
-
-# ── Structured lineage (to_h) ─────────────────────────────────────────────────
-
-puts "--- lineage(:subtotal).to_h (keys only) ---"
-h = contract.lineage(:subtotal).to_h
-puts "node=#{h[:node]}, kind=#{h[:kind]}, value=#{h[:value]}"
-puts "contributing=#{h[:contributing].keys.inspect}"
-puts
-
-puts "done=true"

data/examples/ringcentral_routing.rb

@@ -1,269 +0,0 @@
-# frozen_string_literal: true
-
-$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
-require "igniter"
-require "pp"
-
-class InboundCallContract < Igniter::Contract
-  define do
-    input :session_id, type: :string
-    input :direction, type: :string
-    input :from, type: :string
-    input :to, type: :string
-    input :start_time, type: :string
-
-    compute :summary, with: %i[session_id from to start_time] do |session_id:, from:, to:, start_time:|
-      {
-        session_id: session_id,
-        direction: "Inbound",
-        customer_phone: from,
-        lookup_phone: from,
-        dialed_phone: to,
-        started_at: start_time
-      }
-    end
-
-    output :summary
-  end
-end
-
-class OutboundCallContract < Igniter::Contract
-  define do
-    input :session_id, type: :string
-    input :direction, type: :string
-    input :from, type: :string
-    input :to, type: :string
-    input :start_time, type: :string
-
-    compute :summary, with: %i[session_id from to start_time] do |session_id:, from:, to:, start_time:|
-      {
-        session_id: session_id,
-        direction: "Outbound",
-        customer_phone: to,
-        lookup_phone: to,
-        operator_phone: from,
-        started_at: start_time
-      }
-    end
-
-    output :summary
-  end
-end
-
-class UnknownDirectionContract < Igniter::Contract
-  define do
-    input :session_id, type: :string
-    input :direction, type: :string
-    input :from, type: :string
-    input :to, type: :string
-    input :start_time, type: :string
-
-    compute :summary, with: %i[session_id direction] do |session_id:, direction:|
-      {
-        session_id: session_id,
-        direction: direction,
-        ignored: true
-      }
-    end
-
-    output :summary
-  end
-end
-
-class CallEventContract < Igniter::Contract
-  define do
-    input :session_id, type: :string
-    input :direction, type: :string
-    input :from, type: :string
-    input :to, type: :string
-    input :start_time, type: :string
-
-    branch :call_context, with: :direction, inputs: {
-      session_id: :session_id,
-      direction: :direction,
-      from: :from,
-      to: :to,
-      start_time: :start_time
-    } do
-      on "Inbound", contract: InboundCallContract
-      on "Outbound", contract: OutboundCallContract
-      default contract: UnknownDirectionContract
-    end
-
-    export :summary, from: :call_context
-  end
-end
-
-class CallConnectedContract < Igniter::Contract
-  define do
-    input :extension_id, type: :integer
-    input :active_calls, type: :array
-    input :telephony_status, type: :string
-
-    guard :has_calls, with: :active_calls, message: "No active calls" do |active_calls:|
-      active_calls.any?
-    end
-
-    collection :calls,
-      with: :active_calls,
-      each: CallEventContract,
-      key: :session_id,
-      mode: :collect,
-      map_inputs: lambda { |item:|
-        {
-          session_id: item.fetch("telephonySessionId"),
-          direction: item.fetch("direction"),
-          from: item.fetch("from"),
-          to: item.fetch("to"),
-          start_time: item.fetch("startTime")
-        }
-      }
-
-    compute :call_summaries, with: :calls do |calls:|
-      calls.successes.values.map { |item| item.result.summary }
-    end
-
-    compute :routing_summary, with: %i[calls call_summaries extension_id telephony_status has_calls] do |calls:, call_summaries:, extension_id:, telephony_status:, has_calls:|
-      has_calls
-      {
-        extension_id: extension_id,
-        telephony_status: telephony_status,
-        total_calls: calls.summary[:total],
-        succeeded_calls: calls.summary[:succeeded],
-        failed_calls: calls.summary[:failed],
-        inbound_calls: call_summaries.count { |item| item[:direction] == "Inbound" },
-        outbound_calls: call_summaries.count { |item| item[:direction] == "Outbound" },
-        ignored_calls: call_summaries.count { |item| item[:ignored] }
-      }
-    end
-
-    output :calls
-    output :routing_summary
-  end
-end
-
-class NoCallContract < Igniter::Contract
-  define do
-    input :extension_id, type: :integer
-    input :telephony_status, type: :string
-    input :active_calls, type: :array
-
-    compute :routing_summary, with: %i[extension_id telephony_status] do |extension_id:, telephony_status:|
-      {
-        extension_id: extension_id,
-        telephony_status: telephony_status,
-        clear_operator: true
-      }
-    end
-
-    output :routing_summary
-  end
-end
-
-class RingingContract < Igniter::Contract
-  define do
-    input :extension_id, type: :integer
-    input :telephony_status, type: :string
-    input :active_calls, type: :array
-
-    compute :routing_summary, with: %i[extension_id telephony_status] do |extension_id:, telephony_status:|
-      {
-        extension_id: extension_id,
-        telephony_status: telephony_status,
-        ringing: true
-      }
-    end
-
-    output :routing_summary
-  end
-end
-
-class UnknownStatusContract < Igniter::Contract
-  define do
-    input :extension_id, type: :integer
-    input :telephony_status, type: :string
-    input :active_calls, type: :array
-
-    compute :routing_summary, with: %i[extension_id telephony_status] do |extension_id:, telephony_status:|
-      {
-        extension_id: extension_id,
-        telephony_status: telephony_status,
-        ignored_status: true
-      }
-    end
-
-    output :routing_summary
-  end
-end
-
-class RingcentralWebhookContract < Igniter::Contract
-  define do
-    input :payload
-
-    scope :parse do
-      project :body, from: :payload, key: :body, default: {}
-      project :telephony_status, from: :body, key: "telephonyStatus"
-      project :extension_id, from: :body, key: "extensionId"
-      project :active_calls, from: :body, key: "activeCalls", default: []
-    end
-
-    branch :status_route,
-      with: :telephony_status,
-      depends_on: %i[extension_id active_calls],
-      map_inputs: lambda { |selector:, extension_id:, active_calls:|
-        {
-          extension_id: extension_id,
-          telephony_status: selector,
-          active_calls: active_calls
-        }
-      } do
-      on "CallConnected", contract: CallConnectedContract
-      on "NoCall", contract: NoCallContract
-      on "Ringing", contract: RingingContract
-      default contract: UnknownStatusContract
-    end
-
-    export :routing_summary, from: :status_route
-    output :status_route
-  end
-end
-
-payload = {
-  "body" => {
-    "extensionId" => 62872332031,
-    "telephonyStatus" => "CallConnected",
-    "activeCalls" => [
-      {
-        "from" => "+18009066027",
-        "to" => "+16199627154",
-        "direction" => "Outbound",
-        "startTime" => "2024-04-01T16:18:13.553Z",
-        "telephonySessionId" => "s-outbound-1"
-      },
-      {
-        "from" => "+13125550100",
-        "to" => "+18009066027",
-        "direction" => "Inbound",
-        "startTime" => "2024-04-01T16:19:10.000Z",
-        "telephonySessionId" => "s-inbound-2"
-      },
-      {
-        "from" => "+13125550199",
-        "to" => "+18009066027",
-        "direction" => "Parked",
-        "startTime" => "2024-04-01T16:20:00.000Z",
-        "telephonySessionId" => "s-unknown-3"
-      }
-    ]
-  }
-}
-
-contract = RingcentralWebhookContract.new(payload: payload)
-
-puts contract.explain_plan
-puts "---"
-puts "routing_summary=#{contract.result.routing_summary.inspect}"
-puts "status_route_branch=#{contract.events.find { |event| event.type == :branch_selected }.payload[:matched_case]}"
-puts "child_collection_summary=#{contract.result.status_route.calls.summary.inspect}"
-puts "child_diagnostics_status=#{contract.result.status_route.execution.diagnostics.to_h[:status]}"
-pp contract.result.status_route.calls.as_json

data/examples/saga.rb

@@ -1,110 +0,0 @@
-# frozen_string_literal: true
-
-# Saga Pattern — compensating transactions for Igniter contracts.
-#
-# When a step fails mid-execution, the saga system automatically runs
-# compensating actions for all previously completed steps in reverse order.
-#
-# Run: ruby examples/saga.rb
-
-$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
-require "igniter"
-require "igniter/extensions/saga"
-require "igniter/extensions/execution_report"
-
-# ── Contracts ─────────────────────────────────────────────────────────────────
-
-class OrderWorkflow < Igniter::Contract
-  define do
-    input :order_id, type: :string
-    input :amount,   type: :numeric
-
-    compute :reserve_stock, depends_on: :order_id do |order_id:|
-      puts "  [forward] reserve_stock for order #{order_id}"
-      { reservation_id: "rsv-#{order_id}" }
-    end
-
-    compute :charge_card, depends_on: %i[order_id amount reserve_stock] do |order_id:, amount:, **|
-      puts "  [forward] charge_card: $#{amount}"
-      raise "Card declined: amount $#{amount} exceeds limit" if amount > 500
-
-      { charge_id: "chg-#{order_id}", amount: amount }
-    end
-
-    compute :send_confirmation, depends_on: %i[reserve_stock charge_card] do |charge_card:, **|
-      puts "  [forward] send_confirmation for charge #{charge_card[:charge_id]}"
-      { sent: true }
-    end
-
-    output :reserve_stock
-    output :charge_card
-    output :send_confirmation
-  end
-
-  compensate :charge_card do |_inputs:, value:|
-    puts "  [compensate] refunding charge #{value[:charge_id]}"
-  end
-
-  compensate :reserve_stock do |_inputs:, value:|
-    puts "  [compensate] releasing reservation #{value[:reservation_id]}"
-  end
-end
-
-puts "=== Saga Demo ==="
-puts
-
-# ── 1. Successful saga ─────────────────────────────────────────────────────────
-
-puts "--- 1. Successful execution (amount=$100) ---"
-result_ok = OrderWorkflow.new(order_id: "ord-001", amount: 100.0).resolve_saga
-puts result_ok.explain
-puts
-
-# ── 2. Failed saga — compensations triggered ───────────────────────────────────
-
-puts "--- 2. Failed execution (amount=$999 — exceeds limit) ---"
-result_fail = OrderWorkflow.new(order_id: "ord-002", amount: 999.0).resolve_saga
-puts result_fail.explain
-puts
-
-# ── 3. Result query API ────────────────────────────────────────────────────────
-
-puts "--- 3. Result query API ---"
-puts "success?          = #{result_fail.success?}"
-puts "failed_node       = #{result_fail.failed_node.inspect}"
-puts "error             = #{result_fail.error.message}"
-puts "compensations_ran = #{result_fail.compensations.map(&:node_name).inspect}"
-puts "all compensations ok? #{result_fail.compensations.all?(&:success?)}"
-puts
-
-# ── 4. Execution report ────────────────────────────────────────────────────────
-
-puts "--- 4. execution_report (after failed saga) ---"
-failed_contract = OrderWorkflow.new(order_id: "ord-003", amount: 999.0)
-begin
-  failed_contract.resolve_all
-rescue Igniter::Error
-  nil
-end
-puts failed_contract.execution_report.explain
-puts
-
-# ── 5. Execution report on successful contract ────────────────────────────────
-
-puts "--- 5. execution_report (successful) ---"
-ok_contract = OrderWorkflow.new(order_id: "ord-004", amount: 50.0)
-ok_contract.resolve_all
-puts ok_contract.execution_report.explain
-puts
-
-# ── 6. to_h / structured output ───────────────────────────────────────────────
-
-puts "--- 6. result.to_h ---"
-h = result_fail.to_h
-puts "success:       #{h[:success]}"
-puts "failed_node:   #{h[:failed_node].inspect}"
-puts "error:         #{h[:error]}"
-puts "compensations: #{h[:compensations].map { |c| [c[:node], c[:success]] }.inspect}"
-puts
-
-puts "done=true"