igniter-extensions 0.5.2

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

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require_relative "debug/profile_snapshot"
+require_relative "debug/pack_audit"
+require_relative "debug/report"
+
+module Igniter
+  module Extensions
+    module Contracts
+      module DebugPack
+        module_function
+
+        REPORT_CONTRIBUTOR = Module.new do
+          module_function
+
+          def augment(report:, result:, profile:)
+            snapshot = DebugPack.profile_snapshot(profile)
+            report.add_section(:debug, {
+                                 profile_fingerprint: profile.fingerprint,
+                                 pack_names: snapshot.pack_names,
+                                 registry_keys: snapshot.registry_keys,
+                                 output_names: result.outputs.keys.sort,
+                                 state_keys: result.state.keys.sort,
+                                 operation_count: result.compiled_graph.operations.length
+                               })
+          end
+        end
+
+        def manifest
+          Igniter::Contracts::PackManifest.new(
+            name: :extensions_debug,
+            requires_packs: [ExecutionReportPack, ProvenancePack],
+            registry_contracts: [Igniter::Contracts::PackManifest.diagnostic(:debug)],
+            metadata: { category: :developer }
+          )
+        end
+
+        def install_into(kernel)
+          kernel.diagnostics_contributors.register(:debug, REPORT_CONTRIBUTOR)
+          kernel
+        end
+
+        def profile_snapshot(profile)
+          Debug::ProfileSnapshot.new(profile: profile)
+        end
+
+        def pack_snapshot(pack_or_name, profile:)
+          manifest =
+            case pack_or_name
+            when Symbol, String
+              profile.pack_manifest(pack_or_name)
+            else
+              pack_or_name.respond_to?(:manifest) ? pack_or_name.manifest : profile.pack_manifest(pack_or_name)
+            end
+          raise ArgumentError, "unknown pack #{pack_or_name}" unless manifest
+
+          Debug::PackSnapshot.new(manifest)
+        end
+
+        def audit(pack, profile: nil)
+          Debug::PackAudit.build(pack, profile: profile)
+        end
+
+        def snapshot(result, profile:)
+          diagnostics = Igniter::Contracts.diagnose(result, profile: profile)
+          Debug::Report.new(
+            profile_snapshot: profile_snapshot(profile),
+            execution_result: result,
+            diagnostics_report: diagnostics,
+            provenance_summary: provenance_summary(result)
+          )
+        end
+
+        def report(environment, inputs: nil, compiled_graph: nil, &block)
+          compilation =
+            if block
+              environment.compilation_report(&block)
+            elsif compiled_graph
+              nil
+            else
+              raise ArgumentError, "debug_report requires a block or compiled_graph"
+            end
+
+          graph = compiled_graph || compilation&.compiled_graph
+          if inputs.nil? || compilation&.invalid?
+            return Debug::Report.new(profile_snapshot: profile_snapshot(environment.profile),
+                                     compilation_report: compilation)
+          end
+
+          result = environment.execute(graph, inputs: inputs)
+          diagnostics = environment.diagnose(result)
+
+          Debug::Report.new(
+            profile_snapshot: profile_snapshot(environment.profile),
+            compilation_report: compilation,
+            execution_result: result,
+            diagnostics_report: diagnostics,
+            provenance_summary: provenance_summary(result)
+          )
+        end
+
+        def provenance_summary(result)
+          result.outputs.keys.sort.each_with_object({}) do |output_name, memo|
+            lineage = ProvenancePack.lineage(result, output_name)
+            memo[output_name] = {
+              value: lineage.value,
+              contributing_inputs: lineage.contributing_inputs,
+              trace: lineage.to_h
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/differential/divergence.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Differential
+        class Divergence
+          attr_reader :output_name, :primary_value, :candidate_value, :kind
+
+          def initialize(output_name:, primary_value:, candidate_value:, kind:)
+            @output_name = output_name.to_sym
+            @primary_value = primary_value
+            @candidate_value = candidate_value
+            @kind = kind.to_sym
+            freeze
+          end
+
+          def delta
+            return nil unless primary_value.is_a?(Numeric) && candidate_value.is_a?(Numeric)
+
+            candidate_value - primary_value
+          end
+
+          def to_h
+            {
+              output_name: output_name,
+              primary_value: primary_value,
+              candidate_value: candidate_value,
+              kind: kind,
+              delta: delta
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/differential/formatter.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Differential
+        module Formatter
+          module_function
+
+          VALUE_MAX = 60
+
+          def format(report)
+            lines = []
+            lines << "Primary:    #{report.primary_name}"
+            lines << "Candidate:  #{report.candidate_name}"
+            lines << "Match:      #{report.match? ? "YES" : "NO"}"
+
+            if report.primary_error
+              lines << ""
+              lines << "PRIMARY ERROR: #{report.primary_error.fetch(:message)}"
+              return lines.join("\n")
+            end
+
+            if report.candidate_error
+              lines << ""
+              lines << "CANDIDATE ERROR: #{report.candidate_error.fetch(:message)}"
+            end
+
+            lines << ""
+
+            if report.divergences.empty? && report.primary_only.empty? && report.candidate_only.empty?
+              lines << "All shared outputs match."
+            else
+              append_divergences(report, lines)
+              append_only_section("CANDIDATE ONLY", report.candidate_only, lines)
+              append_only_section("PRIMARY ONLY", report.primary_only, lines)
+            end
+
+            lines.join("\n")
+          end
+
+          def append_divergences(report, lines)
+            return if report.divergences.empty?
+
+            lines << "DIVERGENCES (#{report.divergences.size}):"
+            report.divergences.each do |divergence|
+              lines << "  :#{divergence.output_name}"
+              lines << "    primary:   #{fmt(divergence.primary_value)}"
+              lines << "    candidate: #{fmt(divergence.candidate_value)}"
+              next if divergence.delta.nil?
+
+              delta = divergence.delta
+              lines << "    delta:     #{delta >= 0 ? "+#{delta}" : delta}"
+            end
+            lines << ""
+          end
+
+          def append_only_section(label, values, lines)
+            return if values.empty?
+
+            lines << "#{label} (#{values.size}):"
+            values.each do |name, value|
+              lines << "  :#{name} = #{fmt(value)}"
+            end
+            lines << ""
+          end
+
+          def fmt(value)
+            string =
+              case value
+              when nil then "nil"
+              when String, Symbol then value.inspect
+              when Hash then "{#{value.map { |key, item| "#{key}: #{item.inspect}" }.join(", ")}}"
+              when Array then "[#{value.map(&:inspect).join(", ")}]"
+              else
+                value.inspect
+              end
+
+            string.length > VALUE_MAX ? "#{string[0, VALUE_MAX - 3]}..." : string
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Differential
+        class Report
+          attr_reader :primary_name, :candidate_name, :inputs,
+                      :primary_outputs, :candidate_outputs,
+                      :divergences, :primary_only, :candidate_only,
+                      :primary_error, :candidate_error
+
+          def initialize(
+            primary_name:,
+            candidate_name:,
+            inputs:,
+            primary_outputs:,
+            candidate_outputs:,
+            divergences:,
+            primary_only:,
+            candidate_only:,
+            primary_error: nil,
+            candidate_error: nil
+          )
+            @primary_name = primary_name.to_s
+            @candidate_name = candidate_name.to_s
+            @inputs = inputs.transform_keys(&:to_sym).freeze
+            @primary_outputs = primary_outputs.transform_keys(&:to_sym).freeze
+            @candidate_outputs = candidate_outputs.transform_keys(&:to_sym).freeze
+            @divergences = divergences.freeze
+            @primary_only = primary_only.transform_keys(&:to_sym).freeze
+            @candidate_only = candidate_only.transform_keys(&:to_sym).freeze
+            @primary_error = primary_error&.freeze
+            @candidate_error = candidate_error&.freeze
+            freeze
+          end
+
+          def match?
+            divergences.empty? &&
+              primary_only.empty? &&
+              candidate_only.empty? &&
+              primary_error.nil? &&
+              candidate_error.nil?
+          end
+
+          def summary
+            return "match" if match?
+
+            parts = []
+            parts << "#{divergences.size} value(s) differ" if divergences.any?
+            parts << "#{primary_only.size} output(s) only in primary" if primary_only.any?
+            parts << "#{candidate_only.size} output(s) only in candidate" if candidate_only.any?
+            parts << "candidate error: #{candidate_error.fetch(:message)}" if candidate_error
+            parts << "primary error: #{primary_error.fetch(:message)}" if primary_error
+            "diverged - #{parts.join(", ")}"
+          end
+
+          def explain
+            Formatter.format(self)
+          end
+
+          alias to_s explain
+
+          def to_h
+            {
+              primary: primary_name,
+              candidate: candidate_name,
+              inputs: inputs,
+              match: match?,
+              primary_outputs: primary_outputs,
+              candidate_outputs: candidate_outputs,
+              divergences: divergences.map(&:to_h),
+              primary_only: primary_only,
+              candidate_only: candidate_only,
+              primary_error: primary_error,
+              candidate_error: candidate_error
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/differential/runner.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Differential
+        class Runner
+          def initialize(primary_name:, candidate_name:, tolerance: nil)
+            @primary_name = primary_name
+            @candidate_name = candidate_name
+            @tolerance = tolerance
+          end
+
+          def compare(
+            inputs:,
+            primary_environment: nil,
+            primary_compiled_graph: nil,
+            primary_result: nil,
+            candidate_environment: nil,
+            candidate_compiled_graph: nil,
+            candidate_result: nil
+          )
+            primary_result, primary_error = resolve_execution(
+              result: primary_result,
+              environment: primary_environment,
+              compiled_graph: primary_compiled_graph,
+              inputs: inputs,
+              label: @primary_name
+            )
+            candidate_result, candidate_error = resolve_execution(
+              result: candidate_result,
+              environment: candidate_environment,
+              compiled_graph: candidate_compiled_graph,
+              inputs: inputs,
+              label: @candidate_name
+            )
+
+            primary_outputs = primary_result ? primary_result.outputs.to_h : {}
+            candidate_outputs = candidate_result ? candidate_result.outputs.to_h : {}
+
+            build_report(
+              inputs: inputs,
+              primary_outputs: primary_outputs,
+              candidate_outputs: candidate_outputs,
+              primary_error: primary_error,
+              candidate_error: candidate_error
+            )
+          end
+
+          private
+
+          def resolve_execution(result:, environment:, compiled_graph:, inputs:, label:)
+            return [result, nil] if result
+
+            if environment.nil? || compiled_graph.nil?
+              raise ArgumentError,
+                    "#{label} comparison requires either an execution result or environment + compiled_graph"
+            end
+
+            begin
+              [environment.execute(compiled_graph, inputs: inputs), nil]
+            rescue StandardError => e
+              [nil, serialize_error(e)]
+            end
+          end
+
+          def build_report(inputs:, primary_outputs:, candidate_outputs:, primary_error:, candidate_error:)
+            common = primary_outputs.keys & candidate_outputs.keys
+            divergences = compare_common(primary_outputs, candidate_outputs, common)
+
+            Report.new(
+              primary_name: @primary_name,
+              candidate_name: @candidate_name,
+              inputs: inputs,
+              primary_outputs: primary_outputs,
+              candidate_outputs: candidate_outputs,
+              divergences: divergences,
+              primary_only: slice_missing(primary_outputs, candidate_outputs),
+              candidate_only: slice_missing(candidate_outputs, primary_outputs),
+              primary_error: primary_error,
+              candidate_error: candidate_error
+            )
+          end
+
+          def compare_common(primary_outputs, candidate_outputs, names)
+            names.filter_map do |name|
+              primary_value = primary_outputs.fetch(name)
+              candidate_value = candidate_outputs.fetch(name)
+              next if values_match?(primary_value, candidate_value)
+
+              Divergence.new(
+                output_name: name,
+                primary_value: primary_value,
+                candidate_value: candidate_value,
+                kind: divergence_kind(primary_value, candidate_value)
+              )
+            end
+          end
+
+          def slice_missing(source, other)
+            (source.keys - other.keys).each_with_object({}) do |name, memo|
+              memo[name] = source.fetch(name)
+            end
+          end
+
+          def values_match?(left, right)
+            return true if left == right
+            return false unless @tolerance
+            return false unless left.is_a?(Numeric) && right.is_a?(Numeric)
+
+            (left - right).abs <= @tolerance
+          end
+
+          def divergence_kind(left, right)
+            left.instance_of?(right.class) ? :value_mismatch : :type_mismatch
+          end
+
+          def serialize_error(error)
+            payload =
+              if error.respond_to?(:to_h)
+                error.to_h
+              else
+                {}
+              end
+
+            {
+              type: error.class.name,
+              message: error.message,
+              details: payload
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "differential/divergence"
+require_relative "differential/formatter"
+require_relative "differential/report"
+require_relative "differential/runner"
+
+module Igniter
+  module Extensions
+    module Contracts
+      module DifferentialPack
+        module_function
+
+        def manifest
+          Igniter::Contracts::PackManifest.new(
+            name: :extensions_differential,
+            metadata: { category: :developer }
+          )
+        end
+
+        def install_into(kernel)
+          kernel
+        end
+
+        def compare(
+          inputs:,
+          primary_environment: nil,
+          primary_compiled_graph: nil,
+          primary_result: nil,
+          candidate_environment: nil,
+          candidate_compiled_graph: nil,
+          candidate_result: nil,
+          tolerance: nil,
+          primary_name: "primary",
+          candidate_name: "candidate"
+        )
+          Differential::Runner.new(
+            primary_name: primary_name,
+            candidate_name: candidate_name,
+            tolerance: tolerance
+          ).compare(
+            inputs: inputs,
+            primary_environment: primary_environment,
+            primary_compiled_graph: primary_compiled_graph,
+            primary_result: primary_result,
+            candidate_environment: candidate_environment,
+            candidate_compiled_graph: candidate_compiled_graph,
+            candidate_result: candidate_result
+          )
+        end
+
+        def shadow(**arguments)
+          on_divergence = arguments.delete(:on_divergence)
+          report = compare(**arguments)
+          on_divergence.call(report) if on_divergence && !report.match?
+          report
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module ExecutionReportPack
+        module_function
+
+        REPORT_CONTRIBUTOR = Module.new do
+          module_function
+
+          def augment(report:, result:, profile:)
+            report.add_section(:execution_report, {
+                                 profile_fingerprint: profile.fingerprint,
+                                 pack_names: profile.pack_names.sort,
+                                 output_count: result.outputs.length,
+                                 state_count: result.state.length,
+                                 outputs: result.outputs.to_h,
+                                 state_keys: result.state.keys.sort
+                               })
+          end
+        end
+
+        def manifest
+          Igniter::Contracts::PackManifest.new(
+            name: :extensions_execution_report,
+            registry_contracts: [Igniter::Contracts::PackManifest.diagnostic(:execution_report)]
+          )
+        end
+
+        def install_into(kernel)
+          kernel.diagnostics_contributors.register(:execution_report, REPORT_CONTRIBUTOR)
+          kernel
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/incremental/formatter.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Incremental
+        module Formatter
+          module_function
+
+          LINE = "─" * 42
+          VALUE_MAX = 60
+
+          def format(result)
+            lines = []
+            lines << "Contracts Incremental Report"
+            lines << LINE
+            lines << "Recomputed:  #{result.recomputed_count} node(s)"
+            lines << "Skipped:     #{result.skipped_nodes.length} node(s)"
+            lines << "Backdated:   #{result.backdated_nodes.length} node(s)"
+            lines << ""
+
+            if result.changed_outputs.any?
+              lines << "CHANGED OUTPUTS (#{result.changed_outputs.length}):"
+              result.changed_outputs.each do |name, diff|
+                lines << "  :#{name}  #{fmt(diff[:from])} -> #{fmt(diff[:to])}"
+              end
+            else
+              lines << "No output values changed."
+            end
+
+            lines << ""
+            if result.skipped_nodes.any?
+              lines << "SKIPPED:   #{result.skipped_nodes.map do |name|
+                ":#{name}"
+              end.join("  ")}"
+            end
+            if result.backdated_nodes.any?
+              lines << "BACKDATED: #{result.backdated_nodes.map do |name|
+                ":#{name}"
+              end.join("  ")}"
+            end
+            if result.changed_nodes.any?
+              lines << "CHANGED:   #{result.changed_nodes.map do |name|
+                ":#{name}"
+              end.join("  ")}"
+            end
+            lines.compact.join("\n")
+          end
+
+          def fmt(value)
+            rendered = value.inspect
+            return rendered if rendered.length <= VALUE_MAX
+
+            "#{rendered[0, VALUE_MAX - 3]}..."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/extensions/contracts/incremental/node_state.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Incremental
+        class NodeState
+          attr_reader :name, :value, :value_version, :dep_snapshot
+
+          def initialize(name:, value:, value_version:, dep_snapshot: {})
+            @name = name.to_sym
+            @value = value
+            @value_version = Integer(value_version)
+            @dep_snapshot = dep_snapshot.transform_keys(&:to_sym).freeze
+            freeze
+          end
+
+          def to_h
+            {
+              name: name,
+              value: value,
+              value_version: value_version,
+              dep_snapshot: dep_snapshot
+            }
+          end
+        end
+      end
+    end
+  end
+end