igniter 0.5.0 → 0.5.2

data/lib/igniter/extensions/auditing/timeline.rb

@@ -1,103 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Extensions
-    module Auditing
-      class Timeline
-        attr_reader :execution
-
-        def initialize(execution)
-          @execution = execution
-          @events = []
-        end
-
-        def call(event)
-          @events << event
-        end
-
-        def events
-          @events.dup
-        end
-
-        def restore!(events)
-          @events = Array(events).map { |event| event.is_a?(Igniter::Events::Event) ? event : Igniter::Events::Event.from_h(event) }
-        end
-
-        def snapshot
-          {
-            execution_id: execution.events.execution_id,
-            graph: execution.compiled_graph.name,
-            event_count: @events.size,
-            events: @events.map { |event| serialize_event(event) },
-            states: serialize_states,
-            children: child_snapshots
-          }
-        end
-
-        private
-
-        def serialize_event(event)
-          {
-            event_id: event.event_id,
-            type: event.type,
-            execution_id: event.execution_id,
-            node_id: event.node_id,
-            node_name: event.node_name,
-            path: event.path,
-            status: event.status,
-            payload: serialize_payload(event.payload),
-            timestamp: event.timestamp
-          }
-        end
-
-        def serialize_states
-          execution.cache.to_h.each_with_object({}) do |(node_name, state), memo|
-            memo[node_name] = {
-              path: state.node.path,
-              kind: state.node.kind,
-              status: state.status,
-              version: state.version,
-              invalidated_by: state.invalidated_by,
-              resolved_at: state.resolved_at,
-              value: serialize_value(state.value),
-              error: state.error&.message
-            }
-          end
-        end
-
-        def child_snapshots
-          execution.cache.values.filter_map do |state|
-            next unless state.value.is_a?(Igniter::Runtime::Result)
-
-            {
-              node_name: state.node.name,
-              path: state.node.path,
-              snapshot: state.value.execution.audit.snapshot
-            }
-          end
-        end
-
-        def serialize_payload(payload)
-          payload.each_with_object({}) do |(key, value), memo|
-            memo[key] = serialize_value(value)
-          end
-        end
-
-        def serialize_value(value)
-          case value
-          when Igniter::Runtime::Result
-            {
-              type: :result,
-              execution_id: value.execution.events.execution_id,
-              graph: value.execution.compiled_graph.name
-            }
-          when Array
-            value.map { |item| serialize_value(item) }
-          else
-            value
-          end
-        end
-      end
-    end
-  end
-end

data/lib/igniter/extensions/auditing.rb

@@ -1,10 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "auditing/timeline"
-
-module Igniter
-  module Extensions
-    module Auditing
-    end
-  end
-end

data/lib/igniter/extensions/capabilities.rb

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-require "igniter/capabilities"
-
-# Patches CompiledGraph with capability introspection methods.
-# The Resolver integration is handled via guard-claused hooks in resolver.rb.
-module Igniter
-  module Compiler
-    class CompiledGraph
-      # Returns a Hash of { node_name => [capabilities] } for every compute/effect
-      # node whose executor declares at least one capability.
-      def required_capabilities
-        (nodes + outputs).each_with_object({}) do |node, memo|
-          caps = node_capabilities(node)
-          memo[node.name] = caps unless caps.empty?
-        end
-      end
-
-      # Returns declared capabilities for a single node by name.
-      def capabilities_for(node_name)
-        sym    = node_name.to_sym
-        target = (nodes + outputs).find { |n| n.name == sym }
-        return [] unless target
-
-        node_capabilities(target)
-      end
-
-      private
-
-      def node_capabilities(node)
-        callable = node.respond_to?(:callable) ? node.callable : nil
-        callable ||= node.respond_to?(:adapter_class) ? node.adapter_class : nil
-        return [] unless callable.is_a?(Class) && callable <= Igniter::Executor
-
-        callable.declared_capabilities
-      end
-    end
-  end
-end

data/lib/igniter/extensions/content_addressing.rb

