igniter 0.2.0 → 0.3.0

data/lib/igniter/dsl/contract_builder.rb

@@ -11,9 +11,12 @@ module Igniter
         @name = name
         @nodes = []
         @sequence = 0
+        @scope_stack = []
       end
 
       UNDEFINED_INPUT_DEFAULT = :__igniter_undefined__
+      UNDEFINED_CONST_VALUE = :__igniter_const_undefined__
+      UNDEFINED_GUARD_MATCHER = :__igniter_guard_matcher_undefined__
 
       def input(name, type: nil, required: nil, default: UNDEFINED_INPUT_DEFAULT, **metadata)
         input_metadata = with_source_location(metadata)
@@ -25,33 +28,114 @@ module Igniter
           Model::InputNode.new(
             id: next_id,
             name: name,
+            path: scoped_path(name),
             metadata: input_metadata
           )
         )
       end
 
-      def compute(name, depends_on:, call: nil, **metadata, &block)
-        callable = call || block
+      def compute(name, depends_on: nil, with: nil, call: nil, executor: nil, **metadata, &block)
+        callable, resolved_metadata = resolve_compute_callable(call: call, executor: executor, metadata: metadata, block: block)
         raise CompileError, "compute :#{name} requires a callable" unless callable
-        raise CompileError, "compute :#{name} cannot accept both `call:` and a block" if call && block
 
         add_node(
           Model::ComputeNode.new(
             id: next_id,
             name: name,
-            dependencies: Array(depends_on),
+            dependencies: normalize_dependencies(depends_on: depends_on, with: with),
             callable: callable,
-            metadata: with_source_location(metadata)
+            path: scoped_path(name),
+            metadata: with_source_location(resolved_metadata)
           )
         )
       end
 
+      def const(name, value = UNDEFINED_CONST_VALUE, **metadata, &block)
+        raise CompileError, "const :#{name} cannot accept both a value and a block" if !block.nil? && value != UNDEFINED_CONST_VALUE
+        raise CompileError, "const :#{name} requires a value or a block" if block.nil? && value == UNDEFINED_CONST_VALUE
+
+        callable = if block
+                     block
+                   else
+                     proc { value }
+                   end
+
+        compute(name, with: [], call: callable, **metadata.merge(kind: :const))
+      end
+
+      def lookup(name, depends_on: nil, with: nil, call: nil, executor: nil, **metadata, &block)
+        compute(name, depends_on: depends_on, with: with, call: call, executor: executor, **{ category: :lookup }.merge(metadata), &block)
+      end
+
+      def map(name, from:, call: nil, executor: nil, **metadata, &block)
+        compute(name, with: from, call: call, executor: executor, **{ category: :map }.merge(metadata), &block)
+      end
+
+      def guard(name, depends_on: nil, with: nil, call: nil, executor: nil, message: nil,
+                eq: UNDEFINED_GUARD_MATCHER, in: UNDEFINED_GUARD_MATCHER, matches: UNDEFINED_GUARD_MATCHER,
+                **metadata, &block)
+        matcher_options = {
+          eq: eq,
+          in: binding.local_variable_get(:in),
+          matches: matches
+        }.reject { |_key, value| value == UNDEFINED_GUARD_MATCHER }
+
+        if matcher_options.any?
+          raise CompileError, "guard :#{name} cannot combine matcher options with `call:`, `executor:`, or a block" if call || executor || block
+          raise CompileError, "guard :#{name} supports only one matcher option at a time" if matcher_options.size > 1
+
+          dependencies = normalize_dependencies(depends_on: depends_on, with: with)
+          raise CompileError, "guard :#{name} with matcher options requires exactly one dependency" unless dependencies.size == 1
+
+          dependency = dependencies.first
+          matcher_name, matcher_value = matcher_options.first
+
+          call = build_guard_matcher(matcher_name, matcher_value, dependency)
+        end
+
+        compute(
+          name,
+          depends_on: depends_on,
+          with: with,
+          call: call,
+          executor: executor,
+          **metadata.merge(kind: :guard, guard: true, guard_message: message || "Guard '#{name}' failed"),
+          &block
+        )
+      end
+
+      def export(*names, from:, **metadata)
+        names.each do |name|
+          output(name, from: "#{from}.#{name}", **metadata)
+        end
+      end
+
+      def expose(*sources, as: nil, **metadata)
+        raise CompileError, "expose cannot use `as:` with multiple sources" if as && sources.size != 1
+
+        sources.each do |source|
+          output(as || source, from: source, **metadata)
+        end
+      end
+
+      def scope(name, &block)
+        raise CompileError, "scope requires a block" unless block
+
+        @scope_stack << name.to_s
+        instance_eval(&block)
+      ensure
+        @scope_stack.pop
+      end
+
+      alias namespace scope
+
       def output(name, from: nil, **metadata)
         add_node(
           Model::OutputNode.new(
             id: next_id,
             name: name,
             source: (from || name),
+            path: scoped_output_path(name),
             metadata: with_source_location(metadata)
           )
         )
