perfgate 0.1.0

data/lib/perfgate/execution/runner.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "sample_context"
+require_relative "../fingerprints/workload_definition"
+
+module Perfgate
+  module Execution
+    # Executes a single workload's warmup and measured samples in the
+    # current process (spec section 12.2, steps 4-9). Process isolation
+    # across workloads is layered on top by ProcessRunner. SQL count/
+    # duration, allocations, and GC deltas are collected only inside the
+    # workload's explicit `Perfgate.measure` block; duration falls back
+    # to wall-clock timing of the whole workload when `Perfgate.measure`
+    # is never called (spec section 13.1).
+    #
+    # A failed assertion or raised exception inside the workload is an
+    # execution error, not a performance regression (spec section 12.2):
+    # it aborts this workload's run and is reported as `status: "error"`
+    # rather than raising out of `call`.
+    class Runner
+      def initialize(workload)
+        @workload = workload
+      end
+
+      def call
+        @workload.warmup.times { run_once }
+
+        samples = Array.new(@workload.samples) { run_once }
+
+        result("completed", samples, nil)
+      rescue StandardError => e
+        result("error", [], "#{e.class}: #{e.message}")
+      end
+
+      private
+
+      def result(status, samples, error)
+        {
+          "id" => @workload.id, "status" => status, "samples" => samples, "error" => error,
+          "definition_hash" => Fingerprints::WorkloadDefinition.hash_for(@workload)
+        }
+      end
+
+      def run_once
+        data = nil
+
+        SampleContext.with_new(metrics: @workload.metrics) do |context|
+          wall_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          @workload.call
+          wall_elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - wall_start
+
+          data = context.data.dup
+          data["duration_ns"] ||= (wall_elapsed * 1_000_000_000).round
+        end
+
+        data
+      end
+    end
+  end
+end

data/lib/perfgate/execution/sample_context.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "../instrumentation"
+
+module Perfgate
+  module Execution
+    # Thread-local scratch space that `Perfgate.measure` writes into when
+    # called from inside a running workload sample, per the explicit
+    # measurement contract in spec section 9.1 / 13.1: metrics other than
+    # the wall-clock duration fallback are only ever collected during the
+    # explicit `Perfgate.measure` block, never for the workload as a
+    # whole (Milestone 2 exit criterion: "metrics are correctly isolated
+    # to the measurement block").
+    class SampleContext
+      def self.current
+        Thread.current[:baseline_sample_context]
+      end
+
+      def self.current=(context)
+        Thread.current[:baseline_sample_context] = context
+      end
+
+      # Runs the block with a fresh context active for the given metric
+      # names, restoring whatever was active beforehand (nil, normally)
+      # once the block finishes.
+      def self.with_new(metrics: [:duration])
+        previous = current
+        context = new(metrics: metrics)
+        self.current = context
+        yield context
+      ensure
+        self.current = previous
+      end
+
+      def initialize(metrics: [:duration])
+        @collectors = Instrumentation.collectors_for(metrics)
+        @data = {}
+        @measured = false
+      end
+
+      # Runs the block with every configured collector started
+      # beforehand and stopped immediately after, merging their results
+      # into this sample's data. Safe to call more than once per sample;
+      # repeated calls accumulate (numeric values are summed).
+      def measure
+        @measured = true
+        started = @collectors.map { |collector| [collector, collector.start] }
+        result = yield
+        started.each { |collector, state| accumulate(collector.finish(state)) }
+        result
+      end
+
+      def measured?
+        @measured
+      end
+
+      attr_reader :data
+
+      private
+
+      def accumulate(collected)
+        collected.each { |key, value| @data[key] = @data.fetch(key, 0) + value }
+      end
+    end
+  end
+end

