igniter 0.5.0 → 0.5.2

data/packages/igniter-extensions/lib/igniter/extensions/contracts/aggregate_pack.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module AggregatePack
+        AGGREGATE_KEYWORDS = %i[count sum avg].freeze
+
+        class << self
+          def manifest
+            Igniter::Contracts::PackManifest.new(
+              name: :extensions_aggregate,
+              registry_contracts: AGGREGATE_KEYWORDS.map { |kind| Igniter::Contracts::PackManifest.dsl_keyword(kind) }
+            )
+          end
+
+          def install_into(kernel)
+            install_dsl_keywords(kernel)
+            kernel
+          end
+
+          def install_dsl_keywords(kernel)
+            kernel.dsl_keywords.register(:count, count_keyword)
+            kernel.dsl_keywords.register(:sum, sum_keyword)
+            kernel.dsl_keywords.register(:avg, avg_keyword)
+          end
+
+          def count_keyword
+            Igniter::Contracts::DslKeyword.new(:count) do |name, from:, builder:, matching: nil|
+              builder.add_operation(
+                kind: :compute,
+                name: name,
+                depends_on: [from.to_sym],
+                callable: lambda do |**values|
+                  items = AggregatePack.enumerable_source(values.fetch(from.to_sym), source_name: from.to_sym,
+                                                                                     operation_name: :count)
+
+                  if matching
+                    items.count { |item| matching.call(item) }
+                  else
+                    items.count
+                  end
+                end
+              )
+            end
+          end
+
+          def sum_keyword
+            Igniter::Contracts::DslKeyword.new(:sum) do |name, from:, builder:, using: nil|
+              builder.add_operation(
+                kind: :compute,
+                name: name,
+                depends_on: [from.to_sym],
+                callable: lambda do |**values|
+                  items = AggregatePack.enumerable_source(values.fetch(from.to_sym), source_name: from.to_sym,
+                                                                                     operation_name: :sum)
+                  items.reduce(0) do |total, item|
+                    total + AggregatePack.extract_value(item, using)
+                  end
+                end
+              )
+            end
+          end
+
+          def avg_keyword
+            Igniter::Contracts::DslKeyword.new(:avg) do |name, from:, builder:, using: nil|
+              builder.add_operation(
+                kind: :compute,
+                name: name,
+                depends_on: [from.to_sym],
+                callable: lambda do |**values|
+                  items = AggregatePack.enumerable_source(values.fetch(from.to_sym), source_name: from.to_sym,
+                                                                                     operation_name: :avg)
+                  projected = items.map { |item| AggregatePack.extract_value(item, using) }
+                  next nil if projected.empty?
+
+                  projected.sum.to_f / projected.length
+                end
+              )
+            end
+          end
+
+          def enumerable_source(source, source_name:, operation_name:)
+            return source.to_a if source.respond_to?(:to_a)
+
+            raise TypeError, "#{operation_name} source #{source_name} is not enumerable"
+          end
+
+          def extract_value(item, projection)
+            return item if projection.nil?
+            return projection.call(item) if projection.respond_to?(:call)
+
+            key = projection.to_sym
+            return item.fetch(key) if item.respond_to?(:key?) && item.key?(key)
+            return item.fetch(key.to_s) if item.respond_to?(:key?) && item.key?(key.to_s)
+
+            item.public_send(key)
+          end
+        end
+      end
+    end
+  end
+end

