specproof 0.1.0

data/lib/specproof/collector.rb

@@ -0,0 +1,304 @@
+# frozen_string_literal: true
+
+require_relative "target_name"
+
+module SpecProof
+  # Captures method calls during a test run and matches them to obligations.
+  class Collector
+    # `method` is part of the collector's internal target record.
+    # rubocop:disable-next Lint/StructNewOverride
+    Target = Struct.new(:name, :owner, :constant_names, :method_owner, :method_name, :method, :method_ids, :input_names,
+                        keyword_init: true)
+
+    def initialize(specifications:, observer:)
+      @specifications = specifications
+      @observer = observer
+      @issues = []
+      @issue_keys = {}
+      @disabled_targets = {}
+      @tracepoint = nil
+      @pid = nil
+      @thread = nil
+    end
+
+    def start
+      raise_configuration_error("collector is already started", code: "collector_already_started") if enabled?
+
+      targets = @specifications.map { |specification| build_target(specification) }
+      duplicate = targets.group_by(&:name).find { |_name, entries| entries.length > 1 }
+      if duplicate
+        raise_configuration_error("duplicate target #{duplicate.first}", target: duplicate.first,
+                                                                         code: "duplicate_target")
+      end
+
+      duplicate_binding = {}
+      targets.each do |target|
+        target.method_ids.each do |method_id|
+          binding = [target.method_owner, method_id]
+          if duplicate_binding.key?(binding)
+            raise_configuration_error("multiple targets resolve to the same runtime method binding",
+                                      target: target.name, code: "duplicate_binding")
+          end
+
+          duplicate_binding[binding] = target
+        end
+      end
+
+      @targets = targets.to_h { |target| [target.name, target] }
+      @target_methods = duplicate_binding
+      @disabled_targets = {}
+      @pid = Process.pid
+      @thread = Thread.current
+      @tracepoint = TracePoint.new(:call) { |trace| collect(trace) }
+      @tracepoint.enable
+      self
+    rescue StandardError => e
+      @tracepoint&.disable
+      @tracepoint = nil
+      @targets = nil
+      @target_methods = nil
+      raise if configuration_error?(e)
+
+      raise_configuration_error("collector could not start: #{e.class}", code: "collector_start_failed")
+    end
+
+    def stop
+      tracepoint = @tracepoint
+      return nil unless tracepoint
+
+      begin
+        tracepoint.disable
+      ensure
+        @tracepoint = nil
+        @targets&.each_value do |target|
+          report_redefinition(target)
+          report_binding_change(target)
+        end
+        @target_methods = nil
+        @pid = nil
+        @thread = nil
+      end
+      nil
+    end
+
+    def enabled?
+      @tracepoint&.enabled? || false
+    end
+
+    def issues
+      @issues.map { |issue| issue.dup.freeze }.freeze
+    end
+
+    private
+
+    def build_target(specification)
+      target_name = specification.target
+      unless target_name.is_a?(String) && !target_name.empty?
+        raise_configuration_error("target must be a non-empty String", code: "invalid_target")
+      end
+
+      owner, owner_names, method_owner, method_symbol, method = resolve_target(target_name)
+
+      input_names, exclusion_names = declaration_names(specification, target_name)
+
+      parameters = method.parameters
+      unless parameters.all? { |kind, _name| %i[req opt keyreq key].include?(kind) }
+        raise_configuration_error("#{target_name} may only use named positional or keyword parameters",
+                                  target: target_name, code: "unsupported_parameters")
+      end
+
+      declared_names = parameters.map(&:last)
+      input_names_match = specification.inputs.all? { |name, input| input.name == name }
+      names_match = valid_parameter_names?(declared_names, input_names, exclusion_names)
+      unless names_match && input_names_match
+        raise_configuration_error("#{target_name} parameters must exactly match analyzed and excluded input names",
+                                  target: target_name, code: "parameter_mismatch")
+      end
+
+      method_ids = method_owner.public_instance_methods(false).select do |candidate|
+        method_owner.instance_method(candidate) == method
+      rescue NameError
+        false
+      end
+
+      Target.new(
+        name: target_name.freeze,
+        owner: owner,
+        constant_names: owner_names.map(&:freeze).freeze,
+        method_owner: method_owner,
+        method_name: method_symbol,
+        method: method,
+        method_ids: method_ids.freeze,
+        input_names: declared_names.select { |name| input_names.include?(name) }.freeze
+      ).freeze
+    end
+
+    def resolve_target(target_name)
+      owner_name, method_name, kind = TargetName.parse(target_name)
+      owner_names = owner_name.delete_prefix("::").split("::")
+      owner = resolve_class(owner_names, target_name)
+      unless owner.is_a?(Module) && (kind == :singleton || owner.is_a?(Class))
+        raise_configuration_error("target owner must be a named Class or Module",
+                                  target: target_name, code: "invalid_target_owner")
+      end
+
+      method_owner = kind == :singleton ? owner.singleton_class : owner
+      method_symbol = method_name.to_sym
+      unless method_owner.public_method_defined?(method_symbol, false)
+        visibility = kind == :singleton ? "public singleton method" : "public instance method"
+        raise_configuration_error("#{target_name} must name a directly defined #{visibility}",
+                                  target: target_name, code: "invalid_method")
+      end
+
+      method = method_owner.instance_method(method_symbol)
+      unless method.owner == method_owner && method.original_name == method_symbol
+        raise_configuration_error("#{target_name} cannot name an inherited or aliased method", target: target_name,
+                                                                                               code: "invalid_method")
+      end
+      if method.source_location.nil?
+        raise_configuration_error("#{target_name} must have a Ruby source location", target: target_name,
+                                                                                     code: "invalid_method")
+      end
+
+      [owner, owner_names, method_owner, method_symbol, method]
+    end
+
+    def declaration_names(specification, target_name)
+      input_names = specification.inputs.keys
+      exclusions = specification.respond_to?(:exclusions) ? specification.exclusions : {}
+      exclusion_names = exclusions.keys
+      unless input_names.all?(Symbol)
+        raise_configuration_error("#{target_name} inputs must use symbol names", target: target_name,
+                                                                                 code: "invalid_inputs")
+      end
+      unless exclusion_names.all?(Symbol) && exclusions.all? do |name, item|
+        item.name == name && item.reason.is_a?(String) && !item.reason.strip.empty?
+      end
+        raise_configuration_error("#{target_name} exclusions must have valid names and reasons",
+                                  target: target_name, code: "invalid_exclusions")
+      end
+      [input_names, exclusion_names]
+    end
+
+    def valid_parameter_names?(declared_names, input_names, exclusion_names)
+      declared_names.none?(&:nil?) && declared_names.sort == (input_names | exclusion_names).sort &&
+        !input_names.intersect?(exclusion_names)
+    end
+
+    def resolve_class(constant_names, target_name)
+      value = Object
+      constant_names.each do |constant_name|
+        symbol = constant_name.to_sym
+        if value.autoload?(symbol)
+          raise_configuration_error("#{target_name} cannot resolve an autoloaded constant", target: target_name,
+                                                                                            code: "autoloaded_target")
+        end
+        unless value.const_defined?(symbol, false)
+          raise_configuration_error("#{target_name} references an undefined constant", target: target_name,
+                                                                                       code: "undefined_target")
+        end
+
+        value = value.const_get(symbol, false)
+      end
+      value
+    end
+
+    def collect(trace)
+      return unless Process.pid == @pid && Thread.current.equal?(@thread)
+
+      target = @target_methods[[trace.defined_class, trace.method_id]]
+      return unless target
+      return if target.method_owner != trace.defined_class
+      return if @disabled_targets[target.name]
+
+      unless method_unchanged?(target)
+        disable_target(target, "target_redefined")
+        return
+      end
+
+      arguments = copy_arguments(trace, target)
+      @observer.observe(target: target.name, arguments: arguments)
+    rescue StandardError => e
+      disable_target(target, error_code(e)) if target
+    end
+
+    def copy_arguments(trace, target)
+      binding = trace.binding
+      target.input_names.to_h do |name|
+        value = binding.local_variable_get(name)
+        raise ArgumentError, "non_primitive_argument" unless primitive?(value)
+
+        [name, Domains.supported_string?(value) ? Domains.canonical_string(value) : value]
+      end.freeze
+    end
+
+    def primitive?(value)
+      Domains.primitive?(value)
+    end
+
+    def error_code(error)
+      return "non_primitive_argument" if error.message == "non_primitive_argument"
+      return "binding_failure" if error.is_a?(NameError)
+
+      "observer_error"
+    end
+
+    def disable_target(target, code)
+      @disabled_targets[target.name] = true
+      add_issue(target.name, code, "collector disabled this target after an observation failure")
+    end
+
+    def report_redefinition(target)
+      return if method_unchanged?(target)
+
+      add_issue(target.name, "target_redefined", "target method changed while collection was active")
+    end
+
+    def report_binding_change(target)
+      return if target_binding_unchanged?(target)
+
+      add_issue(target.name, "target_binding_changed", "target constant binding changed while collection was active")
+    end
+
+    def target_binding_unchanged?(target)
+      value = Object
+      target.constant_names.each do |constant_name|
+        return false unless value.is_a?(Module)
+
+        symbol = constant_name.to_sym
+        return false if value.autoload?(symbol) || !value.const_defined?(symbol, false)
+
+        value = value.const_get(symbol, false)
+      end
+      value.equal?(target.owner)
+    rescue NameError
+      false
+    end
+
+    def method_unchanged?(target)
+      target.method_owner.instance_method(target.method_name) == target.method
+    rescue NameError
+      false
+    end
+
+    def add_issue(target, code, message)
+      key = [target, code]
+      return if @issue_keys[key]
+
+      @issue_keys[key] = true
+      @issues << { target: target, code: code, message: message }.freeze
+    end
+
+    def raise_configuration_error(message, target: nil, code: "configuration_error")
+      add_issue(target, code, message)
+      error_class = SpecProof.const_get(:ConfigurationError, false)
+      raise error_class.new(message, code: code)
+    end
+
+    def configuration_error?(error)
+      error.is_a?(SpecProof.const_get(:ConfigurationError, false))
+    rescue NameError
+      false
+    end
+  end
+end

