igniter 0.5.0 → 0.5.2

data/lib/igniter/extensions/introspection/runtime_formatter.rb

@@ -1,117 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Extensions
-    module Introspection
-      class RuntimeFormatter
-        def self.states(execution)
-          new(execution).states
-        end
-
-        def self.explain_output(execution, output_name)
-          new(execution).explain_output(output_name)
-        end
-
-        def initialize(execution)
-          @execution = execution
-        end
-
-        def states
-          @execution.cache.to_h.each_with_object({}) do |(node_name, state), memo|
-            memo[node_name] = serialize_state(state)
-          end
-        end
-
-        def explain_output(output_name)
-          output = @execution.compiled_graph.fetch_output(output_name)
-          source = @execution.compiled_graph.fetch_node(output.source_root)
-
-          explanation = {
-            output_id: output.id,
-            output: output.name,
-            path: output.path,
-            source_id: source.id,
-            source: source.name,
-            source_path: source.path,
-            dependencies: dependency_tree(source)
-          }
-
-          if output.composition_output?
-            explanation[:child_output] = output.child_output_name
-            explanation[:child_output_path] = output.source.to_s
-          end
-
-          explanation
-        end
-
-        private
-
-        def dependency_tree(node)
-          state = @execution.cache.fetch(node.name)
-          {
-            id: node.id,
-            name: node.name,
-            path: node.path,
-            kind: node.kind,
-            source_location: node.source_location,
-            status: state&.status,
-            invalidated_by: invalidation_details(state),
-            value: serialize_value(state&.value),
-            error: state&.error&.message,
-            dependencies: node.dependencies.map do |dependency_name|
-              dependency_tree(@execution.compiled_graph.fetch_dependency(dependency_name))
-            end
-          }
-        end
-
-        def serialize_state(state)
-          {
-            id: state.node.id,
-            path: state.node.path,
-            kind: state.node.kind,
-            source_location: state.node.source_location,
-            status: state.status,
-            version: state.version,
-            invalidated_by: invalidation_details(state),
-            value: serialize_value(state.value),
-            error: state.error&.message
-          }
-        end
-
-        def invalidation_details(state)
-          return nil unless state&.invalidated_by
-
-          invalidating_node = @execution.compiled_graph.fetch_node(state.invalidated_by)
-          {
-            node_id: invalidating_node.id,
-            node_name: invalidating_node.name,
-            node_path: invalidating_node.path
-          }
-        end
-
-        def serialize_value(value)
-          case value
-          when Igniter::Runtime::DeferredResult
-            {
-              type: :deferred,
-              token: value.token,
-              payload: value.payload,
-              source_node: value.source_node,
-              waiting_on: value.waiting_on
-            }
-          when Igniter::Runtime::Result
-            {
-              type: :result,
-              graph: value.execution.compiled_graph.name,
-              execution_id: value.execution.events.execution_id
-            }
-          when Array
-            value.map { |item| serialize_value(item) }
-          else
-            value
-          end
-        end
-      end
-    end
-  end
-end

data/lib/igniter/extensions/introspection.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "introspection/graph_formatter"
-require_relative "introspection/plan_formatter"
-require_relative "introspection/runtime_formatter"
-
-module Igniter
-  module Extensions
-    module Introspection
-    end
-  end
-end

data/lib/igniter/extensions/invariants.rb