data/lib/perfgate/fingerprints/compatibility.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Perfgate
+  module Fingerprints
+    # Decides whether a baseline run and a candidate run are comparable
+    # at all, before any statistics are computed (spec section 15.3).
+    # A difference in any "strict" field makes the runs incompatible;
+    # a difference in an "informational" field only downgrades the
+    # result to "compatible_with_warnings" (still comparable, but the
+    # decision should be presented to the reader with that context).
+    module Compatibility
+      module_function
+
+      def evaluate(baseline_components:, candidate_components:, config: Perfgate.configuration)
+        strict = diff_fields(baseline_components, candidate_components, config.fingerprint_strict_fields, "strict")
+        informational = diff_fields(baseline_components, candidate_components,
+                                    config.fingerprint_informational_fields, "informational")
+        differences = strict + informational
+
+        { "status" => status_for(differences), "differences" => differences }
+      end
+
+      def diff_fields(baseline_components, candidate_components, fields, severity)
+        Array(fields).filter_map do |field|
+          next if field == "workload_definition_hash"
+
+          baseline_value = baseline_components[field]
+          candidate_value = candidate_components[field]
+          next if baseline_value == candidate_value
+
+          { "field" => field, "severity" => severity, "baseline" => baseline_value, "candidate" => candidate_value }
+        end
+      end
+
+      def status_for(differences)
+        if differences.any? { |d| d["severity"] == "strict" }
+          "incompatible"
+        elsif differences.any?
+          "compatible_with_warnings"
+        else
+          "compatible"
+        end
+      end
+    end
+  end
+end

data/lib/perfgate/fingerprints/components.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "digest"
+require "etc"
+
+module Perfgate
+  module Fingerprints
+    # Collects the run-level fingerprint component values referenced by
+    # the strict/informational field lists in config.fingerprint (spec
+    # section 15.1/15.2). `workload_definition_hash` is deliberately
+    # excluded here: it is computed per-workload
+    # (see WorkloadDefinition) and compared per-workload in the
+    # comparison engine, not as a run-wide component.
+    module Components
+      module_function
+
+      def collect(config: Perfgate.configuration)
+        strict_components(config).merge(informational_components)
+      end
+
+      def strict_components(config)
+        {
+          "ruby_engine" => RUBY_ENGINE,
+          "ruby_version" => RUBY_VERSION,
+          "rails_version" => rails_version,
+          "baseline_version_major" => Perfgate::VERSION.split(".").first,
+          "database_adapter" => database_adapter,
+          "database_version_major" => database_version_major,
+          "dataset_hash" => dataset_hash(config)
+        }
+      end
+
+      def informational_components
+        {
+          "operating_system" => operating_system,
+          "cpu_model" => cpu_model,
+          "cpu_count" => Etc.nprocessors.to_s,
+          "memory_bytes" => nil,
+          "ci_provider" => ci_provider,
+          "runner_image" => ENV.fetch("PERFGATE_RUNNER_IMAGE", nil),
+          "dependency_lock_hash" => dependency_lock_hash
+        }
+      end
+
+      def rails_version
+        defined?(::Rails) ? ::Rails.version : nil
+      end
+
+      def database_adapter
+        return nil unless defined?(::ActiveRecord::Base)
+
+        ::ActiveRecord::Base.connection.adapter_name
+      rescue StandardError
+        nil
+      end
+
+      def database_version_major
+        return nil unless defined?(::ActiveRecord::Base)
+
+        version = ::ActiveRecord::Base.connection.database_version
+        version.to_s.split(".").first
+      rescue StandardError, NotImplementedError
+        nil
+      end
+
+      # Applications provide their own dataset fingerprint hook (spec
+      # section 12.3, e.g. a fixture set version or seed migration
+      # number); Baseline only ever stores its hash, never the raw value,
+      # to avoid leaking application data into shared run artifacts.
+      def dataset_hash(config)
+        raw = config.dataset_fingerprint.call
+        "sha256:#{Digest::SHA256.hexdigest(raw.to_s)}"
+      end
+
+      def operating_system
+        RbConfig::CONFIG["host_os"]
+      end
+
+      def cpu_model
+        ENV.fetch("PERFGATE_CPU_MODEL", nil)
+      end
+
+      def ci_provider
+        return "github_actions" if ENV["GITHUB_ACTIONS"]
+        return "gitlab_ci" if ENV["GITLAB_CI"]
+        return "circleci" if ENV["CIRCLECI"]
+
+        nil
+      end
+
+      # Deferred: hashing Gemfile.lock (or equivalent) is a small addition
+      # but out of Milestone 3's explicit scope; left nil until wired up.
+      def dependency_lock_hash
+        nil
+      end
+    end
+  end
+end

