igniter 0.2.0

data/examples/basic_pricing.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "igniter"
+
+class PriceContract < Igniter::Contract
+  define do
+    input :order_total, type: :numeric
+    input :country, type: :string
+
+    compute :vat_rate, depends_on: [:country] do |country:|
+      country == "UA" ? 0.2 : 0.0
+    end
+
+    compute :gross_total, depends_on: %i[order_total vat_rate] do |order_total:, vat_rate:|
+      order_total * (1 + vat_rate)
+    end
+
+    output :gross_total
+  end
+end
+
+contract = PriceContract.new(order_total: 100, country: "UA")
+
+puts "gross_total=#{contract.result.gross_total}"
+contract.update_inputs(order_total: 150)
+puts "updated_gross_total=#{contract.result.gross_total}"

data/examples/composition.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "igniter"
+
+class PriceContract < Igniter::Contract
+  define do
+    input :order_total, type: :numeric
+    input :country, type: :string
+
+    compute :vat_rate, depends_on: [:country] do |country:|
+      country == "UA" ? 0.2 : 0.0
+    end
+
+    compute :gross_total, depends_on: %i[order_total vat_rate] do |order_total:, vat_rate:|
+      order_total * (1 + vat_rate)
+    end
+
+    output :gross_total
+  end
+end
+
+class CheckoutContract < Igniter::Contract
+  define do
+    input :order_total, type: :numeric
+    input :country, type: :string
+
+    compose :pricing, contract: PriceContract, inputs: {
+      order_total: :order_total,
+      country: :country
+    }
+
+    output :pricing
+  end
+end
+
+contract = CheckoutContract.new(order_total: 100, country: "UA")
+
+puts "pricing=#{contract.result.to_h.inspect}"

data/examples/diagnostics.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "igniter"
+
+class PriceContract < Igniter::Contract
+  define do
+    input :order_total, type: :numeric
+    input :country, type: :string
+
+    compute :vat_rate, depends_on: [:country] do |country:|
+      country == "UA" ? 0.2 : 0.0
+    end
+
+    compute :gross_total, depends_on: %i[order_total vat_rate] do |order_total:, vat_rate:|
+      order_total * (1 + vat_rate)
+    end
+
+    output :gross_total
+  end
+end
+
+contract = PriceContract.new(order_total: 100, country: "UA")
+contract.result.gross_total
+
+puts contract.diagnostics_text
+puts "---"
+puts contract.result.as_json.inspect

data/lib/igniter/compiler/compiled_graph.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Compiler
+    class CompiledGraph
+      attr_reader :name, :nodes, :nodes_by_id, :nodes_by_name, :nodes_by_path, :outputs, :outputs_by_name, :resolution_order, :dependents
+
+      def initialize(name:, nodes:, outputs:, resolution_order:, dependents:)
+        @name = name
+        @nodes = nodes.freeze
+        @nodes_by_id = nodes.each_with_object({}) { |node, memo| memo[node.id] = node }.freeze
+        @nodes_by_name = nodes.each_with_object({}) { |node, memo| memo[node.name] = node }.freeze
+        @nodes_by_path = nodes.each_with_object({}) { |node, memo| memo[node.path] = node }.freeze
+        @outputs = outputs.freeze
+        @outputs_by_name = outputs.each_with_object({}) { |node, memo| memo[node.name] = node }.freeze
+        @resolution_order = resolution_order.freeze
+        @dependents = dependents.transform_values(&:freeze).freeze
+        freeze
+      end
+
+      def fetch_node_by_id(id)
+        @nodes_by_id.fetch(id)
+      end
+
+      def fetch_node(name)
+        @nodes_by_name.fetch(name.to_sym)
+      end
+
+      def node?(name)
+        @nodes_by_name.key?(name.to_sym)
+      end
+
+      def fetch_node_by_path(path)
+        @nodes_by_path.fetch(path.to_s)
+      end
+
+      def fetch_output(name)
+        @outputs_by_name.fetch(name.to_sym)
+      end
+
+      def to_h
+        {
+          name: name,
+          nodes: nodes.map do |node|
+            base = {
+              id: node.id,
+              kind: node.kind,
+              name: node.name,
+              path: node.path,
+              dependencies: node.dependencies
+            }
+            if node.kind == :composition
+              base[:contract] = node.contract_class.name
+              base[:inputs] = node.input_mapping
+            end
+            base
+          end,
+          outputs: outputs.map do |output|
+            {
+              name: output.name,
+              path: output.path,
+              source: output.source
+            }
+          end,
+          resolution_order: resolution_order.map(&:name)
+        }
+      end
+
+      def to_text
+        Extensions::Introspection::GraphFormatter.to_text(self)
+      end
+
+      def to_mermaid
+        Extensions::Introspection::GraphFormatter.to_mermaid(self)
+      end
+    end
+  end
+end