@@ -1,116 +0,0 @@
-# frozen_string_literal: true
-
-require "igniter"
-require "igniter/invariant"
-
-module Igniter
-  module Extensions
-    # Patches Igniter::Contract with:
-    #   - Class method: invariant(name) { |output:, **| condition }
-    #   - Instance method: check_invariants → Array<InvariantViolation>
-    #   - Automatic post-execution check in resolve_all (raises InvariantError)
-    #
-    # Invariant blocks receive ONLY the contract's declared output values as
-    # keyword args — the stable public interface, independent of internal nodes.
-    # Use ** to absorb outputs you don't need.
-    #
-    # @example
-    #   class PricingContract < Igniter::Contract
-    #     define do
-    #       input  :price
-    #       input  :quantity
-    #       compute :total, depends_on: %i[price quantity] do |price:, quantity:|
-    #         price * quantity
-    #       end
-    #       output :total
-    #     end
-    #
-    #     invariant(:total_non_negative) { |total:, **| total >= 0 }
-    #   end
-    #
-    # This module is applied globally via:
-    #   Igniter::Contract.include(Igniter::Extensions::Invariants)
-    #
-    module Invariants
-      def self.included(base)
-        base.extend(ClassMethods)
-        base.prepend(InstanceMethods)
-      end
-
-      # ── Class-level DSL ──────────────────────────────────────────────────────
-
-      module ClassMethods
-        # Declare a condition that must always hold after successful execution.
-        #
-        # The block receives the contract's declared output values as keyword
-        # arguments; use ** to absorb outputs you don't care about. Return a
-        # truthy value to indicate the invariant holds, falsy to indicate
-        # a violation.
-        #
-        # @example
-        #   invariant(:positive_total) { |total:, **| total >= 0 }
-        #
-        # @param name [Symbol]
-        def invariant(name, &block)
-          @_invariants ||= {}
-          @_invariants[name.to_sym] = Igniter::Invariant.new(name, &block)
-        end
-
-        # @return [Hash{Symbol => Igniter::Invariant}]
-        def invariants
-          @_invariants || {}
-        end
-      end
-
-      # ── Instance override + new public method ───────────────────────────────
-
-      module InstanceMethods
-        # Intercepts resolve_all to run invariant checks after execution.
-        # Uses a thread-local flag so that property testing can disable the
-        # automatic raise and collect violations as data instead.
-        def resolve_all(...)
-          result = super
-          validate_invariants! unless Thread.current[:igniter_skip_invariants]
-          result
-        end
-
-        # Run all invariants without raising. Returns violations as data.
-        # Safe to call at any time after execution.
-        #
-        # @return [Array<Igniter::InvariantViolation>]
-        def check_invariants
-          return [] if self.class.invariants.empty?
-
-          resolved = collect_output_values
-          self.class.invariants.values.filter_map { |inv| inv.check(resolved) }
-        end
-
-        private
-
-        def validate_invariants!
-          violations = check_invariants
-          return if violations.empty?
-
-          names = violations.map { |v| ":#{v.name}" }.join(", ")
-          raise Igniter::InvariantError.new(
-            "#{violations.size} invariant(s) violated: #{names}",
-            violations: violations,
-            context: { contract: self.class.name }
-          )
-        end
-
-        # Collect all declared output values from the resolved cache.
-        # Keyed by output name (not source node name).
-        def collect_output_values
-          cache = execution.cache
-          execution.compiled_graph.outputs.each_with_object({}) do |output_node, acc|
-            state = cache.fetch(output_node.source_root)
-            acc[output_node.name] = state.value if state&.succeeded?
-          end
-        end
-      end
-    end
-  end
-end
-
-Igniter::Contract.include(Igniter::Extensions::Invariants)

data/lib/igniter/extensions/mesh.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-# Igniter Mesh — Phase 1 (Static) + Phase 2 (Dynamic Discovery)
-#
-# Extends the remote: DSL with capability-based and pinned routing modes, and
-# enables dynamic peer discovery so that the peer topology can be maintained
-# without static add_peer declarations.
-#
-# Usage:
-#   require "igniter/extensions/mesh"
-#
-#   # Phase 1 — static topology (still works):
-#   Igniter::Mesh.configure do |c|
-#     c.add_peer "orders-node",
-#                url: "http://orders.internal:4567",
-#                capabilities: [:orders, :inventory]
-#   end
-#
-#   # Phase 2 — dynamic discovery:
-#   Igniter::Mesh.configure do |c|
-#     c.peer_name          = "api-node"
-#     c.local_url          = "http://api.internal:4567"
-#     c.local_capabilities = [:api]
-#     c.seeds              = %w[http://orders.internal:4567 http://audit.internal:4567]
-#     c.discovery_interval = 30
-#   end
-#   Igniter::Mesh.start_discovery!
-#
-require "igniter"
-require "igniter/server"
-require "igniter/mesh"