data/packages/igniter-extensions/lib/igniter/extensions/contracts/audit/builder.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Audit
+        module Builder
+          module_function
+
+          def build(target)
+            result = unwrap_result(target)
+            compiled_graph = result.compiled_graph
+            outputs = result.outputs.to_h
+            state_values = result.state.to_h
+
+            Snapshot.new(
+              graph: graph_name(compiled_graph),
+              profile_fingerprint: result.profile_fingerprint,
+              events: build_events(compiled_graph, state_values: state_values, outputs: outputs),
+              states: build_states(compiled_graph, state_values: state_values, outputs: outputs),
+              children: build_children(state_values),
+              output_names: compiled_graph.operations.select(&:output?).map(&:name)
+            )
+          end
+
+          def unwrap_result(target)
+            return target.execution_result if target.respond_to?(:execution_result)
+
+            target
+          end
+
+          def graph_name(compiled_graph)
+            operation_names = compiled_graph.operations.reject(&:output?).map(&:name)
+            return "contracts_graph" if operation_names.empty?
+
+            "contracts_graph(#{operation_names.join(",")})"
+          end
+
+          def build_events(compiled_graph, state_values:, outputs:)
+            compiled_graph.operations.each_with_index.map do |operation, index|
+              Event.new(
+                event_id: "#{operation.kind}:#{operation.name}:#{index}",
+                type: event_type_for(operation),
+                node_name: operation.name,
+                path: [operation.name],
+                status: status_for(operation, state_values: state_values, outputs: outputs),
+                payload: payload_for(operation, state_values: state_values, outputs: outputs)
+              )
+            end
+          end
+
+          def build_states(compiled_graph, state_values:, outputs:)
+            compiled_graph.operations.each_with_object({}) do |operation, memo|
+              next if operation.output?
+
+              value = operation.output? ? outputs[operation.name] : state_values[operation.name]
+              memo[operation.name] = {
+                path: [operation.name],
+                kind: operation.kind,
+                status: status_for(operation, state_values: state_values, outputs: outputs),
+                value: serialize_value(value),
+                dependencies: dependency_names_for(operation)
+              }
+            end
+          end
+
+          def build_children(state_values)
+            state_values.each_with_object([]) do |(name, value), memo|
+              next unless nested_execution_result?(value)
+
+              memo << {
+                node_name: name,
+                snapshot: build(value).to_h
+              }
+            end
+          end
+
+          def event_type_for(operation)
+            return :output_observed if operation.output?
+
+            :"#{operation.kind}_observed"
+          end
+
+          def status_for(operation, state_values:, outputs:)
+            collection = operation.output? ? outputs : state_values
+            collection.key?(operation.name) ? :succeeded : :missing
+          end
+
+          def payload_for(operation, state_values:, outputs:)
+            value = operation.output? ? outputs[operation.name] : state_values[operation.name]
+            payload = {
+              kind: operation.kind,
+              value: serialize_value(value)
+            }
+
+            dependencies = dependency_names_for(operation)
+            payload[:dependencies] = dependencies if dependencies.any?
+            payload
+          end
+
+          def dependency_names_for(operation)
+            names = []
+            names.concat(Array(operation.attributes[:depends_on])) if operation.attribute?(:depends_on)
+            names << operation.attributes[:from] if operation.attribute?(:from)
+            names.map(&:to_sym).uniq
+          end
+
+          def serialize_value(value)
+            case value
+            when Igniter::Contracts::ExecutionResult
+              {
+                type: :execution_result,
+                profile_fingerprint: value.profile_fingerprint,
+                outputs: value.outputs.to_h
+              }
+            when Array
+              value.map { |item| serialize_value(item) }
+            when Hash
+              value.transform_keys(&:to_sym).transform_values { |item| serialize_value(item) }
+            else
+              value
+            end
+          end
+
+          def nested_execution_result?(value)
+            value.is_a?(Igniter::Contracts::ExecutionResult)
+          end
+        end
+      end
+    end
+  end
+end

