igniter 0.2.0

data/lib/igniter/diagnostics/report.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Diagnostics
+    class Report
+      def initialize(execution)
+        @execution = execution
+      end
+
+      def to_h
+        safely_resolve_execution
+
+        {
+          graph: execution.compiled_graph.name,
+          execution_id: execution.events.execution_id,
+          status: status,
+          outputs: serialize_outputs,
+          errors: serialize_errors,
+          nodes: summarize_nodes,
+          events: summarize_events
+        }
+      end
+
+      def as_json(*)
+        to_h
+      end
+
+      def to_text
+        report = to_h
+        lines = []
+        lines << "Diagnostics #{report[:graph]}"
+        lines << "Execution #{report[:execution_id]}"
+        lines << "Status: #{report[:status]}"
+        lines << format_outputs(report[:outputs])
+        lines << format_nodes(report[:nodes])
+        lines << format_errors(report[:errors])
+        lines << format_events(report[:events])
+        lines.compact.join("\n")
+      end
+
+      def to_markdown
+        report = to_h
+        lines = []
+        lines << "# Diagnostics #{report[:graph]}"
+        lines << ""
+        lines << "- Execution: `#{report[:execution_id]}`"
+        lines << "- Status: `#{report[:status]}`"
+        lines << "- Outputs: #{inline_hash(report[:outputs])}"
+        lines << "- Nodes: total=#{report[:nodes][:total]}, succeeded=#{report[:nodes][:succeeded]}, failed=#{report[:nodes][:failed]}, stale=#{report[:nodes][:stale]}"
+        lines << "- Events: total=#{report[:events][:total]}, latest=#{report[:events][:latest_type] || 'none'}"
+
+        unless report[:errors].empty?
+          lines << ""
+          lines << "## Errors"
+          report[:errors].each do |error|
+            lines << "- `#{error[:node_name]}`: #{error[:message]}"
+          end
+        end
+
+        lines.join("\n")
+      end
+
+      private
+
+      attr_reader :execution
+
+      def execution_result
+        @execution_result ||= Runtime::Result.new(execution)
+      end
+
+      def safely_resolve_execution
+        execution.resolve_all
+      rescue Igniter::Error
+        nil
+      end
+
+      def status
+        return :failed if execution.cache.values.any?(&:failed?)
+        return :stale if execution.cache.values.any?(&:stale?)
+
+        :succeeded
+      end
+
+      def serialize_errors
+        execution_result.errors.map do |node_name, error|
+          {
+            node_name: node_name,
+            type: error.class.name,
+            message: error.message,
+            context: error.respond_to?(:context) ? error.context : {}
+          }
+        end
+      end
+
+      def serialize_outputs
+        execution.compiled_graph.outputs.each_with_object({}) do |output_node, memo|
+          state = execution.cache.fetch(output_node.source)
+          memo[output_node.name] = serialize_output_state(state)
+        end
+      end
+
+      def serialize_output_state(state)
+        return nil unless state
+        return { error: state.error.message, status: state.status } if state.failed?
+
+        serialize_value(state.value)
+      end
+
+      def summarize_nodes
+        states = execution.states
+
+        {
+          total: states.size,
+          succeeded: states.values.count { |state| state[:status] == :succeeded },
+          failed: states.values.count { |state| state[:status] == :failed },
+          stale: states.values.count { |state| state[:status] == :stale },
+          failed_nodes: states.filter_map do |node_name, state|
+            next unless state[:status] == :failed
+
+            { node_name: node_name, path: state[:path], error: state[:error] }
+          end
+        }
+      end
+
+      def summarize_events
+        events = execution.events.events
+
+        {
+          total: events.size,
+          latest_type: events.last&.type,
+          latest_at: events.last&.timestamp,
+          by_type: events.each_with_object(Hash.new(0)) { |event, memo| memo[event.type] += 1 }
+        }
+      end
+
+      def format_outputs(outputs)
+        "Outputs: #{inline_hash(outputs)}"
+      end
+
+      def format_nodes(nodes)
+        line = "Nodes: total=#{nodes[:total]}, succeeded=#{nodes[:succeeded]}, failed=#{nodes[:failed]}, stale=#{nodes[:stale]}"
+        return line if nodes[:failed_nodes].empty?
+
+        failures = nodes[:failed_nodes].map { |node| "#{node[:node_name]}(#{node[:error]})" }.join(", ")
+        "#{line}\nFailed Nodes: #{failures}"
+      end
+
+      def format_errors(errors)
+        return "Errors: none" if errors.empty?
+
+        "Errors: #{errors.map { |error| "#{error[:node_name]}=#{error[:type]}" }.join(', ')}"
+      end
+
+      def format_events(events)
+        "Events: total=#{events[:total]}, latest=#{events[:latest_type] || 'none'}"
+      end
+
+      def inline_hash(hash)
+        hash.map { |key, value| "#{key}=#{value.inspect}" }.join(", ")
+      end
+
+      def serialize_value(value)
+        case value
+        when Runtime::Result
+          value.to_h
+        when Array
+          value.map { |item| serialize_value(item) }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/igniter/diagnostics.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "diagnostics/report"
+
+module Igniter
+  module Diagnostics
+  end
+end