data/lib/igniter/extensions/provenance.rb

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../provenance"
-
-module Igniter
-  module Extensions
-    # Adds runtime provenance (data lineage) methods to Igniter::Contract.
-    #
-    # After requiring this file, every resolved contract gains two new methods:
-    #
-    #   contract.resolve_all
-    #
-    #   # Full Lineage object — query API
-    #   lin = contract.lineage(:grand_total)
-    #   lin.contributing_inputs        # => { base_price: 100.0, quantity: 2 }
-    #   lin.sensitive_to?(:base_price) # => true
-    #   lin.path_to(:base_price)       # => [:grand_total, :subtotal, :base_price]
-    #   lin.to_h                        # serialisable Hash
-    #
-    #   # Shorthand: human-readable ASCII tree printed to stdout
-    #   contract.explain(:grand_total)
-    #
-    module Provenance
-      # Return a Lineage object for the named output.
-      # Raises ProvenanceError if the output is unknown or the contract has not
-      # been executed (resolve_all has not been called).
-      def lineage(output_name)
-        unless execution
-          raise Igniter::Provenance::ProvenanceError,
-                "Contract has not been executed — call resolve_all first"
-        end
-
-        Igniter::Provenance::Builder.build(output_name, execution)
-      end
-
-      # Return a human-readable ASCII tree explaining how +output_name+ was derived.
-      def explain(output_name)
-        lineage(output_name).explain
-      end
-    end
-  end
-end
-
-# Patch Igniter::Contract so every contract instance gains the methods.
-Igniter::Contract.include(Igniter::Extensions::Provenance)

data/lib/igniter/extensions/reactive/engine.rb

@@ -1,83 +0,0 @@
-# frozen_string_literal: true
-
-require "set"
-
-module Igniter
-  module Extensions
-    module Reactive
-      class Engine
-        attr_reader :execution, :contract, :reactions, :errors
-
-        def initialize(execution:, contract:, reactions:)
-          @execution = execution
-          @contract = contract
-          @reactions = reactions
-          @errors = []
-          @fired_reactions = Set.new
-        end
-
-        def call(event)
-          reactions.each do |reaction|
-            next unless Matcher.new(reaction, event).match?
-            next if already_fired?(reaction, event)
-
-            mark_fired(reaction, event)
-            call_action(
-              reaction.action,
-              event: event,
-              contract: contract,
-              execution: execution,
-              value: value_for(event)
-            )
-          rescue StandardError => e
-            @errors << {
-              event: event,
-              reaction: reaction,
-              error: e
-            }
-          end
-        end
-
-        private
-
-        def call_action(action, **kwargs)
-          parameters = action.parameters
-          accepts_any_keywords = parameters.any? { |kind, _name| kind == :keyrest }
-
-          if accepts_any_keywords
-            action.call(**kwargs)
-            return
-          end
-
-          accepted_keywords = parameters.select { |kind, _name| %i[key keyreq].include?(kind) }.map(&:last)
-          filtered_kwargs = kwargs.slice(*accepted_keywords)
-          action.call(**filtered_kwargs)
-        end
-
-        def value_for(event)
-          return nil unless %i[node_succeeded node_resumed node_pending].include?(event.type)
-          return nil unless event.node_name
-
-          state = execution.cache.fetch(event.node_name)
-          state&.value
-        end
-
-        def already_fired?(reaction, event)
-          return false unless reaction.once_per_execution
-
-          @fired_reactions.include?(reaction_key(reaction, event))
-        end
-
-        def mark_fired(reaction, event)
-          return unless reaction.once_per_execution
-
-          @fired_reactions << reaction_key(reaction, event)
-        end
-
-        def reaction_key(reaction, event)
-          [reaction.object_id, event.execution_id]
-        end
-      end
-    end
-  end
-end