@@ -1,5 +0,0 @@
-# frozen_string_literal: true
-
-# Loading this file activates content-addressed caching for pure executors.
-# The Resolver picks up content addressing via a guard clause when this constant is defined.
-require "igniter/content_addressing"

data/lib/igniter/extensions/dataflow.rb

@@ -1,117 +0,0 @@
-# frozen_string_literal: true
-
-require "igniter"
-require "igniter/dataflow"
-
-# Activates incremental dataflow support for all contracts.
-#
-# After requiring this file:
-#
-#   - `collection` DSL accepts `mode: :incremental` and `window:` options.
-#   - Contracts gain `#feed_diff` — push event-style diffs instead of full arrays.
-#   - Contracts gain `#collection_diff` — inspect what changed after the last resolve.
-#
-# == Usage
-#
-#   require "igniter/extensions/dataflow"
-#
-#   class SensorPipeline < Igniter::Contract
-#     define do
-#       input :readings, type: :array
-#
-#       collection :processed,
-#                  with: :readings,
-#                  each: SensorContract,
-#                  key: :sensor_id,
-#                  mode: :incremental,
-#                  window: { last: 500 }
-#
-#       output :processed
-#     end
-#   end
-#
-#   contract = SensorPipeline.new(readings: initial_readings)
-#   contract.resolve_all
-#
-#   # Push new events without replacing the full array
-#   contract.feed_diff(:readings, add: [new_reading], remove: [:sensor_old])
-#   contract.resolve_all
-#
-#   # Inspect what changed
-#   diff = contract.collection_diff(:processed)
-#   diff.added     # => [:sensor_42]
-#   diff.removed   # => [:sensor_old]
-#   diff.changed   # => []
-#   diff.unchanged # => [:sensor_1, :sensor_2, ...]
-#
-module Igniter
-  module Extensions
-    module Dataflow
-      module InstanceMethods
-        # Push a diff to a collection input without replacing the full array.
-        #
-        # Automatically finds the incremental collection node that uses +input_name+
-        # as its source dependency, uses its key_name to merge the diff into the
-        # current input array, then calls update_inputs.
-        #
-        # @param input_name [Symbol, String]  the contract input holding the collection
-        # @param add        [Array<Hash>]     new items to append
-        # @param remove     [Array]           keys or Hash items to remove (matched by key_name)
-        # @param update     [Array<Hash>]     updated versions of existing items (replace by key)
-        # @return [self]
-        #
-        # @raise [ArgumentError] if no incremental collection node uses the given input
-        def feed_diff(input_name, add: [], remove: [], update: [])
-          sym      = input_name.to_sym
-          key_name = _incremental_node_for(sym).key_name
-          current  = execution.inputs[sym].dup || []
-          items    = _apply_diff(current, key_name, add: add, remove: remove, update: update)
-          execution.update_inputs(sym => items)
-          self
-        end
-
-        # Returns the Diff from the last resolve for a named collection node.
-        #
-        # @param collection_name [Symbol, String]  the collection node name
-        # @return [Igniter::Dataflow::Diff, nil]  nil if not yet resolved or not incremental
-        def collection_diff(collection_name)
-          state = execution.cache.fetch(collection_name.to_sym)
-          value = state&.value
-          value.respond_to?(:diff) ? value.diff : nil
-        end
-
-        private
-
-        def _apply_diff(items, key_name, add:, remove:, update:)
-          remove_keys = Array(remove).map { |e| e.is_a?(Hash) ? e.fetch(key_name) : e }.to_set
-          result = items.reject { |item| remove_keys.include?(item.fetch(key_name)) }
-          _apply_updates(result, key_name, update)
-          result.concat(Array(add))
-        end
-
-        def _apply_updates(items, key_name, updates)
-          Array(updates).each do |updated|
-            k   = updated.fetch(key_name)
-            idx = items.index { |item| item.fetch(key_name) == k }
-            idx ? items[idx] = updated : items << updated
-          end
-        end
-
-        def _incremental_node_for(input_name)
-          node = execution.compiled_graph.nodes.find do |n|
-            n.kind == :collection &&
-              n.mode == :incremental &&
-              n.source_dependency == input_name
-          end
-          return node if node
-
-          raise ArgumentError,
-                "No incremental collection node found for input '#{input_name}'. " \
-                "Ensure the collection is declared with mode: :incremental."
-        end
-      end
-    end
-  end
-end
-
-Igniter::Contract.include(Igniter::Extensions::Dataflow::InstanceMethods)