data/lib/specproof/combinations.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module SpecProof
+  # Collects static partial assignments declared in a combinations block.
+  class CombinationBuilder
+    attr_reader :forbidden
+
+    def initialize(names, source)
+      @names = names.freeze
+      @source = source
+      @forbidden = []
+    end
+
+    def in_partition(name)
+      source = Loader.call_source
+      unless name.is_a?(Symbol) && !name.to_s.empty?
+        raise ConfigurationError.new("partition reference name must be a non-empty symbol",
+                                     code: "invalid_partition_reference", source: source || @source)
+      end
+
+      PartitionReference.new(name)
+    end
+
+    def forbid(**assignments)
+      source = Loader.call_source
+      if assignments.empty?
+        raise ConfigurationError.new("forbid requires at least one assignment", code: "empty_forbidden_assignment",
+                                                                                source: source || @source)
+      end
+      unknown = assignments.keys - @names
+      unless unknown.empty?
+        raise ConfigurationError.new("forbidden assignment names non-group input #{unknown.first.inspect}",
+                                     code: "unknown_forbidden_input", source: source || @source)
+      end
+      unless assignments.values.all? { |value| Domains.primitive?(value) || value.is_a?(PartitionReference) }
+        raise ConfigurationError.new("forbidden values must be primitive values or whole partition references",
+                                     code: "unsupported_value", source: source || @source)
+      end
+
+      forbidden << ForbiddenAssignment.new(assignments: assignments, source: source || @source)
+    end
+  end
+
+  # Enumerates a bounded finite joint domain and the pair rows it permits.
+  class CombinationSpace
+    MAX_ASSIGNMENTS = 10_000
+    MAX_PAIR_ROWS = 10_000
+
+    attr_reader :pairs, :excluded_pairs, :allowed_count, :sources
+
+    def initialize(specification)
+      @specification = specification
+      @group = specification.combination_group
+      unless @group
+        raise ConfigurationError.new("target has no combinations declaration: #{specification.target}",
+                                     code: "combinations_required", source: specification.source)
+      end
+
+      validate_group
+      check_limits
+      enumerate
+    end
+
+    def allowed?(arguments)
+      normalized = arguments.each_with_object({}) do |(name, value), values|
+        values[name.to_sym] = canonical_value(value)
+      end
+      return false unless @group.inputs.all? do |name|
+        normalized.key?(name) && Domains.include?(@inputs.fetch(name).domain, normalized.fetch(name))
+      end
+
+      @group.forbidden.none? do |rule|
+        rule.assignments.all? do |name, value|
+          normalized.key?(name) && same_value?(normalized.fetch(name), value)
+        end
+      end
+    end
+
+    def allowed_assignments
+      @allowed_assignments ||= canonical_allowed_assignments
+    end
+
+    private
+
+    def validate_group
+      if @group.inputs.length < 2
+        raise ConfigurationError.new("a combinations group requires at least two inputs",
+                                     code: "invalid_combination_inputs", source: @group.source)
+      end
+
+      @inputs = group_inputs.freeze
+      validate_forbidden_assignments
+      collect_sources
+    end
+
+    def group_inputs
+      @group.inputs.to_h do |name|
+        input = @specification.inputs[name]
+        if @specification.exclusions.key?(name)
+          raise ConfigurationError.new("excluded input #{name.inspect} cannot be in a combinations group",
+                                       code: "excluded_combination_input", source: @group.source)
+        end
+        unless input
+          raise ConfigurationError.new("unknown combinations input #{name.inspect}",
+                                       code: "unknown_combination_input", source: @group.source)
+        end
+        unless input.domain.is_a?(FiniteDomain)
+          raise ConfigurationError.new("combinations input #{name.inspect} must have finite values",
+                                       code: "finite_combinations_required", source: input.source)
+        end
+        [name, input]
+      end
+    end
+
+    def validate_forbidden_assignments
+      @group.forbidden.each do |rule|
+        if rule.assignments.empty?
+          raise ConfigurationError.new("forbid requires at least one assignment",
+                                       code: "empty_forbidden_assignment", source: rule.source)
+        end
+        rule.assignments.each do |name, value|
+          input = @inputs[name]
+          unless input
+            raise ConfigurationError.new("forbidden assignment names non-group input #{name.inspect}",
+                                         code: "unknown_forbidden_input", source: rule.source)
+          end
+          if value.is_a?(PartitionReference)
+            raise ConfigurationError.new("partition reference for #{name.inspect} requires an integer input",
+                                         code: "partition_reference_requires_integer_input", source: rule.source)
+          end
+          unless Domains.primitive?(value) && Domains.include?(input.domain, value)
+            raise ConfigurationError.new("forbidden value #{value.inspect} is outside #{name.inspect}'s finite domain",
+                                         code: "invalid_combination_value", source: rule.source)
+          end
+        end
+      end
+    end
+
+    def collect_sources
+      @sources = ([@group.source] + @inputs.values.flat_map(&:sources) + @group.forbidden.map(&:source))
+                 .compact.uniq.sort_by { |source| [source.path, source.line, source.kind] }.freeze
+    end
+
+    def check_limits
+      assignment_count = @inputs.values.reduce(1) { |count, input| count * input.domain.values.length }
+      raise limit_error("complete assignments", assignment_count, @group.source) if assignment_count > MAX_ASSIGNMENTS
+
+      pair_rows = 0
+      @group.inputs.each_with_index do |left, index|
+        @group.inputs.drop(index + 1).each do |right|
+          pair_rows += @inputs.fetch(left).domain.values.length * @inputs.fetch(right).domain.values.length
+          raise limit_error("possible pair rows", pair_rows, @group.source) if pair_rows > MAX_PAIR_ROWS
+        end
+      end
+    end
+
+    def limit_error(kind, count, source)
+      ConfigurationError.new("combinations declaration has #{count} #{kind}; limit is #{MAX_ASSIGNMENTS}",
+                             code: "combination_limit_exceeded", source: source)
+    end
+
+    def enumerate
+      allowed = canonical_allowed_assignments
+      @allowed_count = allowed.length
+      pair_rows = {}
+      allowed.each do |assignment|
+        each_input_pair do |left, right|
+          row = { left => assignment.fetch(left), right => assignment.fetch(right) }.freeze
+          pair_rows[pair_key(row)] ||= row
+        end
+      end
+      @pairs = pair_rows.values.sort_by { |row| row_key(row) }.freeze
+      all_rows = []
+      each_input_pair do |left, right|
+        left_values = @inputs.fetch(left).domain.values
+        right_values = @inputs.fetch(right).domain.values
+        left_values.each do |left_value|
+          right_values.each do |right_value|
+            all_rows << { left => left_value, right => right_value }.freeze
+          end
+        end
+      end
+      feasible_keys = pair_rows.keys.to_h { |key| [key, true] }
+      @excluded_pairs = all_rows.reject { |row| feasible_keys.key?(pair_key(row)) }
+                                .sort_by { |row| row_key(row) }.freeze
+    end
+
+    def canonical_allowed_assignments
+      complete_assignments.select { |assignment| allowed?(assignment) }.map(&:freeze).freeze
+    end
+
+    def complete_assignments
+      return [] if @group.inputs.any? { |name| @inputs.fetch(name).domain.values.empty? }
+
+      rows = [{}]
+      @group.inputs.sort_by(&:to_s).each do |name|
+        rows = rows.flat_map do |row|
+          @inputs.fetch(name).domain.values.map { |value| row.merge(name => value) }
+        end
+      end
+      rows
+    end
+
+    def each_input_pair
+      @group.inputs.each_with_index do |left, index|
+        @group.inputs.drop(index + 1).each { |right| yield left, right }
+      end
+    end
+
+    def pair_key(row)
+      row.map { |name, value| [name.to_s, Report.value(value)] }
+    end
+
+    def row_key(row)
+      row.flat_map { |name, value| [name.to_s, Domains.sort_key(value)] }
+    end
+
+    def canonical_value(value)
+      Domains.supported_string?(value) ? Domains.canonical_string(value) : value
+    end
+
+    def same_value?(left, right)
+      left.instance_of?(right.class) && left.eql?(right)
+    end
+  end
+end