data/lib/igniter/extensions/reactive/matcher.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Extensions
-    module Reactive
-      class Matcher
-        def initialize(reaction, event)
-          @reaction = reaction
-          @event = event
-        end
-
-        def match?
-          return false unless @reaction.event_type == @event.type
-          return true unless @reaction.path
-
-          @reaction.path == @event.path
-        end
-      end
-    end
-  end
-end

data/lib/igniter/extensions/reactive/reaction.rb

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Extensions
-    module Reactive
-      class Reaction
-        attr_reader :event_type, :path, :action, :once_per_execution
-
-        def initialize(event_type:, path: nil, action:, once_per_execution: false)
-          @event_type = event_type.to_sym
-          @path = path&.to_s
-          @action = action
-          @once_per_execution = once_per_execution
-        end
-      end
-    end
-  end
-end

data/lib/igniter/extensions/reactive.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "reactive/reaction"
-require_relative "reactive/matcher"
-require_relative "reactive/engine"
-
-module Igniter
-  module Extensions
-    module Reactive
-    end
-  end
-end

data/lib/igniter/extensions/saga.rb

@@ -1,74 +0,0 @@
-# frozen_string_literal: true
-
-require "igniter"
-require "igniter/saga"
-
-module Igniter
-  module Extensions
-    # Adds saga/compensating-transaction support to all Igniter contracts.
-    #
-    # Class-level DSL:
-    #   compensate :node_name do |inputs:, value:| ... end
-    #
-    # Instance methods added:
-    #   resolve_saga → Igniter::Saga::Result
-    #
-    # Applied globally via:
-    #   Igniter::Contract.include(Igniter::Extensions::Saga)
-    #
-    module Saga
-      def self.included(base)
-        base.extend(ClassMethods)
-      end
-
-      # ── Class-level DSL ────────────────────────────────────────────────────
-
-      module ClassMethods
-        # Declare a compensating action for a compute node.
-        #
-        # The block is called with:
-        #   inputs: — Hash of the node's dependency values
-        #   value:  — the value the node produced (now being rolled back)
-        #
-        # @param node_name [Symbol]
-        def compensate(node_name, &block)
-          @_compensations ||= {}
-          @_compensations[node_name.to_sym] = Igniter::Saga::Compensation.new(node_name, &block)
-        end
-
-        # @return [Hash{ Symbol => Compensation }]
-        def compensations
-          @_compensations || {}
-        end
-      end
-
-      # ── Instance methods ───────────────────────────────────────────────────
-
-      # Execute the contract and handle compensations on failure.
-      #
-      # Unlike `resolve_all` (which raises on failure), `resolve_saga`:
-      #   - Returns a successful Result when execution completes
-      #   - Catches Igniter::Error, runs compensations, returns a failed Result
-      #
-      # @return [Igniter::Saga::Result]
-      def resolve_saga # rubocop:disable Metrics/MethodLength
-        resolve_all
-        Igniter::Saga::Result.new(success: true, contract: self)
-      rescue Igniter::Error => e
-        executor = Igniter::Saga::Executor.new(self)
-        compensations_ran = executor.run_compensations
-        failed_node = executor.failed_node_name
-
-        Igniter::Saga::Result.new(
-          success: false,
-          contract: self,
-          error: e,
-          failed_node: failed_node,
-          compensations: compensations_ran
-        )
-      end
-    end
-  end
-end
-
-Igniter::Contract.include(Igniter::Extensions::Saga)

data/lib/igniter/extensions.rb

@@ -1,10 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "extensions/auditing"
-require_relative "extensions/reactive"
-require_relative "extensions/introspection"
-
-module Igniter
-  module Extensions
-  end
-end

data/lib/igniter/fingerprint.rb

