igniter-extensions 0.5.2

data/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/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/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/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/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

data/lib/igniter/extensions/contracts/capabilities/report.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Capabilities
+        class Report
+          attr_reader :required_capabilities, :profile_capabilities, :violations, :undeclared_nodes
+
+          def initialize(required_capabilities:, profile_capabilities:, violations:, undeclared_nodes:)
+            @required_capabilities = required_capabilities.transform_keys(&:to_sym).transform_values do |value|
+              Array(value).map(&:to_sym).freeze
+            end.freeze
+            @profile_capabilities = Array(profile_capabilities).map(&:to_sym).uniq.freeze
+            @violations = Array(violations).freeze
+            @undeclared_nodes = Array(undeclared_nodes).map(&:to_sym).freeze
+            freeze
+          end
+
+          def valid?
+            violations.empty?
+          end
+
+          def invalid?
+            !valid?
+          end
+
+          def summary
+            return "valid" if valid?
+
+            "invalid - #{violations.length} capability violation(s)"
+          end
+
+          def to_h
+            {
+              valid: valid?,
+              required_capabilities: required_capabilities,
+              profile_capabilities: profile_capabilities,
+              undeclared_nodes: undeclared_nodes,
+              violations: violations.map(&:to_h)
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/capabilities/violation.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Capabilities
+        class Violation
+          attr_reader :kind, :node_name, :capabilities, :message
+
+          def initialize(kind:, node_name:, capabilities:, message:)
+            @kind = kind.to_sym
+            @node_name = node_name.to_sym
+            @capabilities = Array(capabilities).map(&:to_sym).freeze
+            @message = message.to_s
+            freeze
+          end
+
+          def to_h
+            {
+              kind: kind,
+              node_name: node_name,
+              capabilities: capabilities,
+              message: message
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/capabilities_pack.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require_relative "capabilities/declaration"
+require_relative "capabilities/violation"
+require_relative "capabilities/report"
+require_relative "capabilities/policy"
+require_relative "capabilities/error"
+
+module Igniter
+  module Extensions
+    module Contracts
+      module CapabilitiesPack
+        module_function
+
+        def manifest
+          Igniter::Contracts::PackManifest.new(
+            name: :extensions_capabilities,
+            metadata: { category: :validation }
+          )
+        end
+
+        def install_into(kernel)
+          kernel
+        end
+
+        def declare(*capabilities, callable: nil, &block)
+          target = callable || block
+          raise ArgumentError, "capability declaration requires a callable or block" unless target
+
+          Capabilities::Declaration.new(callable: target, capabilities: capabilities)
+        end
+
+        def pure(callable: nil, &block)
+          declare(:pure, callable: callable, &block)
+        end
+
+        def policy(denied: [], required: [], on_undeclared: :ignore)
+          Capabilities::Policy.new(
+            denied: denied,
+            required: required,
+            on_undeclared: on_undeclared
+          )
+        end
+
+        def required_capabilities(compiled_graph)
+          compiled_graph.operations.reject(&:output?).each_with_object({}) do |operation, memo|
+            capabilities = capabilities_for_operation(operation)
+            memo[operation.name] = capabilities unless capabilities.empty?
+          end
+        end
+
+        def capabilities_for(compiled_graph, node_name)
+          operation = compiled_graph.operations.find { |entry| entry.name == node_name.to_sym }
+          return [] unless operation
+
+          capabilities_for_operation(operation)
+        end
+
+        def profile_capabilities(profile)
+          profile.pack_manifests
+                 .flat_map do |manifest_entry|
+                   manifest_entry.provides_capabilities.empty? ? Array(manifest_entry.metadata[:capabilities]) : manifest_entry.provides_capabilities
+                 end
+                 .map(&:to_sym)
+                 .uniq
+        end
+
+        def report(compiled_graph, profile: nil, policy: nil)
+          requirements = required_capabilities(compiled_graph)
+          undeclared_nodes = compiled_graph.operations.reject(&:output?).map(&:name) - requirements.keys
+          violations = violations_for(requirements, policy: policy, undeclared_nodes: undeclared_nodes)
+          maybe_warn_about_undeclared(policy, undeclared_nodes)
+
+          Capabilities::Report.new(
+            required_capabilities: requirements,
+            profile_capabilities: profile ? profile_capabilities(profile) : [],
+            violations: violations,
+            undeclared_nodes: undeclared_nodes
+          )
+        end
+
+        def check!(compiled_graph, policy:, profile: nil)
+          result = report(compiled_graph, profile: profile, policy: policy)
+          raise Capabilities::CapabilityViolationError.new(nil, report: result) if result.invalid?
+
+          result
+        end
+
+        def capabilities_for_operation(operation)
+          capabilities = Array(operation.attributes[:capabilities]).map(&:to_sym)
+          callable = operation.attributes[:callable]
+          capabilities.concat(Array(callable.declared_capabilities).map(&:to_sym)) if callable.respond_to?(:declared_capabilities)
+          capabilities.uniq
+        end
+
+        def violations_for(requirements, policy:, undeclared_nodes:)
+          return [] unless policy
+
+          violations = []
+
+          requirements.each do |node_name, capabilities|
+            denied = capabilities & policy.denied
+            if denied.any?
+              violations << Capabilities::Violation.new(
+                kind: :denied_capability,
+                node_name: node_name,
+                capabilities: denied,
+                message: "node #{node_name} uses denied capabilities: #{denied.join(", ")}"
+              )
+            end
+
+            missing = policy.required - capabilities
+            next unless missing.any?
+
+            violations << Capabilities::Violation.new(
+              kind: :missing_required_capability,
+              node_name: node_name,
+              capabilities: missing,
+              message: "node #{node_name} is missing required capabilities: #{missing.join(", ")}"
+            )
+          end
+
+          if policy.on_undeclared == :error
+            undeclared_nodes.each do |node_name|
+              violations << Capabilities::Violation.new(
+                kind: :undeclared_capabilities,
+                node_name: node_name,
+                capabilities: [],
+                message: "node #{node_name} does not declare capabilities"
+              )
+            end
+          end
+
+          violations
+        end
+
+        def maybe_warn_about_undeclared(policy, undeclared_nodes)
+          return unless policy&.on_undeclared == :warn
+          return if undeclared_nodes.empty?
+
+          Warning.warn("WARNING: undeclared capabilities for nodes: #{undeclared_nodes.join(", ")}\n")
+        end
+      end
+    end
+  end
+end