data/lib/specproof/composer.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module SpecProof
+  # Combines behavioral declarations with imported scalar input constraints.
+  module Composer
+    module_function
+
+    def compose(specifications:, type_facts:)
+      specifications_by_target = index_specifications(specifications)
+      facts_by_target = index_type_facts(type_facts)
+
+      targets = (specifications_by_target.keys | facts_by_target.keys).sort
+      targets.map do |target|
+        specification = specifications_by_target[target]
+        target_facts = facts_by_target.fetch(target, {})
+        exclusions = specification&.exclusions || {}
+        conflict = target_facts.keys & exclusions.keys
+        unless conflict.empty?
+          name = conflict.min_by(&:to_s)
+          raise ConfigurationError.new("type fact collides with excluded input #{target} / #{name}",
+                                       code: "input_exclusion_overlap", source: target_facts.fetch(name).source)
+        end
+        input_names = ((specification&.inputs&.keys || []) | target_facts.keys).sort_by(&:to_s)
+        inputs = input_names.to_h do |name|
+          [name, compose_input(target, name, specification&.inputs&.[](name), target_facts[name])]
+        end
+        source = specification&.source || canonical_source(target_facts.values.map(&:source))
+        if inputs.empty?
+          raise ConfigurationError.new(
+            "target must declare at least one analyzed input: #{target}", code: "inputs_required", source: source
+          )
+        end
+        composed = Specification.new(target: target, inputs: inputs, exclusions: exclusions,
+                                     combination_group: specification&.combination_group, source: source)
+        PartitionSpace.for_specification(composed, validate_geometry: false) if composed.combination_group
+        composed
+      end.freeze
+    end
+
+    def index_specifications(specifications)
+      specifications.each_with_object({}) do |specification, index|
+        previous = index[specification.target]
+        next index[specification.target] = specification unless previous
+
+        sources = [previous.source, specification.source].compact.uniq.sort_by { |source| source_key(source) }
+        locations = sources.map { |source| "#{source.path}:#{source.line}" }.join(", ")
+        raise ConfigurationError.new("duplicate target #{specification.target} (#{locations})",
+                                     code: "duplicate_target", source: specification.source)
+      end
+    end
+    private_class_method :index_specifications
+
+    def index_type_facts(type_facts)
+      type_facts.each_with_object(Hash.new { |targets, target| targets[target] = {} }) do |fact, index|
+        target_facts = index[fact.target]
+        if target_facts.key?(fact.input)
+          previous = target_facts.fetch(fact.input)
+          sources = [previous.source, fact.source].compact.uniq.sort_by { |source| source_key(source) }
+          locations = sources.map { |source| "#{source.path}:#{source.line}" }.join(", ")
+          raise ConfigurationError.new("duplicate type fact for #{fact.target} / #{fact.input} (#{locations})",
+                                       code: "duplicate_type_fact", source: fact.source)
+        end
+        target_facts[fact.input] = fact
+      end
+    end
+    private_class_method :index_type_facts
+
+    def compose_input(target, name, input, fact)
+      return input unless fact
+
+      sources = [fact.source].compact.uniq.sort_by { |source| source_key(source) }
+      domain = input&.domain || TypeConstraints.finite_domain(fact.constraint)
+      unless domain
+        source = canonical_source(sources)
+        location = source ? " at #{source.path}:#{source.line}" : ""
+        message = "integer input needs a finite DSL domain refinement: #{target} / #{name}#{location}"
+        raise ConfigurationError.new(message, code: "domain_refinement_required", source: source)
+      end
+
+      Input.new(name: name, domain: domain, partitions: input&.partitions || [],
+                exhaustive: input&.exhaustive || false, disjoint: input&.disjoint || false,
+                source: input&.source || canonical_source(sources), type_constraint: fact.constraint,
+                type_sources: sources)
+    end
+    private_class_method :compose_input
+
+    def canonical_source(sources)
+      sources.compact.min_by { |source| source_key(source) }
+    end
+    private_class_method :canonical_source
+
+    def source_key(source)
+      [source.path, source.line, source.kind]
+    end
+    private_class_method :source_key
+  end
+end