igniter 0.5.0 → 0.5.2

data/lib/igniter/property_testing/generators.rb

@@ -1,115 +0,0 @@
-# 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

@@ -1,45 +0,0 @@
-# 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

@@ -1,43 +0,0 @@
-# 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

@@ -1,47 +0,0 @@
-# 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

@@ -1,64 +0,0 @@
-# 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

@@ -1,97 +0,0 @@
-# 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

@@ -1,82 +0,0 @@
-# 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

@@ -1,65 +0,0 @@
-# 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

@@ -1,70 +0,0 @@
-# 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

data/lib/igniter/provenance.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "provenance/node_trace"
-require_relative "provenance/text_formatter"
-require_relative "provenance/lineage"
-require_relative "provenance/builder"
-
-module Igniter
-  # Provenance — runtime data lineage for Igniter contracts.
-  #
-  # After a contract has been resolved, provenance lets you ask:
-  #   "How was this output value computed, and which inputs influenced it?"
-  #
-  # Usage:
-  #   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.path_to(:base_price)         # => [:grand_total, :subtotal, :base_price]
-  #   puts lin                          # ASCII tree
-  #
-  module Provenance
-    class ProvenanceError < Igniter::Error; end
-  end
-end