@@ -1,43 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  # Mixin that enables stable cross-execution cache keys for objects used as
-  # compute node dependencies (e.g. ActiveRecord models).
-  #
-  # Include this module in any class whose instances are passed as node deps:
-  #
-  #   class Trade < ApplicationRecord
-  #     include Igniter::Fingerprint
-  #   end
-  #
-  # The Rails Railtie includes this automatically in ApplicationRecord when
-  # the igniter-rails integration is loaded.
-  #
-  # == Custom fingerprints
-  #
-  # Override #igniter_fingerprint for non-AR objects or custom invalidation logic:
-  #
-  #   class PricingConfig
-  #     include Igniter::Fingerprint
-  #
-  #     def igniter_fingerprint
-  #       "PricingConfig:#{version}:#{market}"
-  #     end
-  #   end
-  module Fingerprint
-    # Returns a stable string that uniquely identifies this object's state.
-    # Changing the returned value invalidates any NodeCache entry that depends on it.
-    #
-    # Default: "{ClassName}:{id}:{updated_at_unix}" — works for any AR record.
-    # Returns "{ClassName}:{id}" for objects without updated_at.
-    def igniter_fingerprint
-      if respond_to?(:updated_at) && updated_at
-        "#{self.class.name}:#{id}:#{updated_at.to_i}"
-      elsif respond_to?(:id)
-        "#{self.class.name}:#{id}"
-      else
-        "#{self.class.name}:#{object_id}"
-      end
-    end
-  end
-end

data/lib/igniter/incremental/formatter.rb

@@ -1,81 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Incremental
-    # Renders an Incremental::Result as a human-readable text block.
-    #
-    # Example output:
-    #
-    #   Incremental Execution Report
-    #   ─────────────────────────────────────────
-    #   Recomputed:  1 node(s)
-    #   Skipped:     2 node(s)  (deps unchanged)
-    #   Backdated:   0 node(s)  (value unchanged)
-    #
-    #   CHANGED OUTPUTS (1):
-    #     :converted_price  1.05 → 1.12
-    #
-    #   SKIPPED NODES (memoized):
-    #     :tier_discount  :adjusted_price
-    #
-    module Formatter
-      VALUE_MAX = 60
-      LINE = "─" * 42
-
-      class << self
-        def format(result) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-          lines = []
-          lines << "Incremental Execution Report"
-          lines << LINE
-          lines << "Recomputed:  #{result.recomputed_count} node(s)"
-          lines << "Skipped:     #{result.skipped_nodes.size} node(s)  (deps unchanged)"
-          lines << "Backdated:   #{result.backdated_nodes.size} node(s)  (value unchanged)"
-          lines << ""
-
-          if result.changed_outputs.any?
-            lines << "CHANGED OUTPUTS (#{result.changed_outputs.size}):"
-            result.changed_outputs.each do |name, diff|
-              lines << "  :#{name}  #{fmt(diff[:from])} → #{fmt(diff[:to])}"
-            end
-          else
-            lines << "No output values changed."
-          end
-          lines << ""
-
-          if result.skipped_nodes.any?
-            lines << "SKIPPED (memoized, #{result.skipped_nodes.size}):"
-            lines << "  #{result.skipped_nodes.map { |n| ":#{n}" }.join("  ")}"
-            lines << ""
-          end
-
-          if result.backdated_nodes.any?
-            lines << "BACKDATED (recomputed → same value, #{result.backdated_nodes.size}):"
-            lines << "  #{result.backdated_nodes.map { |n| ":#{n}" }.join("  ")}"
-            lines << ""
-          end
-
-          if result.changed_nodes.any?
-            lines << "CHANGED (#{result.changed_nodes.size}):"
-            lines << "  #{result.changed_nodes.map { |n| ":#{n}" }.join("  ")}"
-          end
-
-          lines.join("\n")
-        end
-
-        private
-
-        def fmt(value) # rubocop:disable Metrics/CyclomaticComplexity
-          str = case value
-                when nil    then "nil"
-                when String then value.inspect
-                when Symbol then value.inspect
-                when Hash   then "{#{value.map { |k, v| "#{k}: #{v.inspect}" }.join(", ")}}"
-                when Array  then "[#{value.map(&:inspect).join(", ")}]"
-                else             value.inspect
-                end
-          str.length > VALUE_MAX ? "#{str[0, VALUE_MAX - 3]}..." : str
-        end
-      end
-    end
-  end
-end