data/lib/igniter/extensions/differential.rb

@@ -1,114 +0,0 @@
-# frozen_string_literal: true
-
-require "igniter"
-require "igniter/differential"
-
-module Igniter
-  module Extensions
-    # Patches Igniter::Contract with:
-    #   - Class method: shadow_with(candidate, async:, on_divergence:, tolerance:)
-    #   - Instance method: diff_against(candidate_class, tolerance:)
-    #   - Automatic shadow execution after resolve_all (when shadow_with is declared)
-    #
-    # This module is applied globally via:
-    #   Igniter::Contract.include(Igniter::Extensions::Differential)
-    #
-    module Differential
-      def self.included(base)
-        base.extend(ClassMethods)
-        base.prepend(InstanceMethods)
-      end
-
-      # ── Class-level DSL ────────────────────────────────────────────────────
-
-      module ClassMethods
-        # Declare a shadow candidate that runs alongside every resolve_all call.
-        #
-        # @param candidate_class [Class<Igniter::Contract>]
-        # @param async [Boolean]  run the shadow in a background Thread
-        # @param on_divergence [#call, nil] invoked with a Report when outputs differ
-        # @param tolerance [Numeric, nil]  passed to the differential runner
-        def shadow_with(candidate_class, async: false, on_divergence: nil, tolerance: nil)
-          @_shadow_candidate = candidate_class
-          @_shadow_async = async
-          @_shadow_on_divergence = on_divergence
-          @_shadow_tolerance = tolerance
-        end
-
-        def shadow_candidate = @_shadow_candidate
-        def shadow_async? = @_shadow_async || false
-        def shadow_on_divergence = @_shadow_on_divergence
-        def shadow_tolerance = @_shadow_tolerance
-      end
-
-      # ── Instance override + new public method ─────────────────────────────
-
-      module InstanceMethods
-        # Intercepts resolve_all to trigger shadow execution when shadow_with
-        # has been declared.  Uses a thread-local flag to prevent recursive
-        # shadow calls when the runner itself invokes resolve_all internally.
-        def resolve_all(...)
-          result = super
-          run_shadow unless Thread.current[:igniter_skip_shadow]
-          result
-        end
-
-        # Compare the already-executed primary contract against +candidate_class+.
-        # Avoids re-running the primary (reads outputs from the existing cache).
-        #
-        # Raises DifferentialError if resolve_all has not been called yet.
-        #
-        # @return [Igniter::Differential::Report]
-        def diff_against(candidate_class, tolerance: nil)
-          unless execution.cache.values.any?
-            raise Igniter::Differential::DifferentialError,
-                  "Contract has not been executed — call resolve_all first"
-          end
-
-          inputs = extract_inputs_from_execution
-          runner = Igniter::Differential::Runner.new(self.class, candidate_class, tolerance: tolerance)
-          runner.run_with_primary_execution(execution, inputs)
-        end
-
-        private
-
-        def run_shadow # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-          candidate = self.class.shadow_candidate
-          return unless candidate
-
-          on_divergence = self.class.shadow_on_divergence
-          tolerance = self.class.shadow_tolerance
-          inputs = extract_inputs_from_execution
-
-          task = lambda do
-            runner = Igniter::Differential::Runner.new(self.class, candidate, tolerance: tolerance)
-            report = runner.run_with_primary_execution(execution, inputs)
-            on_divergence.call(report) if on_divergence && !report.match?
-          end
-
-          if self.class.shadow_async?
-            Thread.new { task.call }
-          else
-            task.call
-          end
-        end
-
-        # Reads input node values from the resolved cache for re-use in
-        # secondary executions (shadow / diff_against).
-        def extract_inputs_from_execution
-          graph = execution.compiled_graph
-          cache = execution.cache
-
-          graph.nodes.each_with_object({}) do |node, acc|
-            next unless node.kind == :input
-
-            state = cache.fetch(node.name)
-            acc[node.name] = state&.value
-          end
-        end
-      end
-    end
-  end
-end
-
-Igniter::Contract.include(Igniter::Extensions::Differential)