data/lib/igniter/compiler/graph_compiler.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "tsort"
+
+module Igniter
+  module Compiler
+    class GraphCompiler
+      include TSort
+
+      def self.call(graph)
+        new(graph).call
+      end
+
+      def initialize(graph)
+        @graph = graph
+      end
+
+      def call
+        validator = Validator.call(@graph)
+        @nodes_by_name = validator.runtime_nodes_by_name
+
+        CompiledGraph.new(
+          name: @graph.name,
+          nodes: validator.runtime_nodes,
+          outputs: validator.outputs,
+          resolution_order: tsort,
+          dependents: build_dependents
+        )
+      end
+
+      private
+
+      def runtime_nodes
+        @runtime_nodes ||= @graph.nodes.reject { |node| node.kind == :output }
+      end
+
+      def build_dependents
+        runtime_nodes.each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |node, memo|
+          node.dependencies.each { |dependency_name| memo[dependency_name] << node.name }
+        end
+      end
+
+      def tsort_each_node(&block)
+        runtime_nodes.each(&block)
+      end
+
+      def tsort_each_child(node, &block)
+        node.dependencies.each do |dependency_name|
+          block.call(@nodes_by_name.fetch(dependency_name))
+        end
+      end
+
+      def tsort
+        super
+      rescue TSort::Cyclic => e
+        raise CycleError, e.message
+      end
+    end
+  end
+end

data/lib/igniter/compiler/validator.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Compiler
+    class Validator
+      def self.call(graph)
+        new(graph).call
+      end
+
+      def initialize(graph)
+        @graph = graph
+        @runtime_nodes_by_name = {}
+      end
+
+      def call
+        validate_unique_ids!
+        index_runtime_nodes!
+        validate_outputs!
+        validate_unique_paths!
+        validate_dependencies!
+        validate_callable_signatures!
+
+        self
+      end
+
+      def runtime_nodes
+        @runtime_nodes ||= @graph.nodes.reject { |node| node.kind == :output }
+      end
+
+      def outputs
+        @outputs ||= @graph.nodes.select { |node| node.kind == :output }
+      end
+
+      def runtime_nodes_by_name
+        @runtime_nodes_by_name
+      end
+
+      private
+
+      def validate_unique_ids!
+        seen = {}
+
+        @graph.nodes.each do |node|
+          if seen.key?(node.id)
+            raise validation_error(node, "Duplicate node id: #{node.id}")
+          end
+
+          seen[node.id] = true
+        end
+      end
+
+      def validate_unique_paths!
+        seen = {}
+
+        runtime_nodes.each do |node|
+          if seen.key?(node.path)
+            raise validation_error(node, "Duplicate node path: #{node.path}")
+          end
+
+          seen[node.path] = true
+        end
+
+        outputs.each do |output|
+          if seen.key?(output.path)
+            raise validation_error(output, "Duplicate node path: #{output.path}")
+          end
+
+          seen[output.path] = true
+        end
+      end
+
+      def index_runtime_nodes!
+        runtime_nodes.each do |node|
+          raise validation_error(node, "Duplicate node name: #{node.name}") if @runtime_nodes_by_name.key?(node.name)
+
+          @runtime_nodes_by_name[node.name] = node
+        end
+      end
+
+      def validate_outputs!
+        raise ValidationError, "Graph must define at least one output" if outputs.empty?
+
+        seen = {}
+        outputs.each do |output|
+          raise validation_error(output, "Duplicate output name: #{output.name}") if seen.key?(output.name)
+          raise validation_error(output, "Unknown output source '#{output.source}' for output '#{output.name}'") unless @runtime_nodes_by_name.key?(output.source)
+
+          seen[output.name] = true
+        end
+      end
+
+      def validate_dependencies!
+        runtime_nodes.each do |node|
+          validate_composition_node!(node) if node.kind == :composition
+
+          node.dependencies.each do |dependency_name|
+            next if @runtime_nodes_by_name.key?(dependency_name)
+
+            raise validation_error(node, "Unknown dependency '#{dependency_name}' for node '#{node.name}'")
+          end
+        end
+      end
+
+      def validate_composition_node!(node)
+        contract_class = node.contract_class
+
+        unless contract_class.is_a?(Class) && contract_class <= Igniter::Contract
+          raise validation_error(node, "Composition '#{node.name}' must reference an Igniter::Contract subclass")
+        end
+
+        unless contract_class.compiled_graph
+          raise validation_error(node, "Composition '#{node.name}' references an uncompiled contract")
+        end
+
+        validate_composition_input_mapping!(node, contract_class.compiled_graph)
+      end
+
+      def validate_composition_input_mapping!(node, child_graph)
+        child_input_nodes = child_graph.nodes.select { |child_node| child_node.kind == :input }
+        child_input_names = child_input_nodes.map(&:name)
+
+        unknown_inputs = node.input_mapping.keys - child_input_names
+        unless unknown_inputs.empty?
+          raise validation_error(
+            node,
+            "Composition '#{node.name}' maps unknown child inputs: #{unknown_inputs.sort.join(', ')}"
+          )
+        end
+
+        missing_required_inputs = child_input_nodes
+          .select(&:required?)
+          .reject { |child_input| node.input_mapping.key?(child_input.name) }
+          .map(&:name)
+
+        return if missing_required_inputs.empty?
+
+        raise validation_error(
+          node,
+          "Composition '#{node.name}' is missing mappings for required child inputs: #{missing_required_inputs.sort.join(', ')}"
+        )
+      end
+
+      def validate_callable_signatures!
+        runtime_nodes.each do |node|
+          next unless node.kind == :compute
+          next unless node.callable.is_a?(Proc)
+
+          validate_proc_signature!(node)
+        end
+      end
+
+      def validate_proc_signature!(node)
+        parameters = node.callable.parameters
+        positional_kinds = %i[req opt rest]
+        positional = parameters.select { |kind, _name| positional_kinds.include?(kind) }
+
+        unless positional.empty?
+          raise validation_error(
+            node,
+            "Compute '#{node.name}' proc must use keyword arguments for dependencies, got positional parameters"
+          )
+        end
+
+        accepts_any_keywords = parameters.any? { |kind, _name| kind == :keyrest }
+        accepted_keywords = parameters
+          .select { |kind, _name| %i[key keyreq].include?(kind) }
+          .map(&:last)
+        required_keywords = parameters
+          .select { |kind, _name| kind == :keyreq }
+          .map(&:last)
+
+        missing_dependencies = required_keywords - node.dependencies
+        unless missing_dependencies.empty?
+          raise validation_error(
+            node,
+            "Compute '#{node.name}' requires undeclared dependencies: #{missing_dependencies.sort.join(', ')}"
+          )
+        end
+
+        return if accepts_any_keywords
+
+        unknown_dependencies = node.dependencies - accepted_keywords
+        return if unknown_dependencies.empty?
+
+        raise validation_error(
+          node,
+          "Compute '#{node.name}' declares unsupported dependencies for its proc: #{unknown_dependencies.sort.join(', ')}"
+        )
+      end
+
+      def validation_error(node, message)
+        ValidationError.new(
+          message,
+          context: {
+            graph: @graph.name,
+            node_id: node.id,
+            node_name: node.name,
+            node_path: node.path,
+            source_location: node.source_location
+          }
+        )
+      end
+    end
+  end
+end