@@ -66,6 +150,42 @@ module Igniter
             name: name,
             contract_class: contract,
             input_mapping: inputs,
+            path: scoped_path(name),
+            metadata: with_source_location(metadata)
+          )
+        )
+      end
+
+      def branch(name, with:, inputs:, **metadata, &block)
+        raise CompileError, "branch :#{name} requires a block" unless block
+        raise CompileError, "branch :#{name} requires an `inputs:` hash" unless inputs.is_a?(Hash)
+
+        definition = BranchBuilder.build(&block)
+
+        add_node(
+          Model::BranchNode.new(
+            id: next_id,
+            name: name,
+            selector_dependency: with,
+            cases: definition[:cases],
+            default_contract: definition[:default_contract],
+            input_mapping: inputs,
+            path: scoped_path(name),
+            metadata: with_source_location(metadata)
+          )
+        )
+      end
+
+      def collection(name, with:, each:, key:, mode: :collect, **metadata)
+        add_node(
+          Model::CollectionNode.new(
+            id: next_id,
+            name: name,
+            source_dependency: with,
+            contract_class: each,
+            key_name: key,
+            mode: mode,
+            path: scoped_path(name),
             metadata: with_source_location(metadata)
           )
         )
@@ -90,6 +210,89 @@ module Igniter
       def with_source_location(metadata)
         metadata.merge(source_location: caller_locations(2, 1).first&.to_s)
       end
+
+      def resolve_compute_callable(call:, executor:, metadata:, block:)
+        raise CompileError, "compute cannot accept both `call:` and `executor:`" if call && executor
+        raise CompileError, "compute cannot accept both `call:` and a block" if call && block
+        raise CompileError, "compute cannot accept both `executor:` and a block" if executor && block
+
+        if executor
+          definition = Igniter.executor_registry.fetch(executor)
+          return [definition.executor_class, definition.metadata.merge(metadata).merge(executor_key: definition.key)]
+        end
+
+        [call || block, metadata]
+      end
+
+      def normalize_dependencies(depends_on:, with:)
+        raise CompileError, "Use either `depends_on:` or `with:`, not both" if depends_on && with
+
+        dependencies = depends_on || with
+        Array(dependencies)
+      end
+
+      def build_guard_matcher(matcher_name, matcher_value, dependency)
+        case matcher_name
+        when :eq
+          proc do |**values|
+            values.fetch(dependency) == matcher_value
+          end
+        when :in
+          allowed_values = Array(matcher_value)
+          proc do |**values|
+            allowed_values.include?(values.fetch(dependency))
+          end
+        when :matches
+          matcher = matcher_value
+          raise CompileError, "`matches:` expects a Regexp" unless matcher.is_a?(Regexp)
+
+          proc do |**values|
+            values.fetch(dependency).to_s.match?(matcher)
+          end
+        else
+          raise CompileError, "Unsupported guard matcher: #{matcher_name}"
+        end
+      end
+
+      def scoped_path(name)
+        return name.to_s if @scope_stack.empty?
+
+        "#{@scope_stack.join('.')}.#{name}"
+      end
+
+      def scoped_output_path(name)
+        return "output.#{name}" if @scope_stack.empty?
+
+        "#{@scope_stack.join('.')}.output.#{name}"
+      end
+
+      class BranchBuilder
+        def self.build(&block)
+          new.tap { |builder| builder.instance_eval(&block) }.to_h
+        end
+
+        def initialize
+          @cases = []
+          @default_contract = nil
+        end
+
+        def on(match, contract:)
+          @cases << { match: match, contract: contract }
+        end
+
+        def default(contract:)
+          raise CompileError, "branch can define only one `default`" if @default_contract
+
+          @default_contract = contract
+        end
+
+        def to_h
+          {
+            cases: @cases,
+            default_contract: @default_contract
+          }
+        end
+      end
     end
   end
 end

