igniter 0.3.1 → 0.4.3

data/lib/igniter/property_testing/formatter.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Igniter
+  module PropertyTesting
+    # Renders a property-test Result as a human-readable ASCII report.
+    class Formatter
+      PASS_LABEL = "PASS"
+      FAIL_LABEL = "FAIL"
+
+      def initialize(result)
+        @result = result
+      end
+
+      def render # rubocop:disable Metrics/MethodLength
+        lines = []
+        lines << header
+        lines << summary_line
+        lines << ""
+
+        if @result.passed?
+          lines << "  All #{@result.total_runs} runs passed."
+        else
+          lines << counterexample_section
+          lines << ""
+          lines << failed_runs_section
+        end
+
+        lines.join("\n")
+      end
+
+      private
+
+      def header
+        label = @result.passed? ? PASS_LABEL : FAIL_LABEL
+        "PropertyTest: #{@result.contract_class.name}  [#{label}]"
+      end
+
+      def summary_line
+        "Runs: #{@result.total_runs} | " \
+          "Passed: #{@result.passed_runs.size} | " \
+          "Failed: #{@result.failed_runs.size}"
+      end
+
+      def counterexample_section
+        cx = @result.counterexample
+        return "" unless cx
+
+        [
+          "COUNTEREXAMPLE (run ##{cx.run_number}):",
+          "  Inputs:  #{cx.inputs.inspect}",
+          "  Failure: #{cx.failure_message}"
+        ].join("\n")
+      end
+
+      def failed_runs_section
+        return "" if @result.failed_runs.empty?
+
+        lines = ["FAILED RUNS:"]
+        @result.failed_runs.each do |run|
+          lines << "  ##{run.run_number.to_s.ljust(5)} #{run.failure_message.ljust(40)} inputs: #{run.inputs.inspect}"
+        end
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/igniter/property_testing/generators.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Igniter
+  module PropertyTesting
+    # Built-in convenience generators for property testing.
+    #
+    # Each method returns a callable (lambda) that produces a random value
+    # when invoked. Pass these as values in the `generators:` hash to
+    # ContractClass.property_test.
+    #
+    # @example
+    #   G = Igniter::PropertyTesting::Generators
+    #
+    #   MyContract.property_test(
+    #     generators: {
+    #       price:    G.float(0.0..500.0),
+    #       quantity: G.positive_integer(max: 100),
+    #       label:    G.string(length: 3..10),
+    #       active:   G.boolean
+    #     },
+    #     runs: 200
+    #   )
+    module Generators
+      # @param min [Integer]
+      # @param max [Integer]
+      # @return [#call]
+      def self.integer(min: -100, max: 100)
+        -> { rand(min..max) }
+      end
+
+      # @param max [Integer]
+      # @return [#call]
+      def self.positive_integer(max: 1000)
+        -> { rand(1..max) }
+      end
+
+      # @param range [Range<Float>]
+      # @return [#call]
+      def self.float(range = 0.0..1.0)
+        -> { range.min + rand * (range.max - range.min) }
+      end
+
+      # @param length [Range<Integer>, Integer]
+      # @param charset [Symbol] :alpha, :alphanumeric, :hex, :printable
+      # @return [#call]
+      def self.string(length: 1..20, charset: :alpha) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+        chars = case charset
+                when :alpha        then ("a".."z").to_a + ("A".."Z").to_a
+                when :alphanumeric then ("a".."z").to_a + ("A".."Z").to_a + ("0".."9").to_a
+                when :hex          then ("0".."9").to_a + ("a".."f").to_a
+                when :printable    then (32..126).map(&:chr)
+                else raise ArgumentError, "Unknown charset: #{charset}"
+                end
+
+        lambda do
+          len = length.is_a?(Range) ? rand(length) : length
+          Array.new(len) { chars.sample }.join
+        end
+      end
+
+      # Returns one of the supplied values at random.
+      #
+      # @param values [Array]
+      # @return [#call]
+      def self.one_of(*values)
+        raise ArgumentError, "one_of requires at least one value" if values.empty?
+
+        -> { values.sample }
+      end
+
+      # Generates an array of values produced by the given generator.
+      #
+      # @param generator [#call]
+      # @param size [Range<Integer>, Integer]
+      # @return [#call]
+      def self.array(generator, size: 0..10)
+        lambda do
+          len = size.is_a?(Range) ? rand(size) : size
+          Array.new(len) { generator.call }
+        end
+      end
+
+      # @return [#call]
+      def self.boolean
+        -> { [true, false].sample }
+      end
+
+      # Wraps another generator, occasionally returning nil.
+      #
+      # @param generator [#call]
+      # @param null_rate [Float] probability of nil (0.0..1.0)
+      # @return [#call]
+      def self.nullable(generator, null_rate: 0.1)
+        -> { rand < null_rate ? nil : generator.call }
+      end
+
+      # Generates a Hash where each key maps to a generated value.
+      #
+      # @param fields [Hash{Symbol => #call}]
+      # @return [#call]
+      def self.hash_of(**fields)
+        -> { fields.transform_values(&:call) }
+      end
+
+      # Always returns the same constant value. Useful for pinning one input
+      # while randomising others.
+      #
+      # @param value [Object]
+      # @return [#call]
+      def self.constant(value)
+        -> { value }
+      end
+    end
+  end
+end