data/lib/igniter/extensions/execution_report.rb

@@ -1,27 +0,0 @@
-# frozen_string_literal: true
-
-require "igniter"
-require "igniter/execution_report"
-
-module Igniter
-  module Extensions
-    # Adds execution_report method to all Igniter contracts.
-    #
-    # Applied globally via:
-    #   Igniter::Contract.include(Igniter::Extensions::ExecutionReport)
-    #
-    module ExecutionReport
-      # Build a structured execution report from the current execution state.
-      #
-      # Can be called after resolve_all succeeds OR after it raises — in both
-      # cases the cache contains partial or full execution state.
-      #
-      # @return [Igniter::ExecutionReport::Report]
-      def execution_report
-        Igniter::ExecutionReport::Builder.build(self)
-      end
-    end
-  end
-end
-
-Igniter::Contract.include(Igniter::Extensions::ExecutionReport)

data/lib/igniter/extensions/incremental.rb

@@ -1,50 +0,0 @@
-# frozen_string_literal: true
-
-require "igniter"
-require "igniter/incremental"
-
-module Igniter
-  module Extensions
-    # Patches Igniter::Contract with:
-    #   - Instance method: resolve_incrementally(new_inputs = {}) → Incremental::Result
-    #
-    # The method updates inputs, re-resolves, and returns a structured report
-    # of which nodes changed, were memoized, or were backdated.
-    #
-    # Applied globally via:
-    #   Igniter::Contract.include(Igniter::Extensions::Incremental)
-    #
-    module Incremental
-      def self.included(base)
-        base.include(InstanceMethods)
-      end
-
-      module InstanceMethods
-        # Update inputs and re-resolve, returning a detailed incremental result.
-        #
-        # If called without arguments on an already-resolved contract, it
-        # re-resolves with current inputs (useful for observing memoization).
-        #
-        # @param new_inputs [Hash] input values to update before re-resolving
-        # @return [Igniter::Incremental::Result]
-        def resolve_incrementally(new_inputs = {})
-          unless execution.cache.values.any?
-            raise Igniter::Incremental::IncrementalError,
-                  "Contract has not been executed yet — call resolve_all first, " \
-                  "then resolve_incrementally to get incremental results"
-          end
-
-          tracker = Igniter::Incremental::Tracker.new(execution)
-          tracker.start!
-
-          update_inputs(new_inputs) if new_inputs.any?
-          resolve_all
-
-          tracker.build_result
-        end
-      end
-    end
-  end
-end
-
-Igniter::Contract.include(Igniter::Extensions::Incremental)

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