data/lib/perfgate/fingerprints/workload_definition.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module Perfgate
+  module Fingerprints
+    # Computes a per-workload definition hash from the properties that,
+    # if changed, would make a historical run incomparable to a new one
+    # (spec section 15.4): the workload's id, its sample/warmup counts,
+    # and the set of metrics it records. Hashing the workload's source
+    # code (to detect behavioral changes even when these properties are
+    # unchanged) is explicitly deferred -- the spec notes this requires
+    # normalizing formatting/whitespace-only diffs, which is a larger
+    # follow-up.
+    module WorkloadDefinition
+      module_function
+
+      def hash_for(workload)
+        payload = {
+          "id" => workload.id,
+          "samples" => workload.samples,
+          "warmup" => workload.warmup,
+          "metrics" => Array(workload.metrics).map(&:to_s).sort
+        }
+        "sha256:#{Digest::SHA256.hexdigest(JSON.generate(payload))}"
+      end
+    end
+  end
+end

data/lib/perfgate/instrumentation/allocations.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Perfgate
+  module Instrumentation
+    # Ruby object allocation count during a `Perfgate.measure` block
+    # (spec section 13.4), using the allocation counter built into every
+    # supported Ruby version.
+    module Allocations
+      module_function
+
+      def start
+        GC.stat(:total_allocated_objects)
+      end
+
+      def finish(started_at)
+        { "allocations" => GC.stat(:total_allocated_objects) - started_at }
+      end
+    end
+  end
+end

data/lib/perfgate/instrumentation/duration.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Perfgate
+  module Instrumentation
+    # Wall-clock duration of a `Perfgate.measure` block (spec section
+    # 13.1). Uses a monotonic clock so NTP adjustments and system clock
+    # changes never produce a negative or inflated reading.
+    module Duration
+      module_function
+
+      def start
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def finish(started_at)
+        { "duration_ns" => ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1_000_000_000).round }
+      end
+    end
+  end
+end

data/lib/perfgate/instrumentation/gc.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Perfgate
+  module Instrumentation
+    # Garbage-collection activity during a `Perfgate.measure` block (spec
+    # section 13.5). `gc_count` matches the run-result schema in section
+    # 14.1; `gc_minor_count`/`gc_major_count` are additional diagnostic
+    # deltas the schema doesn't name explicitly but section 13.5 asks us
+    # to capture. GC metrics are diagnostic only and never fail a run.
+    module Gc
+      module_function
+
+      def start
+        {
+          count: GC.stat(:count),
+          minor_count: GC.stat(:minor_gc_count),
+          major_count: GC.stat(:major_gc_count)
+        }
+      end
+
+      def finish(started_at)
+        {
+          "gc_count" => GC.stat(:count) - started_at[:count],
+          "gc_minor_count" => GC.stat(:minor_gc_count) - started_at[:minor_count],
+          "gc_major_count" => GC.stat(:major_gc_count) - started_at[:major_count]
+        }
+      end
+    end
+  end
+end