data/lib/igniter/property_testing/result.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Igniter
+  module PropertyTesting
+    # Aggregated result of a full property-test run.
+    class Result
+      attr_reader :contract_class, :total_runs, :runs
+
+      def initialize(contract_class:, total_runs:, runs:)
+        @contract_class = contract_class
+        @total_runs     = total_runs
+        @runs           = runs.freeze
+      end
+
+      def passed?     = failed_runs.empty?
+      def failed_runs = runs.select(&:failed?)
+      def passed_runs = runs.select(&:passed?)
+
+      # The first failing run — the counterexample to inspect and debug.
+      # nil when all runs passed.
+      #
+      # @return [Run, nil]
+      def counterexample = failed_runs.first
+
+      # @return [String]
+      def explain = Formatter.new(self).render
+
+      # @return [Hash]
+      def to_h # rubocop:disable Metrics/MethodLength
+        {
+          contract: contract_class.name,
+          total_runs: total_runs,
+          passed: passed_runs.size,
+          failed: failed_runs.size,
+          passed?: passed?,
+          counterexample: counterexample && {
+            run_number: counterexample.run_number,
+            inputs: counterexample.inputs,
+            failure: counterexample.failure_message
+          }
+        }
+      end
+    end
+  end
+end

data/lib/igniter/property_testing/run.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Igniter
+  module PropertyTesting
+    # Result of a single property-test execution.
+    #
+    # A run can fail in two ways:
+    #   - :execution_error  — the contract raised an error
+    #   - :invariant_violation — the contract completed but an invariant was violated
+    class Run
+      attr_reader :run_number, :inputs, :execution_error, :violations
+
+      def initialize(run_number:, inputs:, execution_error: nil, violations: [])
+        @run_number      = run_number
+        @inputs          = inputs.freeze
+        @execution_error = execution_error
+        @violations      = violations.freeze
+        freeze
+      end
+
+      def passed? = execution_error.nil? && violations.empty?
+      def failed? = !passed?
+
+      # @return [Symbol, nil] :execution_error, :invariant_violation, or nil
+      def failure_type
+        if execution_error
+          :execution_error
+        elsif violations.any?
+          :invariant_violation
+        end
+      end
+
+      # @return [String, nil]
+      def failure_message
+        if execution_error
+          execution_error.message
+        elsif violations.any?
+          violations.map { |v| ":#{v.name} violated" }.join(", ")
+        end
+      end
+    end
+  end
+end