data/lib/igniter/dsl/contract_builder.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Igniter
+  module DSL
+    class ContractBuilder
+      def self.compile(name: "AnonymousContract", &block)
+        new(name: name).tap { |builder| builder.instance_eval(&block) }.compile
+      end
+
+      def initialize(name:)
+        @name = name
+        @nodes = []
+        @sequence = 0
+      end
+
+      UNDEFINED_INPUT_DEFAULT = :__igniter_undefined__
+
+      def input(name, type: nil, required: nil, default: UNDEFINED_INPUT_DEFAULT, **metadata)
+        input_metadata = with_source_location(metadata)
+        input_metadata[:type] = type if type
+        input_metadata[:required] = required unless required.nil?
+        input_metadata[:default] = default unless default == UNDEFINED_INPUT_DEFAULT
+
+        add_node(
+          Model::InputNode.new(
+            id: next_id,
+            name: name,
+            metadata: input_metadata
+          )
+        )
+      end
+
+      def compute(name, depends_on:, call: nil, **metadata, &block)
+        callable = call || 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),
+            callable: callable,
+            metadata: with_source_location(metadata)
+          )
+        )
+      end
+
+      def output(name, from: nil, **metadata)
+        add_node(
+          Model::OutputNode.new(
+            id: next_id,
+            name: name,
+            source: (from || name),
+            metadata: with_source_location(metadata)
+          )
+        )
+      end
+
+      def compose(name, contract:, inputs:, **metadata)
+        raise CompileError, "compose :#{name} requires an `inputs:` hash" unless inputs.is_a?(Hash)
+
+        add_node(
+          Model::CompositionNode.new(
+            id: next_id,
+            name: name,
+            contract_class: contract,
+            input_mapping: inputs,
+            metadata: with_source_location(metadata)
+          )
+        )
+      end
+
+      def compile
+        Compiler::GraphCompiler.call(Model::Graph.new(name: @name, nodes: @nodes))
+      end
+
+      private
+
+      def add_node(node)
+        @nodes << node
+        node
+      end
+
+      def next_id
+        @sequence += 1
+        "#{@name}:#{@sequence}"
+      end
+
+      def with_source_location(metadata)
+        metadata.merge(source_location: caller_locations(2, 1).first&.to_s)
+      end
+    end
+  end
+end

data/lib/igniter/dsl.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "dsl/contract_builder"
+
+module Igniter
+  module DSL
+  end
+end

data/lib/igniter/errors.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Igniter
+  class Error < StandardError
+    attr_reader :context
+
+    def initialize(message = nil, context: {})
+      @context = context.compact.freeze
+      super(format_message(message, @context))
+    end
+
+    def graph
+      context[:graph]
+    end
+
+    def node_id
+      context[:node_id]
+    end
+
+    def node_name
+      context[:node_name]
+    end
+
+    def node_path
+      context[:node_path]
+    end
+
+    def source_location
+      context[:source_location]
+    end
+
+    private
+
+    def format_message(message, context)
+      details = []
+      details << "graph=#{context[:graph]}" if context[:graph]
+      details << "node=#{context[:node_name]}" if context[:node_name]
+      details << "path=#{context[:node_path]}" if context[:node_path]
+      details << "location=#{context[:source_location]}" if context[:source_location]
+
+      return message if details.empty?
+
+      "#{message} [#{details.join(', ')}]"
+    end
+  end
+
+  class CompileError < Error; end
+  class ValidationError < CompileError; end
+  class CycleError < ValidationError; end
+  class InputError < Error; end
+  class ResolutionError < Error; end
+  class CompositionError < Error; end
+end

data/lib/igniter/events/bus.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Igniter
+  module Events
+    class Bus
+      attr_reader :execution_id, :events
+
+      def initialize(execution_id: SecureRandom.uuid)
+        @execution_id = execution_id
+        @events = []
+        @subscribers = []
+      end
+
+      def emit(type, node: nil, status: nil, payload: {})
+        event = Event.new(
+          event_id: SecureRandom.uuid,
+          type: type,
+          execution_id: execution_id,
+          node_id: node&.id,
+          node_name: node&.name,
+          path: node&.path,
+          status: status,
+          payload: payload,
+          timestamp: Time.now.utc
+        )
+
+        @events << event
+        @subscribers.each { |subscriber| subscriber.call(event) }
+        event
+      end
+
+      def subscribe(subscriber = nil, &block)
+        @subscribers << (subscriber || block)
+      end
+    end
+  end
+end

data/lib/igniter/events/event.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Igniter
+  module Events
+    Event = Struct.new(
+      :event_id,
+      :type,
+      :execution_id,
+      :node_id,
+      :node_name,
+      :path,
+      :status,
+      :payload,
+      :timestamp,
+      keyword_init: true
+    ) do
+      def to_h
+        {
+          event_id: event_id,
+          type: type,
+          execution_id: execution_id,
+          node_id: node_id,
+          node_name: node_name,
+          path: path,
+          status: status,
+          payload: payload,
+          timestamp: timestamp
+        }
+      end
+
+      def as_json(*)
+        to_h.transform_values { |value| serialize_value(value) }
+      end
+
+      private
+
+      def serialize_value(value)
+        case value
+        when Time
+          value.iso8601
+        when Hash
+          value.each_with_object({}) { |(key, nested_value), memo| memo[key] = serialize_value(nested_value) }
+        when Array
+          value.map { |item| serialize_value(item) }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/igniter/events.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "events/event"
+require_relative "events/bus"
+
+module Igniter
+  module Events
+  end
+end

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

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

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

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

@@ -0,0 +1,73 @@
+# 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 == :composition
+              line += " contract=#{node.contract_class.name || 'AnonymousContract'}"
+            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))} --> #{output_id(output)})
+          end
+          @graph.nodes.each do |node|
+            node.dependencies.each do |dependency_name|
+              dependency_node = @graph.fetch_node(dependency_name)
+              lines << %(  #{node_id(dependency_node)} --> #{node_id(node)})
+            end
+          end
+          lines.join("\n")
+        end
+
+        private
+
+        def node_id(node)
+          "node_#{node.name}"
+        end
+
+        def output_id(output)
+          "output_#{output.name}"
+        end
+
+        def node_label(node)
+          "#{node.kind}: #{node.name}"
+        end
+      end
+    end
+  end
+end