data/lib/igniter/dsl/schema_builder.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Igniter
+  module DSL
+    class SchemaBuilder
+      def self.compile(schema, name: nil)
+        new(schema, name: name).compile
+      end
+
+      def initialize(schema, name: nil)
+        @schema = symbolize(schema)
+        @name = name || @schema[:name] || "AnonymousContract"
+      end
+
+      def compile
+        schema = @schema
+
+        ContractBuilder.compile(name: @name) do
+          Array(schema[:inputs]).each do |input_config|
+            config = input_config
+            input(
+              config.fetch(:name),
+              type: config[:type],
+              required: config[:required],
+              default: config.fetch(:default, ContractBuilder::UNDEFINED_INPUT_DEFAULT),
+              **config.fetch(:metadata, {})
+            )
+          end
+
+          Array(schema[:compositions]).each do |composition_config|
+            config = composition_config
+            compose(
+              config.fetch(:name),
+              contract: config.fetch(:contract),
+              inputs: config.fetch(:inputs),
+              **config.fetch(:metadata, {})
+            )
+          end
+
+          Array(schema[:computes]).each do |compute_config|
+            config = compute_config
+            options = {
+              depends_on: Array(config.fetch(:depends_on)).map(&:to_sym)
+            }
+            options[:call] = config[:call] if config.key?(:call)
+            options[:executor] = config[:executor] if config.key?(:executor)
+            compute(config.fetch(:name), **options, **config.fetch(:metadata, {}))
+          end
+
+          Array(schema[:outputs]).each do |output_config|
+            config = output_config
+            output(config.fetch(:name), from: config[:from], **config.fetch(:metadata, {}))
+          end
+        end
+      end
+
+      private
+
+      def symbolize(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, nested), memo|
+            memo[key.to_sym] = symbolize(nested)
+          end
+        when Array
+          value.map { |item| symbolize(item) }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/igniter/dsl.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "dsl/contract_builder"
+require_relative "dsl/schema_builder"
 
 module Igniter
   module DSL

data/lib/igniter/errors.rb

@@ -48,6 +48,17 @@ module Igniter
   class ValidationError < CompileError; end
   class CycleError < ValidationError; end
   class InputError < Error; end
+  class CollectionInputError < Error; end
+  class CollectionKeyError < Error; end
   class ResolutionError < Error; end
   class CompositionError < Error; end
+  class BranchSelectionError < Error; end
+  class PendingDependencyError < Error
+    attr_reader :deferred_result
+
+    def initialize(deferred_result, message = "Dependency is pending", context: {})
+      @deferred_result = deferred_result
+      super(message, context: context)
+    end
+  end
 end

data/lib/igniter/events/bus.rb

@@ -34,6 +34,11 @@ module Igniter
       def subscribe(subscriber = nil, &block)
         @subscribers << (subscriber || block)
       end
+
+      def restore!(events:, execution_id: nil)
+        @execution_id = execution_id if execution_id
+        @events = Array(events).map { |event| event.is_a?(Event) ? event : Event.from_h(event) }
+      end
     end
   end
 end

data/lib/igniter/events/event.rb

@@ -16,6 +16,20 @@ module Igniter
       :timestamp,
       keyword_init: true
     ) do