data/lib/igniter/property_testing/runner.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Igniter
+  module PropertyTesting
+    # Executes a contract repeatedly with random inputs and collects run results.
+    #
+    # Invariant violations are captured as data (not exceptions) using the
+    # Thread.current[:igniter_skip_invariants] flag, which prevents the
+    # automatic raise in resolve_all.
+    class Runner
+      def initialize(contract_class, generators:, runs: 100, seed: nil)
+        @contract_class = contract_class
+        @generators     = generators
+        @total_runs     = runs
+        @seed           = seed
+      end
+
+      # @return [Result]
+      def run
+        Random.srand(@seed) if @seed
+
+        runs = (1..@total_runs).map { |n| execute_run(n) }
+        Result.new(contract_class: @contract_class, total_runs: @total_runs, runs: runs)
+      end
+
+      private
+
+      def execute_run(run_number)
+        inputs   = generate_inputs
+        contract = @contract_class.new(**inputs)
+
+        Thread.current[:igniter_skip_invariants] = true
+        contract.resolve_all
+        violations = contract.check_invariants
+        Run.new(run_number: run_number, inputs: inputs, violations: violations)
+      rescue StandardError => e
+        Run.new(run_number: run_number, inputs: inputs, execution_error: e)
+      ensure
+        Thread.current[:igniter_skip_invariants] = false
+      end
+
+      def generate_inputs
+        @generators.transform_values(&:call)
+      end
+    end
+  end
+end

data/lib/igniter/property_testing.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "igniter"
+require "igniter/extensions/invariants"
+require "igniter/property_testing/generators"
+require "igniter/property_testing/run"
+require "igniter/property_testing/result"
+require "igniter/property_testing/formatter"
+require "igniter/property_testing/runner"
+
+module Igniter
+  # Property-based testing for Igniter contracts.
+  #
+  # Generates hundreds of random inputs, runs the contract with each set,
+  # and verifies that all declared invariants hold. Violations are collected
+  # as data so you can inspect the first counterexample.
+  #
+  # @example
+  #   require "igniter/property_testing"
+  #
+  #   G = Igniter::PropertyTesting::Generators
+  #
+  #   class PricingContract < Igniter::Contract
+  #     define do
+  #       input  :price
+  #       input  :quantity
+  #       compute :total, depends_on: %i[price quantity] do |price:, quantity:|
+  #         price * quantity
+  #       end
+  #       output :total
+  #     end
+  #
+  #     invariant(:total_non_negative) { |total:, **| total >= 0 }
+  #   end
+  #
+  #   result = PricingContract.property_test(
+  #     generators: { price: G.float(0.0..500.0), quantity: G.positive_integer(max: 100) },
+  #     runs: 200,
+  #     seed: 42
+  #   )
+  #
+  #   puts result.explain
+  #   puts result.counterexample&.inputs
+  #
+  module PropertyTesting
+    # Class methods added to every Igniter::Contract subclass.
+    module ClassMethods
+      # Run the contract against randomly generated inputs and verify invariants.
+      #
+      # Requires at least one `invariant` to be declared on the contract class,
+      # though it will still execute and collect execution errors without any.
+      #
+      # @param generators [Hash{Symbol => #call}] input name → generator callable
+      # @param runs [Integer] number of test runs (default: 100)
+      # @param seed [Integer, nil] optional RNG seed for reproducibility
+      # @return [Igniter::PropertyTesting::Result]
+      def property_test(generators:, runs: 100, seed: nil)
+        Runner.new(self, generators: generators, runs: runs, seed: seed).run
+      end
+    end
+  end
+end
+
+Igniter::Contract.extend(Igniter::PropertyTesting::ClassMethods)

