bparity 0.1.0

data/fixtures/scenarios/03_external_boundary/spec/receipt_spec.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "rspec"
+require_relative "../legacy/receipt"
+
+RSpec.describe Legacy::Receipt do
+  it "renders money through the retired formatter" do
+    expect(described_class.new.print(1_200)).to eq("Total: $12")
+  end
+end

data/fixtures/scenarios/04_intentional_divergence/adapter.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+Bparity.adapter do
+  subject "Identity" do
+    construct { Replacement::Identity }
+    operation "#label" do
+      invoke { |identity, args, _kwargs| identity.display(value: args.fetch(0)) }
+    end
+  end
+  waive "bc-000001", reason: "The replacement uses inclusive terminology",
+                     approved_by: "migration-owner", approved_at: "2026-08-28"
+end

data/fixtures/scenarios/04_intentional_divergence/adapter_unwaived.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+Bparity.adapter do
+  subject "Identity" do
+    construct { Replacement::Identity }
+    operation "#label" do
+      invoke { |identity, args, _kwargs| identity.display(value: args.fetch(0)) }
+    end
+  end
+end

data/fixtures/scenarios/04_intentional_divergence/boundary.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+Bparity.boundary do
+  observe "Legacy::Identity" do
+    methods :label
+  end
+  driver :rspec, files: "fixtures/scenarios/04_intentional_divergence/spec/**/*_spec.rb"
+end

data/fixtures/scenarios/04_intentional_divergence/legacy/dead_identity.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RetiredIdentity
+  module_function
+
+  def guest_name = "guest"
+end

data/fixtures/scenarios/04_intentional_divergence/legacy/identity.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "dead_identity"
+
+module Legacy
+  class Identity
+    def label(name) = name || RetiredIdentity.guest_name
+  end
+end

data/fixtures/scenarios/04_intentional_divergence/replacement/broken.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Replacement
+  module Identity
+    module_function
+
+    def display(value:) = value || "anonymous"
+  end
+end

data/fixtures/scenarios/04_intentional_divergence/replacement/good.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Replacement
+  module Identity
+    module_function
+
+    def display(value:) = value || "guest"
+  end
+end

data/fixtures/scenarios/04_intentional_divergence/spec/identity_spec.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "rspec"
+require_relative "../legacy/identity"
+
+RSpec.describe Legacy::Identity do
+  it "uses the legacy guest label" do
+    expect(described_class.new.label(nil)).to eq("guest")
+  end
+end

data/fixtures/scenarios/05_formal_negative/adapter.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+Bparity.adapter do
+  subject "PureToken" do
+    construct { Replacement::PureTokenService }
+    operation("#token") { invoke { |service, args, _kwargs| service.shift(*args) } }
+  end
+  subject "Turnstile" do
+    construct { Replacement::Gate.new }
+    state { |gate| { locked: gate.phase == :secured } }
+    operation("#unlock") { invoke { |gate, _args, _kwargs| gate.release } }
+    operation("#lock") { invoke { |gate, _args, _kwargs| gate.secure } }
+    operation("#enter") { invoke { |gate, _args, _kwargs| gate.pass } }
+  end
+end

data/fixtures/scenarios/05_formal_negative/boundary.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+Bparity.boundary do
+  observe "Legacy::PureToken" do
+    methods :token
+  end
+  observe "Legacy::Turnstile" do
+    methods :unlock, :lock, :enter
+    state { |turnstile| { locked: turnstile.locked } }
+  end
+  driver :rspec, files: "fixtures/scenarios/05_formal_negative/spec/**/*_spec.rb"
+  formal do
+    pure_fragment "Legacy::PureToken#token"
+    lts_learning :active
+  end
+end

data/fixtures/scenarios/05_formal_negative/legacy/dead_lock.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RetiredLock
+  DEFAULT_LOCKED = true
+end

data/fixtures/scenarios/05_formal_negative/legacy/turnstile.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "dead_lock"
+
+module Legacy
+  class PureToken
+    def token(value) = value + 1
+  end
+
+  class Turnstile
+    attr_reader :locked
+
+    def initialize = @locked = RetiredLock::DEFAULT_LOCKED
+    def unlock = (@locked = false; :ok)
+    def lock = (@locked = true; :ok)
+
+    def enter
+      return :denied if locked
+
+      @locked = true
+      :entered
+    end
+  end
+end

data/fixtures/scenarios/05_formal_negative/replacement/broken.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Replacement
+  module PureTokenService
+    module_function
+
+    def shift(value) = value + 1
+  end
+
+  class Gate
+    attr_reader :phase
+
+    def initialize = @phase = :secured
+    def release = (@phase = :open; :ok)
+    def secure = (@phase = :secured; :ok)
+    def pass = phase == :secured ? :denied : :entered
+  end
+end

data/fixtures/scenarios/05_formal_negative/replacement/formal_broken.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Replacement
+  module PureTokenService
+    module_function
+
+    def shift(value) = value + 2
+  end
+
+  class Gate
+    attr_reader :phase
+
+    def initialize = @phase = :secured
+    def release = (@phase = :open; :ok)
+    def secure = (@phase = :secured; :ok)
+
+    def pass
+      return :denied if phase == :secured
+
+      @phase = :secured
+      :entered
+    end
+  end
+end