data/lib/perfgate/instrumentation/sql_activity.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Perfgate
+  module Instrumentation
+    # SQL query count and cumulative duration during a `Perfgate.measure`
+    # block (spec sections 13.2-13.3), collected via an
+    # ActiveSupport::Notifications subscription scoped to exactly that
+    # block. Schema queries, transaction control statements, and cached
+    # query hits are excluded as configurable noise (13.2); raw SQL text
+    # is never stored, only counts and a cumulative duration.
+    module SqlActivity
+      NOISE_EVENT_NAMES = %w[SCHEMA TRANSACTION].freeze
+
+      module_function
+
+      def start
+        ensure_active_support!
+
+        state = { count: 0, duration_ns: 0 }
+        subscriber = ::ActiveSupport::Notifications.subscribe("sql.active_record") do |*args|
+          event = ::ActiveSupport::Notifications::Event.new(*args)
+          record(state, event) unless noise?(event.payload)
+        end
+        { subscriber: subscriber, state: state }
+      end
+
+      def finish(started)
+        ::ActiveSupport::Notifications.unsubscribe(started.fetch(:subscriber))
+        state = started.fetch(:state)
+        { "sql_count" => state[:count], "sql_duration_ns" => state[:duration_ns] }
+      end
+
+      def record(state, event)
+        state[:count] += 1
+        state[:duration_ns] += (event.duration * 1_000_000).round
+      end
+
+      def noise?(payload)
+        NOISE_EVENT_NAMES.include?(payload[:name].to_s) || payload[:cached]
+      end
+
+      def ensure_active_support!
+        return if defined?(::ActiveSupport::Notifications)
+
+        raise Perfgate::Error,
+              "sql_count/sql_duration instrumentation requires ActiveSupport::Notifications to be loaded"
+      end
+    end
+  end
+end

data/lib/perfgate/instrumentation.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "instrumentation/duration"
+require_relative "instrumentation/sql_activity"
+require_relative "instrumentation/allocations"
+require_relative "instrumentation/gc"
+
+module Perfgate
+  # Instrumentation collectors for the metrics a workload can measure
+  # (spec section 13): each collector module exposes `.start`/`.finish`
+  # and is invoked only within a workload's explicit `Perfgate.measure`
+  # block.
+  module Instrumentation
+    # Maps a workload's configured metric names (spec section 11's
+    # `metrics` config, e.g. `:duration`, `:sql_count`) to the collector
+    # module responsible for it. `sql_count` and `sql_duration` share a
+    # single collector since both come from the same notification
+    # subscription. `memory` (section 13.6) is intentionally absent: it
+    # is disabled by default and not yet implemented.
+    REGISTRY = {
+      duration: Duration,
+      sql_count: SqlActivity,
+      sql_duration: SqlActivity,
+      allocations: Allocations,
+      gc: Gc
+    }.freeze
+
+    module_function
+
+    # The distinct set of collectors needed to satisfy the given metric
+    # names, in a stable order.
+    def collectors_for(metric_names)
+      metric_names.filter_map { |name| REGISTRY[name] }.uniq
+    end
+  end
+end