data/lib/igniter/provenance/builder.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Provenance
+    # Builds a Lineage object for a named output by traversing the compiled
+    # graph and reading resolved values from the execution cache.
+    #
+    # The builder memoises each NodeTrace so that shared dependencies
+    # (diamond patterns) point to the same object rather than being duplicated.
+    class Builder
+      class << self
+        # Build lineage for +output_name+ from a resolved +execution+.
+        def build(output_name, execution)
+          new(execution).build(output_name)
+        end
+      end
+
+      def initialize(execution)
+        @graph = execution.compiled_graph
+        @cache = execution.cache
+      end
+
+      def build(output_name) # rubocop:disable Metrics/MethodLength
+        sym = output_name.to_sym
+
+        raise ProvenanceError, "No output named '#{sym}' in #{@graph.name}" unless @graph.output?(sym)
+
+        output_node = @graph.fetch_output(sym)
+        source_name = output_node.source_root
+
+        source_node = begin
+          @graph.fetch_node(source_name)
+        rescue KeyError
+          raise ProvenanceError, "Source node '#{source_name}' for output '#{sym}' not found in graph"
+        end
+
+        trace = build_trace(source_node, {})
+        Lineage.new(trace)
+      end
+
+      private
+
+      # Recursively build a NodeTrace for +node+.
+      # +memo+ prevents re-processing the same node in diamond-dependency graphs.
+      def build_trace(node, memo) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        return memo[node.name] if memo.key?(node.name)
+
+        # Reserve the slot to handle (unlikely) circular edge during traversal
+        memo[node.name] = nil
+
+        state = @cache.fetch(node.name)
+        value = extract_value(state)
+
+        contributing = {}
+        node.dependencies.each do |dep_name|
+          dep_node = safe_fetch_node(dep_name)
+          next unless dep_node
+
+          contributing[dep_name] = build_trace(dep_node, memo)
+        end
+
+        trace = NodeTrace.new(
+          name: node.name,
+          kind: node.kind,
+          value: value,
+          contributing: contributing
+        )
+        memo[node.name] = trace
+        trace
+      end
+
+      def safe_fetch_node(name)
+        @graph.fetch_node(name)
+      rescue KeyError
+        nil
+      end
+
+      # Extract a display-friendly value from a NodeState.
+      # Composition/Collection results are summarised as hashes.
+      def extract_value(state) # rubocop:disable Metrics/MethodLength
+        return nil unless state
+
+        val = state.value
+        case val
+        when Runtime::Result
+          val.to_h
+        when Runtime::CollectionResult
+          val.summary
+        when Runtime::DeferredResult
+          { pending: true, event: val.waiting_on }
+        else
+          val
+        end
+      end
+    end
+  end
+end

data/lib/igniter/provenance/lineage.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Provenance
+    # Lineage captures the full provenance of a single contract output.
+    #
+    # It wraps the NodeTrace tree rooted at the node that produces the output
+    # and exposes query methods for understanding what inputs shaped the result.
+    #
+    # Usage (after `require "igniter/extensions/provenance"`):
+    #
+    #   contract.resolve_all
+    #   lin = contract.lineage(:grand_total)
+    #
+    #   lin.value                      # => 229.95
+    #   lin.contributing_inputs        # => { base_price: 100.0, quantity: 2, ... }
+    #   lin.sensitive_to?(:base_price) # => true
+    #   lin.sensitive_to?(:user_name)  # => false
+    #   lin.path_to(:base_price)       # => [:grand_total, :subtotal, :unit_price, :base_price]
+    #   puts lin                        # prints ASCII tree
+    #
+    class Lineage
+      # The NodeTrace rooted at the output's source computation node.
+      attr_reader :trace
+
+      def initialize(trace)
+        @trace = trace
+        freeze
+      end
+
+      # The output name (same as the root trace node name).
+      def output_name
+        trace.name
+      end
+
+      # The resolved output value.
+      def value
+        trace.value
+      end
+
+      # All :input nodes that transitively contributed to this output.
+      # Returns Hash{ Symbol => value }.
+      def contributing_inputs
+        trace.contributing_inputs
+      end
+
+      # Does this output's value depend (transitively) on the given input?
+      def sensitive_to?(input_name)
+        trace.sensitive_to?(input_name)
+      end
+
+      # Ordered path of node names from the output down to the given input.
+      # Returns nil if the input does not contribute to this output.
+      def path_to(input_name)
+        trace.path_to(input_name)
+      end
+
+      # Human-readable ASCII tree explaining how this output was derived.
+      def explain
+        TextFormatter.format(trace)
+      end
+
+      alias to_s explain
+
+      # Structured (serialisable) representation of the full trace tree.
+      def to_h
+        serialize_trace(trace)
+      end
+
+      private
+
+      def serialize_trace(trc)
+        {
+          node: trc.name,
+          kind: trc.kind,
+          value: trc.value,
+          contributing: trc.contributing.transform_values { |dep| serialize_trace(dep) }
+        }
+      end
+    end
+  end
+end