data/fixtures/scenarios/05_formal_negative/replacement/good.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Replacement
+  module PureTokenService
+    module_function
+
+    def shift(value) = value + 1
+  end
+
+  class Gate
+    attr_reader :phase
+
+    def initialize = @phase = :secured
+    def release = (@phase = :open; :ok)
+    def secure = (@phase = :secured; :ok)
+
+    def pass
+      return :denied if phase == :secured
+
+      @phase = :secured
+      :entered
+    end
+  end
+end

data/fixtures/scenarios/05_formal_negative/spec/turnstile_spec.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "rspec"
+require_relative "../legacy/turnstile"
+
+RSpec.describe Legacy::Turnstile do
+  it "exposes a pure fragment for F2 and F4 negative checks" do
+    expect(Legacy::PureToken.new.token(1)).to eq(2)
+  end
+
+  it "covers every operation from locked and unlocked states" do
+    turnstile = described_class.new
+    expect(turnstile.lock).to eq(:ok)
+    expect(turnstile.enter).to eq(:denied)
+    expect(turnstile.unlock).to eq(:ok)
+    expect(turnstile.unlock).to eq(:ok)
+    expect(turnstile.lock).to eq(:ok)
+    expect(turnstile.unlock).to eq(:ok)
+    expect(turnstile.enter).to eq(:entered)
+  end
+end

data/lib/bparity/adapter.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Bparity
+  module Adapter
+    Operation = Struct.new(:name, :invoker, :return_mapper, :error_mapper, keyword_init: true) do
+      def invoke(subject, args, kwargs, &block)
+        return invoker.call(subject, args, kwargs, &block) if invoker
+
+        subject.public_send(name.delete_prefix("#"), *args, **kwargs, &block)
+      end
+
+      def map_return(value) = return_mapper ? return_mapper.call(value) : value
+
+      def map_error(error)
+        error_mapper ? error_mapper.call(error) : { class: error.class.name, message: Bparity.exception_message(error) }
+      end
+    end
+
+    class OperationDsl
+      def initialize(operation)
+        @operation = operation
+      end
+
+      def invoke(&block) = @operation.invoker = block
+      def map_return(&block) = @operation.return_mapper = block
+      def map_error(&block) = @operation.error_mapper = block
+    end
+
+    class Subject
+      attr_reader :name, :operations
+      attr_accessor :constructor, :state_projection
+
+      def initialize(name)
+        @name = name
+        @operations = {}
+      end
+
+      def construct(&block) = self.constructor = block
+      def state(&block) = self.state_projection = block
+
+      def operation(name, &block)
+        item = Operation.new(name: name)
+        OperationDsl.new(item).instance_eval(&block) if block
+        operations[name] = item
+      end
+
+      def build(context = {})
+        unless constructor
+          raise ConfigurationError, "Adapter subject #{name} has no constructor. Add a construct block to the adapter."
+        end
+
+        constructor.call(context)
+      end
+    end
+
+    Waiver = Struct.new(:id, :reason, :approved_by, :approved_at, keyword_init: true)
+
+    class External
+      attr_reader :source, :target, :call_mappers
+
+      def initialize(source, target)
+        @source = source
+        @target = target
+        @call_mappers = {}
+      end
+
+      def map_call(name, &block)
+        call_mappers[name.to_s] = block
+      end
+    end
+
+    class Definition
+      attr_reader :spec, :subjects, :waivers, :externals
+
+      def initialize(spec: nil)
+        @spec = spec
+        @subjects = {}
+        @waivers = {}
+        @externals = []
+      end
+
+      def subject(name, &block)
+        item = Subject.new(name)
+        item.instance_eval(&block) if block
+        subjects[name] = item
+      end
+
+      def waive(id, reason:, approved_by:, approved_at:)
+        values = { "id" => id, "reason" => reason, "approved_by" => approved_by, "approved_at" => approved_at }
+        missing = values.filter_map { |name, value| name if value.to_s.strip.empty? }
+        unless missing.empty?
+          raise ConfigurationError,
+                "Waiver metadata is missing #{missing.join(', ')}. Add an ID, reason, approver, and approval date."
+        end
+        begin
+          Date.iso8601(approved_at.to_s)
+        rescue Date::Error
+          raise ConfigurationError,
+                "Waiver #{id} has an invalid approval date. Use YYYY-MM-DD."
+        end
+
+        waivers[id] = Waiver.new(id:, reason:, approved_by:, approved_at:)
+      end
+
+      def external(mapping, &block)
+        source, target = mapping.first
+        item = External.new(source, target)
+        item.instance_eval(&block) if block
+        externals << item
+      end
+    end
+  end
+end