+      def self.from_h(data)
+        new(
+          event_id: value_from(data, :event_id),
+          type: value_from(data, :type).to_sym,
+          execution_id: value_from(data, :execution_id),
+          node_id: value_from(data, :node_id),
+          node_name: value_from(data, :node_name)&.to_sym,
+          path: value_from(data, :path),
+          status: value_from(data, :status)&.to_sym,
+          payload: value_from(data, :payload) || {},
+          timestamp: parse_timestamp(value_from(data, :timestamp))
+        )
+      end
+
       def to_h
         {
           event_id: event_id,
@@ -36,6 +50,21 @@ module Igniter
 
       private
 
+      def self.parse_timestamp(value)
+        case value
+        when Time
+          value
+        when String
+          Time.iso8601(value)
+        else
+          value
+        end
+      end
+
+      def self.value_from(data, key)
+        data[key] || data[key.to_s]
+      end
+
       def serialize_value(value)
         case value
         when Time

data/lib/igniter/executor.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Igniter
+  class Executor
+    class << self
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@executor_inputs, executor_inputs.transform_values(&:dup))
+        subclass.instance_variable_set(:@executor_metadata, executor_metadata.dup)
+      end
+
+      def input(name, required: true, type: nil, **metadata)
+        executor_inputs[name.to_sym] = metadata.merge(required: required, type: type).compact
+      end
+
+      def executor_inputs
+        @executor_inputs ||= {}
+      end
+
+      def executor_metadata
+        @executor_metadata ||= {}
+      end
+
+      def executor_key(value = nil)
+        metadata_value(:key, value)
+      end
+
+      def label(value = nil)
+        metadata_value(:label, value)
+      end
+
+      def category(value = nil)
+        metadata_value(:category, value)
+      end
+
+      def summary(value = nil)
+        metadata_value(:summary, value)
+      end
+
+      def tags(*values)
+        return Array(executor_metadata[:tags]).freeze if values.empty?
+
+        executor_metadata[:tags] = values.flatten.compact.map(&:to_sym).freeze
+      end
+
+      def output_schema(value = nil)
+        metadata_value(:output_schema, value)
+      end
+
+      def call(**dependencies)
+        new.call(**dependencies)
+      end
+
+      private
+
+      def metadata_value(key, value)
+        return executor_metadata[key] if value.nil?
+
+        executor_metadata[key] = value
+      end
+    end
+
+    attr_reader :execution, :contract
+
+    def initialize(execution: nil, contract: nil)
+      @execution = execution
+      @contract = contract
+    end
+
+    def defer(token: nil, payload: {})
+      Runtime::DeferredResult.build(token: token, payload: payload)
+    end
+  end
+end

data/lib/igniter/executor_registry.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Igniter
+  class ExecutorRegistry
+    Definition = Struct.new(:key, :executor_class, :metadata, keyword_init: true)
+
+    def initialize
+      @definitions = {}
+    end
+
+    def register(key, executor_class, **metadata)
+      normalized_key = key.to_s
+      raise CompileError, "executor registry key cannot be empty" if normalized_key.empty?
+
+      unless executor_class.is_a?(Class) && executor_class <= Igniter::Executor
+        raise CompileError, "Executor registry key '#{normalized_key}' must reference an Igniter::Executor subclass"
+      end
+
+      @definitions[normalized_key] = Definition.new(
+        key: normalized_key,
+        executor_class: executor_class,
+        metadata: executor_class.executor_metadata.merge(metadata).merge(key: normalized_key)
+      )
+    end
+
+    def fetch(key)
+      @definitions.fetch(key.to_s)
+    rescue KeyError
+      raise CompileError, "Unknown executor registry key: #{key}"
+    end
+
+    def registered?(key)
+      @definitions.key?(key.to_s)
+    end
+
+    def definitions
+      @definitions.values.sort_by(&:key)
+    end
+
+    def clear
+      @definitions.clear
+    end
+  end
+end

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

@@ -19,6 +19,10 @@ module Igniter
           @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,

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

@@ -23,9 +23,31 @@ module Igniter
           @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 += " cases=#{cases.join('|')}"
+              line += " default=#{node.default_contract.name || 'AnonymousContract'}"
+            end
+            if node.kind == :collection
+              line += " with=#{node.source_dependency}"
+              line += " each=#{node.contract_class.name || 'AnonymousContract'}"
+              line += " key=#{node.key_name}"
+              line += " mode=#{node.mode}"
+            end
             lines << line
           end
           lines << "Outputs:"
@@ -43,11 +65,11 @@ module Igniter
           end
           @graph.outputs.each do |output|
             lines << %(  #{output_id(output)}["output: #{output.name}"])
-            lines << %(  #{node_id(@graph.fetch_node(output.source))} --> #{output_id(output)})
+            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_node(dependency_name)
+              dependency_node = @graph.fetch_dependency(dependency_name)
               lines << %(  #{node_id(dependency_node)} --> #{node_id(node)})
             end
           end
@@ -57,6 +79,8 @@ module Igniter
         private
 
         def node_id(node)
+          return "output_#{node.name}" if node.kind == :output
+
           "node_#{node.name}"
         end
 
@@ -65,7 +89,9 @@ module Igniter
         end
 
         def node_label(node)
-          "#{node.kind}: #{node.name}"
+          return "#{node.kind}: #{node.path}" unless node.kind == :compute
+
+          "#{node.kind}: #{node.path}\\n#{node.callable_name}"
         end
       end
     end

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

@@ -0,0 +1,55 @@
+# 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