data/lib/igniter/provenance/node_trace.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Provenance
+    # Immutable snapshot of a single resolved node and its full dependency chain.
+    #
+    # The tree structure mirrors the contract's dependency graph: each NodeTrace
+    # holds the traced values of all the nodes that contributed to its result.
+    # Input nodes are leaves (no contributing dependencies).
+    #
+    # The tree may share nodes (diamond dependencies in the original graph) but
+    # each shared node is memoised once by the Builder, so the same NodeTrace
+    # object is referenced from multiple parents — it is NOT duplicated.
+    class NodeTrace
+      attr_reader :name, :kind, :value, :contributing
+
+      # contributing: Hash{ Symbol => NodeTrace } — may be empty for leaf inputs
+      def initialize(name:, kind:, value:, contributing: {})
+        @name        = name.to_sym
+        @kind        = kind.to_sym
+        @value       = value
+        @contributing = contributing.freeze
+        freeze
+      end
+
+      def input?
+        kind == :input
+      end
+
+      # True when this node has no dependencies that contributed to its value.
+      def leaf?
+        contributing.empty?
+      end
+
+      # Recursively collect all :input nodes that influenced this trace.
+      # Returns Hash{ Symbol => value }.
+      def contributing_inputs
+        return { name => value } if input?
+
+        contributing.each_value.with_object({}) do |dep, acc|
+          acc.merge!(dep.contributing_inputs)
+        end
+      end
+
+      # Does this trace transitively depend on the named input?
+      def sensitive_to?(input_name)
+        contributing_inputs.key?(input_name.to_sym)
+      end
+
+      # Return the ordered path of node names from this node down to the given
+      # input, or nil if the input does not contribute to this node.
+      def path_to(input_name)
+        target = input_name.to_sym
+        return [name] if name == target
+
+        contributing.each_value do |dep|
+          sub_path = dep.path_to(target)
+          return [name] + sub_path if sub_path
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/igniter/provenance/text_formatter.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Provenance
+    # Renders a NodeTrace tree as a human-readable ASCII tree.
+    #
+    # Example output:
+    #
+    #   grand_total = 229.95  [compute]
+    #   ├─ subtotal = 199.96  [compute]
+    #   │  ├─ unit_price = 99.98  [compute]
+    #   │  │  └─ base_price = 100.0  [input]
+    #   │  └─ quantity = 2  [input]
+    #   └─ shipping_cost = 29.99  [compute]
+    #      └─ destination = "US"  [input]
+    #
+    module TextFormatter
+      VALUE_MAX_LENGTH = 60
+
+      def self.format(trace)
+        lines = []
+        render(trace, lines, prefix: "", is_root: true, is_last: true)
+        lines.join("\n")
+      end
+
+      # ── private helpers ──────────────────────────────────────────────────────
+
+      def self.render(trace, lines, prefix:, is_root:, is_last:) # rubocop:disable Metrics/MethodLength
+        if is_root
+          connector = ""
+          child_pad = ""
+        elsif is_last
+          connector = "└─ "
+          child_pad = "   "
+        else
+          connector = "├─ "
+          child_pad = "│  "
+        end
+        child_prefix = prefix + child_pad
+
+        lines << "#{prefix}#{connector}#{trace.name} = #{format_value(trace.value)}  [#{trace.kind}]"
+
+        deps = trace.contributing.values
+        deps.each_with_index do |dep, idx|
+          render(dep, lines,
+                 prefix: child_prefix,
+                 is_root: false,
+                 is_last: idx == deps.size - 1)
+        end
+      end
+      private_class_method :render
+
+      def self.format_value(value) # rubocop:disable Metrics/CyclomaticComplexity
+        str = case value
+              when nil    then "nil"
+              when String then value.inspect
+              when Symbol then value.inspect
+              when Hash   then "{#{value.map { |k, v| "#{k}: #{v.inspect}" }.join(", ")}}"
+              when Array  then "[#{value.map(&:inspect).join(", ")}]"
+              else             value.inspect
+              end
+
+        return str if str.length <= VALUE_MAX_LENGTH
+
+        "#{str[0, VALUE_MAX_LENGTH - 3]}..."
+      end
+      private_class_method :format_value
+    end
+  end
+end