data/lib/perfgate/policy/engine.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Perfgate
+  module Policy
+    # Turns a comparison-result document (or the absence of one) into
+    # the PASS/WARN/FAIL/INCOMPARABLE decision and CI exit code baseline
+    # exits with (spec section 17):
+    #
+    #   0 PASS, or WARN under a non-blocking policy
+    #   1 Performance FAIL
+    #   2 Configuration error       (raised directly by the CLI, not here)
+    #   3 Execution error           (raised directly by the CLI, not here)
+    #   4 Missing baseline under a strict policy
+    #   5 Incompatible baseline under a strict policy
+    #
+    # `config.policy` controls how "soft" signals (an incompatible
+    # fingerprint, a new/removed workload) escalate into a hard FAIL --
+    # every one of those keys defaults to "warn" (never blocking) and
+    # only escalates when explicitly set to "fail".
+    module Engine
+      EXIT_CODES = { "pass" => 0, "warn" => 0, "fail" => 1, "missing_baseline" => 4, "incomparable" => 5 }.freeze
+      ESCALATING_WORKLOAD_DECISIONS = { "new_workload" => :new_workload, "removed_workload" => :removed_workload,
+                                        "incomparable" => :incompatible }.freeze
+
+      module_function
+
+      def evaluate(comparison_result:, config: Perfgate.configuration)
+        status = status_for(comparison_result, config)
+        { "status" => status, "exit_code" => EXIT_CODES.fetch(status) }
+      end
+
+      # A separate entry point for the CLI: there is no comparison result
+      # at all when no prior baseline run could be found to compare
+      # against (spec section 17's exit code 4).
+      def evaluate_missing_baseline(config: Perfgate.configuration)
+        status = config.policy[:missing_baseline] == "fail" ? "missing_baseline" : "warn"
+        { "status" => status, "exit_code" => EXIT_CODES.fetch(status) }
+      end
+
+      def status_for(comparison_result, config)
+        return incompatible_status(config) if comparison_result["decision"] == "incompatible"
+
+        escalation = workload_escalation(comparison_result, config)
+        return escalation if escalation
+
+        metric_status(comparison_result, config)
+      end
+
+      def incompatible_status(config)
+        config.policy[:incompatible] == "fail" ? "incomparable" : "warn"
+      end
+
+      def workload_escalation(comparison_result, config)
+        workloads = comparison_result.fetch("workloads", [])
+        ESCALATING_WORKLOAD_DECISIONS.each do |decision, policy_key|
+          next unless config.policy[policy_key] == "fail"
+          next unless workloads.any? { |w| w["decision"] == decision }
+
+          return "fail"
+        end
+        nil
+      end
+
+      def metric_status(comparison_result, config)
+        case comparison_result["decision"]
+        when "fail" then "fail"
+        when "warn" then config.policy[:fail_on] == "warn" ? "fail" : "warn"
+        else "pass"
+        end
+      end
+    end
+  end
+end

data/lib/perfgate/report/console.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Perfgate
+  module Report
+    # Renders the schema_version 1 comparison-result document (plus its
+    # Policy::Engine verdict) as the plain-text console summary from
+    # spec 20.1: overall decision, run identities, a per-workload/
+    # per-metric table with a "likely signal" diagnostic line,
+    # compatibility status, and sample counts.
+    module Console
+      DURATION_METRICS = %w[duration sql_duration].freeze
+      METRIC_LABELS = { "duration" => "Duration", "sql_count" => "SQL queries", "sql_duration" => "SQL duration",
+                        "allocations" => "Allocations" }.freeze
+
+      module_function
+
+      def render(comparison_result:, policy_result:)
+        lines = ["Baseline Performance Assurance", "", "Overall: #{policy_result["status"].upcase}",
+                 "Baseline: #{comparison_result["baseline_run_id"]}",
+                 "Candidate: #{comparison_result["candidate_run_id"]}", ""]
+        comparison_result.fetch("workloads", []).each { |workload| lines.concat(workload_lines(workload)) }
+        lines << "Compatibility: #{comparison_result.dig("compatibility", "status")}"
+        lines.join("\n")
+      end
+
+      def workload_lines(workload)
+        marker = workload["decision"] == "pass" ? "\u2713" : "\u2717"
+        lines = ["#{marker} #{workload["id"]}"]
+        workload["metrics"].each { |name, metric| lines << metric_line(name, metric) }
+        lines.concat(diagnostics_lines(workload))
+        lines << ""
+      end
+
+      def metric_line(name, metric)
+        label = METRIC_LABELS.fetch(name, name)
+        before = format_value(name, metric["baseline_median"])
+        after = format_value(name, metric["candidate_median"])
+        change = metric["change_percent"] ? format("%+.1f%%", metric["change_percent"]) : "n/a"
+        format("  %<label>-15s %<before>s \u2192 %<after>s   %<change>s   %<decision>s",
+               label: label, before: before, after: after, change: change, decision: metric["decision"].upcase)
+      end
+
+      def format_value(name, value)
+        return "n/a" if value.nil?
+
+        DURATION_METRICS.include?(name) ? format("%.0f ms", value / 1_000_000.0) : value.to_s
+      end
+
+      def diagnostics_lines(workload)
+        messages = workload["diagnostics"] || []
+        return [] if messages.empty?
+
+        ["  Likely signal:"] + messages.map { |message| "    #{message}" }
+      end
+    end
+  end
+end