data/lib/bparity/adequacy.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Bparity
+  module Adequacy
+    class MutantBridge
+      SCORE = /Mutation coverage:\s*([\d.]+)%/
+
+      def available?
+        _output, _error, status = Open3.capture3("bundle", "exec", "mutant", "--version")
+        status.success?
+      rescue Errno::ENOENT
+        false
+      end
+
+      def run
+        return { "status" => "skipped", "reason" => "mutant is not installed" } unless available?
+
+        output, error, status = Open3.capture3("bundle", "exec", "mutant", "run")
+        match = output.match(SCORE)
+        score = match[1].to_f if match
+        { "status" => status.success? ? "completed" : "failed", "score" => score,
+          "output" => output, "error" => error }
+      end
+    end
+
+    module CoverageReconciler
+      module_function
+
+      def call(gaps:, surviving_mutants: [])
+        risks = gaps.map { |gap| "Legacy gap: #{gap['location'] || gap['note'] || gap['kind']}" }
+        risks + surviving_mutants.map { |mutant| "Unconstrained replacement behavior: #{mutant}" }
+      end
+    end
+
+    class Analyzer
+      def initialize(bundle:, results:, mutation: nil)
+        @bundle = bundle
+        @results = results
+        @mutation = mutation || { "status" => "skipped", "reason" => "not requested" }
+      end
+
+      def call
+        examples = @bundle.fetch("subjects").flat_map { |subject| subject.fetch("operations") }
+                          .flat_map { |operation| operation.fetch("examples") }
+        evaluated = @results.length
+        {
+          "specification_coverage" => ratio(evaluated, examples.length),
+          "recorded_examples" => examples.length,
+          "generated_checks" => generated_checks,
+          "formal_assurance" => Reporting::AssuranceMatrix.new(@bundle).to_h,
+          "constraint_strength" => @mutation,
+          "residual_risks" => CoverageReconciler.call(gaps: @bundle.fetch("gaps", []),
+                                                      surviving_mutants: mutation_risks),
+          "waiver_count" => @results.count { |result| result.status == :waived }
+        }
+      end
+
+      private
+
+      def generated_checks
+        @bundle.fetch("subjects").sum do |subject|
+          subject.fetch("operations").sum { |operation| operation.fetch("invariants", []).length }
+        end
+      end
+
+      def ratio(numerator, denominator) = denominator.zero? ? 1.0 : (numerator.to_f / denominator).round(4)
+
+      def mutation_risks
+        score = @mutation["score"]
+        return [] unless score && score < 100
+
+        ["mutation score #{score}% (inspect the mutant output for survivors)"]
+      end
+    end
+  end
+end

data/lib/bparity/boundary.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Bparity
+  module Boundary
+    Subject = Struct.new(:name, :method_names, :excluded, :state_projection, :return_projections, keyword_init: true) do
+      def initialize(name:, **)
+        super(name:, method_names: [], excluded: [], return_projections: {})
+      end
+
+      def methods(*names)
+        self.method_names = names.map(&:to_sym)
+      end
+
+      def exclude(*names)
+        self.excluded |= names.map(&:to_sym)
+      end
+
+      def state(&block)
+        self.state_projection = block
+      end
+
+      def project_return(class_name, &block)
+        return_projections[class_name] = block
+      end
+
+      def observed_methods(target)
+        (method_names.empty? ? target.public_instance_methods(false) : method_names) - excluded
+      end
+    end
+
+    External = Struct.new(:name, :method_names, keyword_init: true) do
+      def initialize(name:, **)
+        super(name:, method_names: [])
+      end
+
+      def methods(*names)
+        self.method_names = names.map(&:to_sym)
+      end
+    end
+
+    class Definition
+      attr_reader :subjects, :externals, :canonicalization, :driver_config, :formal_config
+
+      def initialize
+        @subjects = {}
+        @externals = {}
+        @canonicalization = {}
+        @formal_config = {}
+      end
+
+      def observe(name, &block)
+        subject = Subject.new(name: name)
+        subject.instance_eval(&block) if block
+        subjects[name] = subject
+      end
+
+      def external(name, &block)
+        item = External.new(name: name)
+        item.instance_eval(&block) if block
+        externals[name] = item
+      end
+
+      def canonicalize(&)
+        CanonicalizationDsl.new(canonicalization).instance_eval(&)
+      end
+
+      def driver(name, **options)
+        @driver_config = { name: name.to_sym, **options }
+      end
+
+      def formal(&)
+        FormalDsl.new(formal_config).instance_eval(&)
+      end
+    end
+
+    class CanonicalizationDsl
+      def initialize(config)
+        @config = config
+      end
+
+      def freeze_time(value) = @config[:freeze_time] = value
+      def random_seed(value) = @config[:random_seed] = value
+      def uuid_placeholder(value) = @config[:uuid_placeholder] = value
+      def float_tolerance(value) = @config[:float_tolerance] = value
+    end
+
+    class FormalDsl
+      def initialize(config)
+        @config = config
+      end
+
+      def pure_fragment(name) = (@config[:pure_fragments] ||= []) << name
+      def bounded_scope(**scope) = @config[:bounded_scope] = scope
+      def lts_learning(mode) = @config[:lts_learning] = mode
+    end
+  end
+end