data/packages/igniter-extensions/lib/igniter/extensions/contracts/audit/event.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Audit
+        class Event
+          attr_reader :event_id, :type, :node_name, :path, :status, :payload
+
+          def initialize(event_id:, type:, node_name:, path:, status:, payload: {})
+            @event_id = event_id.to_s
+            @type = type.to_sym
+            @node_name = node_name.to_sym
+            @path = Array(path).map(&:to_sym).freeze
+            @status = status.to_sym
+            @payload = payload.freeze
+            freeze
+          end
+
+          def to_h
+            {
+              event_id: event_id,
+              type: type,
+              node_name: node_name,
+              path: path,
+              status: status,
+              payload: payload
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/packages/igniter-extensions/lib/igniter/extensions/contracts/audit/snapshot.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Audit
+        class Snapshot
+          attr_reader :graph, :profile_fingerprint, :event_count, :events, :states, :children, :output_names
+
+          def initialize(graph:, profile_fingerprint:, events:, states:, children:, output_names:)
+            @graph = graph.to_s
+            @profile_fingerprint = profile_fingerprint
+            @events = events.freeze
+            @states = states.transform_keys(&:to_sym).freeze
+            @children = children.freeze
+            @output_names = output_names.map(&:to_sym).freeze
+            @event_count = @events.length
+            freeze
+          end
+
+          def event_types
+            events.map(&:type).uniq
+          end
+
+          def state(name)
+            states.fetch(name.to_sym)
+          end
+
+          def to_h
+            {
+              graph: graph,
+              profile_fingerprint: profile_fingerprint,
+              event_count: event_count,
+              output_names: output_names,
+              events: events.map(&:to_h),
+              states: states,
+              children: children
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/packages/igniter-extensions/lib/igniter/extensions/contracts/audit_pack.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "audit/event"
+require_relative "audit/snapshot"
+require_relative "audit/builder"
+
+module Igniter
+  module Extensions
+    module Contracts
+      module AuditPack
+        module_function
+
+        REPORT_CONTRIBUTOR = Module.new do
+          module_function
+
+          def augment(report:, result:, profile:) # rubocop:disable Lint/UnusedMethodArgument
+            snapshot = AuditPack.snapshot(result)
+            report.add_section(:audit_summary, {
+                                 graph: snapshot.graph,
+                                 event_count: snapshot.event_count,
+                                 event_types: snapshot.event_types,
+                                 state_count: snapshot.states.length,
+                                 output_names: snapshot.output_names
+                               })
+          end
+        end
+
+        def manifest
+          Igniter::Contracts::PackManifest.new(
+            name: :extensions_audit,
+            registry_contracts: [Igniter::Contracts::PackManifest.diagnostic(:audit_summary)],
+            metadata: { category: :developer }
+          )
+        end
+
+        def install_into(kernel)
+          kernel.diagnostics_contributors.register(:audit_summary, REPORT_CONTRIBUTOR)
+          kernel
+        end
+
+        def snapshot(result)
+          Audit::Builder.build(result)
+        end
+
+        def report(environment, inputs: nil, compiled_graph: nil, &block)
+          result =
+            if block
+              environment.run(inputs: inputs || {}, &block)
+            elsif compiled_graph
+              environment.execute(compiled_graph, inputs: inputs || {})
+            else
+              raise ArgumentError, "audit_report requires a block or compiled_graph"
+            end
+
+          snapshot(result)
+        end
+      end
+    end
+  end
+end

data/packages/igniter-extensions/lib/igniter/extensions/contracts/branch_pack.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module BranchPack
+        UNSET = Object.new.freeze
+
+        class << self
+          def manifest
+            Igniter::Contracts::PackManifest.new(
+              name: :extensions_branch,
+              registry_contracts: [Igniter::Contracts::PackManifest.dsl_keyword(:branch)]
+            )
+          end
+
+          def install_into(kernel)
+            kernel.dsl_keywords.register(:branch, branch_keyword)
+            kernel
+          end
+
+          def branch_keyword
+            Igniter::Contracts::DslKeyword.new(:branch) do |name, on:, builder:, depends_on: [], &block|
+              raise ArgumentError, "branch :#{name} requires a block" unless block
+
+              selector_name = on.to_sym
+              dependency_names = [selector_name, *Array(depends_on).map(&:to_sym)].uniq
+              definition = Definition.new(name: name, selector_name: selector_name)
+              definition.instance_eval(&block)
+              definition.validate!
+
+              builder.add_operation(
+                kind: :compute,
+                name: name,
+                depends_on: dependency_names,
+                callable: lambda do |**values|
+                  definition.resolve(values)
+                end
+              )
+            end
+          end
+
+          def invoke_value(callable_or_value, kwargs)
+            return callable_or_value unless callable_or_value.respond_to?(:call)
+
+            parameters = callable_or_value.parameters
+            accepts_any_keywords = parameters.any? { |kind, _name| kind == :keyrest }
+            return callable_or_value.call(**kwargs) if accepts_any_keywords
+
+            accepted = parameters.select { |kind, _name| %i[key keyreq].include?(kind) }.map(&:last)
+            callable_or_value.call(**kwargs.slice(*accepted))
+          end
+
+          class Definition
+            def initialize(name:, selector_name:)
+              @name = name.to_sym
+              @selector_name = selector_name.to_sym
+              @cases = []
+              @default_case = nil
+            end
+
+            def on(match = UNSET, id: nil, value: UNSET, **options, &block)
+              matcher_kind, matcher_value = normalize_match(match, options)
+              resolved_value = normalize_value(value, block)
+
+              @cases << {
+                id: (id || :"case_#{@cases.length + 1}").to_sym,
+                matcher: matcher_kind,
+                match: matcher_value,
+                value: resolved_value
+              }
+            end
+
+            def default(id: :default, value: UNSET, &block)
+              raise ArgumentError, "branch :#{@name} can define only one default" if @default_case
+
+              @default_case = {
+                id: id.to_sym,
+                matcher: :default,
+                match: :default,
+                value: normalize_value(value, block)
+              }
+            end
+
+            def validate!
+              raise ArgumentError, "branch :#{@name} requires at least one on clause" if @cases.empty?
+              raise ArgumentError, "branch :#{@name} requires a default clause" unless @default_case
+
+              duplicate_ids = (@cases.map { |entry| entry.fetch(:id) } + [@default_case.fetch(:id)])
+                              .group_by { |id| id }
+                              .select { |_id, group| group.length > 1 }
+                              .keys
+              unless duplicate_ids.empty?
+                raise ArgumentError,
+                      "branch :#{@name} has duplicate case ids: #{duplicate_ids.join(", ")}"
+              end
+
+              overlapping = overlapping_literals
+              return if overlapping.empty?
+
+              raise ArgumentError,
+                    "branch :#{@name} has overlapping literal matches: #{overlapping.map(&:inspect).join(", ")}"
+            end
+
+            def resolve(kwargs)
+              selector_value = kwargs.fetch(@selector_name)
+              selected = @cases.find { |entry| match?(entry, selector_value) } || @default_case
+
+              {
+                case: selected.fetch(:id),
+                value: BranchPack.invoke_value(selected.fetch(:value), kwargs),
+                matcher: selected.fetch(:matcher),
+                matched_on: selected.fetch(:match),
+                selector: @selector_name,
+                selector_value: selector_value
+              }
+            end
+
+            private
+
+            def normalize_match(match, options)
+              matcher_options = options.slice(:eq, :in, :matches)
+              provided = matcher_options.reject { |_key, value| value.equal?(UNSET) || value.nil? }
+
+              raise ArgumentError, "branch :#{@name} on cannot combine positional match with eq:, in:, or matches:" if !match.equal?(UNSET) && !provided.empty?
+
+              raise ArgumentError, "branch :#{@name} on requires a positional match or one of eq:, in:, or matches:" if match.equal?(UNSET) && provided.empty?
+
+              if provided.length > 1
+                raise ArgumentError,
+                      "branch :#{@name} on supports only one matcher option at a time"
+              end
+
+              return [:eq, match] unless match.equal?(UNSET)
+
+              matcher_kind, matcher_value = provided.first
+
+              case matcher_kind
+              when :eq
+                [:eq, matcher_value]
+              when :in
+                array = Array(matcher_value)
+                raise ArgumentError, "branch :#{@name} in: requires a non-empty array" if array.empty?
+
+                [:in, array.freeze]
+              when :matches
+                raise ArgumentError, "branch :#{@name} matches: requires a Regexp" unless matcher_value.is_a?(Regexp)
+
+                [:matches, matcher_value]
+              else
+                raise ArgumentError, "branch :#{@name} received an unknown matcher #{matcher_kind.inspect}"
+              end
+            end
+
+            def normalize_value(value, block)
+              if !value.equal?(UNSET) && block
+                raise ArgumentError,
+                      "branch :#{@name} case cannot combine value: with a block"
+              end
+              raise ArgumentError, "branch :#{@name} case requires value: or a block" if value.equal?(UNSET) && !block
+
+              block || value
+            end
+
+            def overlapping_literals
+              literals = @cases.flat_map do |entry|
+                case entry.fetch(:matcher)
+                when :eq
+                  [entry.fetch(:match)]
+                when :in
+                  entry.fetch(:match)
+                else
+                  []
+                end
+              end
+
+              literals.group_by { |value| value }
+                      .select { |_value, group| group.length > 1 }
+                      .keys
+            end
+
+            def match?(entry, selector_value)
+              case entry.fetch(:matcher)
+              when :eq
+                selector_value == entry.fetch(:match)
+              when :in
+                entry.fetch(:match).include?(selector_value)
+              when :matches
+                !!(selector_value.to_s =~ entry.fetch(:match))
+              else
+                false
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/packages/igniter-extensions/lib/igniter/extensions/contracts/capabilities/declaration.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Capabilities
+        class Declaration
+          attr_reader :callable, :capabilities
+
+          def initialize(callable:, capabilities:)
+            @callable = callable
+            @capabilities = Array(capabilities).flatten.compact.map(&:to_sym).uniq.freeze
+            freeze
+          end
+
+          def call(**kwargs)
+            callable.call(**kwargs)
+          end
+
+          def declared_capabilities
+            capabilities
+          end
+
+          def pure?
+            capabilities.include?(:pure)
+          end
+        end
+      end
+    end
+  end
+end

data/packages/igniter-extensions/lib/igniter/extensions/contracts/capabilities/error.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Capabilities
+        class Error < StandardError; end
+
+        class CapabilityViolationError < Error
+          attr_reader :report
+
+          def initialize(message = nil, report:)
+            @report = report
+            super(message || default_message)
+          end
+
+          def to_h
+            {
+              message: message,
+              report: report.to_h
+            }
+          end
+
+          private
+
+          def default_message
+            return "capability policy violated" if report.violations.empty?
+
+            report.violations.map(&:message).join("; ")
+          end
+        end
+      end
+    end
+  end
+end

data/packages/igniter-extensions/lib/igniter/extensions/contracts/capabilities/policy.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Capabilities
+        class Policy
+          attr_reader :denied, :required, :on_undeclared
+
+          def initialize(denied: [], required: [], on_undeclared: :ignore)
+            @denied = Array(denied).map(&:to_sym).uniq.freeze
+            @required = Array(required).map(&:to_sym).uniq.freeze
+            @on_undeclared = on_undeclared.to_sym
+            freeze
+          end
+        end
+      end
+    end
+  end
+end