data/lib/igniter/compiler.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "compiler/compiled_graph"
+require_relative "compiler/validator"
+require_relative "compiler/graph_compiler"
+
+module Igniter
+  module Compiler
+  end
+end

data/lib/igniter/contract.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Igniter
+  class Contract
+    class << self
+      def define(&block)
+        @compiled_graph = DSL::ContractBuilder.compile(name: contract_name, &block)
+      end
+
+      def react_to(event_type, path: nil, &block)
+        raise CompileError, "react_to requires a block" unless block
+
+        reactions << Extensions::Reactive::Reaction.new(
+          event_type: event_type,
+          path: path,
+          action: block
+        )
+      end
+
+      def compiled_graph
+        @compiled_graph || superclass_compiled_graph
+      end
+      alias graph compiled_graph
+
+      def reactions
+        @reactions ||= []
+      end
+
+      private
+
+      def contract_name
+        name || "AnonymousContract"
+      end
+
+      def superclass_compiled_graph
+        return unless superclass.respond_to?(:compiled_graph)
+
+        superclass.compiled_graph
+      end
+    end
+
+    attr_reader :execution, :result
+
+    def initialize(inputs = {})
+      graph = self.class.compiled_graph
+      raise CompileError, "#{self.class.name} has no compiled graph. Use `define`." unless graph
+
+      @execution = Runtime::Execution.new(
+        compiled_graph: graph,
+        contract_instance: self,
+        inputs: inputs
+      )
+      @reactive = Extensions::Reactive::Engine.new(
+        execution: @execution,
+        contract: self,
+        reactions: self.class.reactions
+      )
+      @execution.events.subscribe(@reactive)
+      @result = Runtime::Result.new(@execution)
+    end
+
+    def resolve
+      execution.resolve_all
+      self
+    end
+
+    def resolve_all
+      resolve
+    end
+
+    def update_inputs(inputs)
+      execution.update_inputs(inputs)
+      self
+    end
+
+    def events
+      execution.events.events
+    end
+
+    def audit
+      execution.audit
+    end
+
+    def audit_snapshot
+      execution.audit.snapshot
+    end
+
+    def reactive
+      @reactive
+    end
+
+    def subscribe(subscriber = nil, &block)
+      execution.events.subscribe(subscriber, &block)
+      self
+    end
+
+    def diagnostics
+      Diagnostics::Report.new(execution)
+    end
+
+    def diagnostics_text
+      diagnostics.to_text
+    end
+
+    def diagnostics_markdown
+      diagnostics.to_markdown
+    end
+
+    def success?
+      execution.success?
+    end
+
+    def failed?
+      execution.failed?
+    end
+  end
+end