@@ -1,103 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Extensions
-    module Introspection
-      class GraphFormatter
-        def self.to_text(graph)
-          new(graph).to_text
-        end
-
-        def self.to_mermaid(graph)
-          new(graph).to_mermaid
-        end
-
-        def initialize(graph)
-          @graph = graph
-        end
-
-        def to_text
-          lines = []
-          lines << "Graph #{@graph.name}"
-          lines << "Nodes:"
-          @graph.nodes.each do |node|
-            line = "- #{node.kind} #{node.path}"
-            line += " depends_on=#{node.dependencies.join(',')}" if node.dependencies.any?
-            if node.kind == :compute
-              line += " callable=#{node.callable_name}"
-              line += " guard=true" if node.guard?
-              line += " const=true" if node.const?
-              line += " executor_key=#{node.executor_key}" if node.executor_key
-              line += " label=#{node.executor_label}" if node.executor_label
-              line += " category=#{node.executor_category}" if node.executor_category
-              line += " tags=#{node.executor_tags.join(',')}" if node.executor_tags.any?
-              line += " summary=#{node.executor_summary}" if node.executor_summary
-            end
-            if node.kind == :composition
-              line += " contract=#{node.contract_class.name || 'AnonymousContract'}"
-            end
-            if node.kind == :branch
-              cases = node.cases.map { |entry| "#{entry[:match].inspect}:#{entry[:contract].name || 'AnonymousContract'}" }
-              line += " selector=#{node.selector_dependency}"
-              line += " depends_on=#{node.context_dependencies.join(',')}" if node.context_dependencies.any?
-              line += " cases=#{cases.join('|')}"
-              line += " default=#{node.default_contract.name || 'AnonymousContract'}"
-              line += " mapper=#{node.input_mapper}" if node.input_mapper?
-            end
-            if node.kind == :collection
-              line += " with=#{node.source_dependency}"
-              line += " depends_on=#{node.context_dependencies.join(',')}" if node.context_dependencies.any?
-              line += " each=#{node.contract_class.name || 'AnonymousContract'}"
-              line += " key=#{node.key_name}"
-              line += " mode=#{node.mode}"
-              line += " mapper=#{node.input_mapper}" if node.input_mapper?
-            end
-            lines << line
-          end
-          lines << "Outputs:"
-          @graph.outputs.each do |output|
-            lines << "- #{output.path} -> #{output.source}"
-          end
-          lines.join("\n")
-        end
-
-        def to_mermaid
-          lines = []
-          lines << "graph TD"
-          @graph.nodes.each do |node|
-            lines << %(  #{node_id(node)}["#{node_label(node)}"])
-          end
-          @graph.outputs.each do |output|
-            lines << %(  #{output_id(output)}["output: #{output.name}"])
-            lines << %(  #{node_id(@graph.fetch_node(output.source_root))} --> #{output_id(output)})
-          end
-          @graph.nodes.each do |node|
-            node.dependencies.each do |dependency_name|
-              dependency_node = @graph.fetch_dependency(dependency_name)
-              lines << %(  #{node_id(dependency_node)} --> #{node_id(node)})
-            end
-          end
-          lines.join("\n")
-        end
-
-        private
-
-        def node_id(node)
-          return "output_#{node.name}" if node.kind == :output
-
-          "node_#{node.name}"
-        end
-
-        def output_id(output)
-          "output_#{output.name}"
-        end
-
-        def node_label(node)
-          return "#{node.kind}: #{node.path}" unless node.kind == :compute
-
-          "#{node.kind}: #{node.path}\\n#{node.callable_name}"
-        end
-      end
-    end
-  end
-end

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

@@ -1,55 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Extensions
-    module Introspection
-      class PlanFormatter
-        def self.to_text(execution, output_names = nil)
-          new(execution, output_names).to_text
-        end
-
-        def initialize(execution, output_names = nil)
-          @execution = execution
-          @plan = execution.plan(output_names)
-        end
-
-        def to_text
-          lines = []
-          lines << "Plan #{@execution.compiled_graph.name}"
-          lines << "Targets: #{format_list(@plan[:targets])}"
-          lines << "Ready: #{format_list(@plan[:ready])}"
-          lines << "Blocked: #{format_list(@plan[:blocked])}"
-          lines << "Nodes:"
-
-          @plan[:nodes].each_value do |entry|
-            lines << format_node(entry)
-          end
-
-          lines.join("\n")
-        end
-
-        private
-
-        def format_node(entry)
-          line = "- #{entry[:kind]} #{entry[:path]} status=#{entry[:status]}"
-          line += " ready=true" if entry[:ready]
-          line += " blocked=true" if entry[:blocked]
-          line += " waiting_on=#{format_list(entry[:waiting_on])}" if entry[:waiting_on].any?
-
-          dependency_summary = entry[:dependencies].map do |dependency|
-            "#{dependency[:name]}(#{dependency[:status]})"
-          end
-          line += " deps=#{dependency_summary.join(',')}" if dependency_summary.any?
-          line
-        end
-
-        def format_list(values)
-          array = Array(values)
-          return "none" if array.empty?
-
-          array.join(",")
-        end
-      end
-    end
-  end
-end