duel 0.1.0

data/sig/duel/config.rbs

@@ -0,0 +1,181 @@
+module Duel
+  # What Duel knows about a project (.duel.rb changes what doesn't follow
+  # from the conventions).
+  class Config
+    # A prepare block (see #prepare): given a Resource for a version or a
+    # worker, it returns the environment variables it gets.
+    type prepare = ^(Resource resource) -> Hash[String, String?]
+
+    # The Ruby each version runs on (see #ruby): nil for the runner's, its
+    # version file's, a path, or what a block makes of the version's tree.
+    type ruby = :version_file | String | ^(String root) -> String | nil
+
+    @root: String
+    @benchmarks: String
+    @watch: Array[String]
+    @library: String | :conventional | nil
+    @build: String | :conventional | nil
+    @main_branch: String?
+    @release_tags: String
+    @prepares: Hash[Symbol, Array[prepare]]
+    @ruby: ruby
+    @metrics: Array[singleton(Metric)]
+    @in_workers: Array[^(Stops stops) -> void]
+    @hooks: Hash[Symbol, Array[hook]]
+    @used: Hash[Symbol, Used]
+    @measures: Hash[String, Hash[Symbol, untyped]]
+    @loader: (^(String version_root) -> void)?
+
+    # Where the project is (and its config file).
+    attr_reader root: String
+
+    # A glob, from the root, of the files defining benchmarks.
+    attr_accessor benchmarks: String
+
+    # Paths, from the root, whose changes a comparison is about.
+    attr_accessor watch: Array[String]
+
+    # The library to require from each version, or nil for none.
+    attr_writer library (): String?
+
+    # A shell command that builds a checked-out tree, or nil for none.
+    attr_writer build (): String?
+
+    # The branch a comparison defaults to (nil: the one origin/HEAD names).
+    attr_accessor main_branch: String?
+
+    # The glob release tags match (for `--base last-release`).
+    attr_accessor release_tags: String
+
+    # The Ruby each version runs on: nil for the runner's own,
+    # :version_file for the one its version file names, a path, or a block
+    # given the version's tree.
+    attr_accessor ruby: ruby
+
+    # What #prepare was given, by scope.
+    # @api private
+    attr_reader prepares: Hash[Symbol, Array[prepare]]
+
+    # The metrics #metric added, in order.
+    attr_reader metrics: Array[singleton(Metric)]
+
+    # What #in_worker was given.
+    # @api private
+    attr_reader in_workers: Array[^(Stops stops) -> void]
+
+    # What the hooks were given, by name.
+    # @api private
+    attr_reader hooks: Hash[Symbol, Array[hook]]
+
+    # Each measure's settings changed, by name.
+    # @api private
+    attr_reader measures: Hash[String, Hash[Symbol, untyped]]
+
+    # A configuration of the conventions, for the project at +root+.
+    def initialize: (?String root) -> void
+
+    # What #prepare prepares: each version, or each worker.
+    # @api private
+    SCOPES: Array[Symbol]
+
+    # The library: the gem the project's only .gemspec names, unless set.
+    %a{pure} def library: () -> String?
+
+    # The build command: `bundle exec rake compile` for a project with
+    # ext/ and a Rakefile, unless set.
+    %a{pure} def build: () -> String?
+
+    # How a worker loads one version of the code, from the tree at the
+    # root it's given, instead of the convention.
+    def load: () { (String version_root) -> void } -> void
+
+    # Loads the version at +version_root+.
+    # @api private
+    def load_into: (String version_root) -> void
+
+    # Uses a plugin, by its name: requires duel/+name+, and configures Duel
+    # for it with +options+, once. Returns what that returned.
+    def use: (Symbol name, **untyped options) -> untyped
+
+    # The plugins used, by name, in the order they were first used.
+    def plugins: () -> Array[Symbol]
+
+    # A plugin as #use installed it.
+    # @api private
+    class Used
+      @options: Hash[Symbol, untyped]
+      @value: untyped
+
+      attr_reader options: Hash[Symbol, untyped]
+
+      attr_accessor value: untyped
+
+      def initialize: (Hash[Symbol, untyped] options) -> void
+
+      # What using it again with +given+ options returns, or fails.
+      def again: (Symbol name, Hash[Symbol, untyped] given) -> untyped
+    end
+
+    # Prepares each version (once for a run, in the runner, before any of
+    # its workers start), or each worker (as it starts). Returns the
+    # environment the version's workers, or the worker, get.
+    def prepare: (Symbol scope) { (Resource resource) -> Hash[String, String?] } -> void
+
+    # Adds a metric to every benchmark: a Duel::Metric subclass, or
+    # running totals the block reads (see Snapshot), one by name (with its
+    # settings) or several by their settings. Returns the metric: running
+    # totals' takes what explains them (.details), typed by what the block
+    # read with them, C.
+    def metric: (singleton(Metric) klass) -> singleton(Metric)
+              # (Totals alone, each a T: no context.)
+              | [T < Metric::value] (String name, **untyped settings) { () -> Snapshot::read_totals[T] } -> Snapshot::_Explained[T, nil]
+              | [T < Metric::value] (Hash[String, Metric::settings] measures) { () -> Snapshot::read_totals[T] } -> Snapshot::_Explained[T, nil]
+              | [T < Metric::value] (**Metric::settings measures) { () -> Snapshot::read_totals[T] } -> Snapshot::_Explained[T, nil]
+              # (Totals and their context, C.)
+              | [T < Metric::value, C] (String name, **untyped settings) { () -> [Snapshot::read_totals[T], C] } -> Snapshot::_Explained[T, C]
+              | [T < Metric::value, C] (Hash[String, Metric::settings] measures) { () -> [Snapshot::read_totals[T], C] } -> Snapshot::_Explained[T, C]
+              | [T < Metric::value, C] (**Metric::settings measures) { () -> [Snapshot::read_totals[T], C] } -> Snapshot::_Explained[T, C]
+
+    # Runs the block in each worker, once its version and the benchmarks
+    # have loaded and before its metrics are made. Returns what it
+    # returns, in the worker.
+    def in_worker: [T] () { (Stops worker) -> T } -> InWorker[T]
+
+    # The configuration's hooks (see Duel::HOOKS), for every benchmark,
+    # run where they were written, before its file's and its own.
+    def setup: () { (?Definition benchmark) -> void } -> void
+
+    def teardown: () { (?Definition benchmark) -> void } -> void
+
+    def before_sample: () { (?Definition benchmark) -> void } -> void
+
+    def around_iteration: () { (Iteration iteration) -> void } -> void
+
+    def after_iterations: () { () -> void } -> void
+
+    # Changes a measure's settings, by its name (skip: true leaves it out).
+    def measure: (String name, **untyped settings) -> void
+
+    # Whether a measure is skipped (see #measure).
+    def skip?: (String name) -> bool
+
+    # The files that define benchmarks, in order.
+    # @api private
+    def benchmark_files: () -> Array[String]
+
+    private
+
+    def add_hook: (Symbol name, Proc? block) -> void
+  end
+
+  # Silences warnings about redefined constants, while loading a version
+  # over files of another's (see Config#load_into).
+  # @api private
+  module QuietRedefinition : Warning
+    REDEFINITION: Regexp
+
+    def self.during: [T] () { () -> T } -> T
+
+    def warn: (String message, ?category: Symbol?) -> nil
+  end
+end

data/sig/duel/context.rbs

@@ -0,0 +1,387 @@
+module Duel
+  # What a benchmark's run is measured by: a Sample, or a Trial,
+  # MemorySample or ProfileSample.
+  # @api private
+  interface _Sample
+    def start: () -> void
+
+    def stop: () -> void
+
+    # Runs the block with measuring paused, and returns what it does.
+    def pause: [T] () { () -> T } -> T
+
+    # Runs the block (around_iteration hooks, around each iteration)
+    # paused, and returns what it does.
+    def between: [T] () { () -> T } -> T
+
+    # Runs the block measured, inside #between's, and returns what it
+    # does.
+    def unpause: [T] () { () -> T } -> T
+  end
+
+  # What a benchmark's blocks run in (its file's hooks, and its own,
+  # too): its state lives in instance variables. Its
+  # methods are the two a benchmark calls, and the helpers that files of
+  # benchmarks define.
+  class Context
+    @__duel_harness: Harness
+
+    # @api private
+    def initialize: (Harness harness) -> void
+
+    # Runs the block the first time the benchmark runs: its trial, or its
+    # first peak memory sample in a worker that ran none.
+    def once: () { () -> void } -> void
+
+    # Runs the block with measuring paused, and returns what it does.
+    def untimed: [T] () { () -> T } -> T
+
+    # Fails if a helper has the name of a method Duel gives benchmarks.
+    # @api private
+    def self.check: () -> void
+  end
+
+  # A benchmark as a worker runs it: its Context, its hooks, its trial
+  # and its samples.
+  # @api private
+  class Harness
+    # Nothing left by pausing and resuming.
+    NO_LEAK: Hash[String, Float]
+
+    # The iterations each calibration sample pauses and resumes.
+    STRETCHES: Integer
+
+    # The iterations of each sample that learns what around_iteration
+    # hooks add to the metrics costly to read.
+    HOOKED: Integer
+
+    # The benchmark's body (or a hook), as a method of the context's, or
+    # a hook of the configuration's.
+    interface _Bound
+      def call: (?) -> untyped
+
+      def arity: () -> Integer
+    end
+
+    @definition: Definition
+    @context: Context
+    @setup: Array[_Bound]
+    @teardown: Array[_Bound]
+    @before_sample: Array[_Bound]
+    @after: Array[_Bound]
+    @body: _Bound
+    # Whether its block takes the number of iterations.
+    @given_n: bool
+    @iteration: Iteration?
+    @trial: bool
+    @sample: _Sample?
+    # Whether its once blocks have run (false: they run in the sample
+    # running, a worker's first for peak memory, and nil: no trial yet).
+    @once_done: bool?
+    @leak: Hash[String, Float]?
+
+    attr_reader definition: Definition
+
+    attr_reader context: Context
+
+    def initialize: (Definition definition, ?Hash[Symbol, Array[hook]] hooks) -> void
+
+    def once: () { () -> void } -> void
+
+    def untimed: [T] () { () -> T } -> T
+
+    # Runs its setup hooks.
+    def prepare: () -> void
+
+    # Runs its teardown hooks.
+    def finish: () -> void
+
+    # Runs the benchmark once, measuring nothing, with its once blocks.
+    def trial: () -> void
+
+    # Runs one sample for its peak memory (its once blocks too, if there
+    # was no trial).
+    def run_memory: (Integer n, MemorySample sample) -> void
+
+    # Runs one sample of +n+ iterations, measured by +sample+.
+    def run: (Integer n, _Sample sample) -> void
+
+    # Whether it runs inside around_iteration hooks.
+    def around?: () -> bool
+
+    # A Sample of +n+ iterations of it, measured by +metrics+.
+    def sample: (Array[Metric] metrics, n: Integer, ?counting: bool) -> Sample
+
+    # What a benchmark with around_iteration hooks leaves in each
+    # measure, an iteration, that isn't the iteration's own.
+    def leak: (Array[Metric] metrics) -> Hash[String, Float]
+
+    # Runs one iteration, measured, then its after_iterations hooks.
+    def iteration: () -> untyped
+
+    private
+
+    # The hooks +name+d: the configuration's, then its file's and its own.
+    def hooks: (Symbol name, Hash[Symbol, Array[hook]] hooks) -> Array[_Bound]
+
+    # +hook+, given the benchmark, if it takes it.
+    def given: (_Bound hook) -> _Bound
+
+    # What pausing and resuming leaves in each measure, an iteration.
+    def paused: (Array[Metric] metrics) -> Hash[String, Float]
+
+    # What the around_iteration hooks add to each measure (of metrics
+    # costly to read), an iteration.
+    def hooked: (Array[Metric] metrics) -> Hash[String, Float]
+
+    # Each measure's least in +runs+, over +stretches+.
+    def least: (Array[Hash[String, Metric::value]] runs, Integer stretches) -> Hash[String, Float]
+
+    def iterate: (Integer n, _Sample sample) -> void
+
+    def bound: (^(?) [self: Context] -> untyped block) -> _Bound
+  end
+
+  # An iteration of a benchmark with around_iteration hooks, which a hook
+  # is given to run.
+  class Iteration
+    @harness: Harness
+    @hook: Harness::_Bound
+    @inner: Iteration?
+    @ran: bool
+    # What its iteration did, the last time it ran.
+    @done: untyped
+
+    # @api private
+    def initialize: (Harness harness, Harness::_Bound hook, Iteration? inner) -> void
+
+    # Runs the iteration, measured, and returns what it does.
+    def call: () -> untyped
+
+    # Runs its hook, given it, and returns what its iteration did.
+    # @api private
+    def run: () -> untyped
+  end
+
+  # One measured stretch of a benchmark: every metric's measurement of it,
+  # and (CRuby) about how many bytes it allocated. A metric's #start_sample gets
+  # it: its #benchmark and #n are the metric's to read, and the rest is the
+  # worker's.
+  class Sample
+    # Zero bytes allocated: what JRuby tells.
+    # @api private
+    NO_HEAP: ^() -> Integer
+
+    # Bytes allocated so far, roughly (zero on JRuby).
+    # @api private
+    HEAP: ^() -> Integer
+
+    # Collects the garbage left so far, then holds off collecting.
+    # @api private
+    QUIET_GC: ^() -> void
+
+    @benchmark: Definition
+    @n: Integer
+    @counting: bool
+    @metrics: Array[Metric]
+    # Those paused around each iteration: not those costly to read.
+    @paused: Array[Metric]
+    @timed: Hash[String, Metric::value]
+    @counted: Hash[String, Metric::value]
+    @details: Hash[String, String]
+    @started: true?
+    @stopped: true?
+    @heap: Integer
+
+    # What a metric learns of the sample: its benchmark and its iterations.
+    attr_reader benchmark: Definition
+
+    attr_reader n: Integer
+
+    # @api private
+    attr_reader started: true?
+
+    # @api private
+    attr_reader stopped: true?
+
+    # Each timed measure's total, by name.
+    # @api private
+    attr_reader timed: Hash[String, Metric::value]
+
+    # Each counted measure's total, by name (when counting).
+    # @api private
+    attr_reader counted: Hash[String, Metric::value]
+
+    # Bytes allocated (once it's stopped).
+    # @api private
+    attr_reader heap: Integer
+
+    # What metrics said of it (Metric#details), by measure.
+    # @api private
+    attr_reader details: Hash[String, String]
+
+    # @api private
+    def initialize: (Definition benchmark, Array[Metric] metrics, n: Integer, ?counting: bool, ?around: bool) -> void
+
+    # @api private
+    def start: () -> void
+
+    # @api private
+    def stop: () -> void
+
+    # Runs the block with the metrics paused, and returns what it does.
+    # @api private
+    def pause: [T] () { () -> T } -> T
+
+    # Runs the block (around_iteration hooks) with the metrics paused, but those
+    # costly to read, and returns what it does.
+    # @api private
+    def between: [T] () { () -> T } -> T
+
+    # Runs the block measured, inside #between's, and returns what it
+    # does.
+    # @api private
+    def unpause: [T] () { () -> T } -> T
+
+    # Takes +leak+ away from each measure, once an iteration.
+    # @api private
+    def less: (Hash[String, Float] leak) -> void
+
+    private
+
+    # Keeps what a metric says of the sample, by measure.
+    def explain: (Metric metric) -> void
+
+    # Files a metric's measurement (or several, by name) by kind.
+    def record: (Metric metric, Metric::measurement value) -> void
+
+    # Adds +measured+ to +name+'s total, of its kind.
+    def file: (Hash[String, Metric::kind] kinds, String name, Metric::value? measured) -> void
+  end
+
+  # A sample of what around_iteration hooks add to the metrics costly to
+  # read: all but the iterations measured.
+  # @api private
+  class Hooked
+    @sample: Sample
+
+    def initialize: (Sample sample) -> void
+
+    def start: () -> void
+
+    def stop: () -> void
+
+    # Runs the block (an untimed one, inside an iteration): paused already.
+    def pause: [T] () { () -> T } -> T
+
+    # Runs the block (the around_iteration hooks): measured.
+    def between: [T] () { () -> T } -> T
+
+    # Runs the block (an iteration) paused.
+    def unpause: [T] () { () -> T } -> T
+  end
+
+  # A run of a benchmark that measures nothing: to see that it runs.
+  # @api private
+  class Trial
+    @started: true?
+    @stopped: true?
+
+    attr_reader started: true?
+
+    attr_reader stopped: true?
+
+    def start: () -> true
+
+    def stop: () -> true
+
+    def pause: [T] () { () -> T } -> T
+
+    def between: [T] () { () -> T } -> T
+
+    def unpause: [T] () { () -> T } -> T
+  end
+
+  # A stretch of a benchmark run for its peak memory.
+  # @api private
+  class MemorySample
+    @started: true?
+    @stopped: true?
+    # Resident memory where it started, plus what paused blocks left.
+    @base: Integer
+    # The most above it the watcher saw, outside paused blocks.
+    @peak: Integer
+    @paused: bool?
+    # Resident memory when it last stopped watching.
+    @unwatched: Integer
+    @watcher: Thread
+
+    attr_reader started: true?
+
+    attr_reader stopped: true?
+
+    # Bytes (once it's stopped).
+    attr_reader peak: Integer
+
+    def start: () -> void
+
+    def stop: () -> void
+
+    # Runs the block unwatched: what it leaves resident isn't counted.
+    def pause: [T] () { () -> T } -> T
+
+    # Runs the block (around_iteration hooks) unwatched, as #pause does.
+    def between: [T] () { () -> T } -> T
+
+    # Runs the block watched, inside #between's.
+    def unpause: [T] () { () -> T } -> T
+
+    private
+
+    def unwatched: () -> void
+
+    def watched: () -> void
+
+    def resident: () -> Integer
+
+    def watch: () -> void
+  end
+
+  # A stretch of a benchmark profiled with StackProf, the garbage
+  # collector held off, and untimed blocks and around_iteration hooks'
+  # own work left out.
+  # @api private
+  class ProfileSample
+    # Microseconds between samples.
+    INTERVAL: Integer
+
+    # What StackProf samples by here (see .mode).
+    MODE: :cpu | :wall
+
+    @started: true?
+    @stopped: true?
+
+    # What StackProf samples by on +platform+: CPU time, but elapsed time
+    # on macOS.
+    def self.mode: (?String platform) -> (:cpu | :wall)
+
+    attr_reader started: true?
+
+    attr_reader stopped: true?
+
+    def start: () -> void
+
+    def stop: () -> void
+
+    # Runs the block (an untimed one, or around_iteration hooks' work) left
+    # out of the profile.
+    def pause: [T] () { () -> T } -> T
+
+    # Runs the block (around_iteration hooks) in #pause.
+    def between: [T] () { () -> T } -> T
+
+    # Runs the block (an iteration, inside its hooks) profiled,
+    # inside #pause's.
+    def unpause: [T] () { () -> T } -> T
+  end
+end

data/sig/duel/init.rbs

@@ -0,0 +1,97 @@
+module Duel
+  # `duel init`: sets Duel up in a gem or an app that isn't a Rails app.
+  # @api private
+  class Init
+    USAGE: String
+
+    TEMPLATES: String
+
+    # What's added to a Rakefile.
+    RAKE_TASK: String
+
+    # What's added to a Gemfile, for profiles of regressions.
+    STACKPROF: String
+
+    # A Gemfile's development group.
+    DEVELOPMENT: Regexp
+
+    @argv: Array[String]
+    @out: _Output
+    @err: _Output
+    @root: String
+    @force: bool?
+    @dry_run: bool?
+    @stackprof: bool?
+
+    def initialize: (Array[String] argv, ?out: _Output, ?err: _Output, ?root: String) -> void
+
+    # Returns the exit status: 0 set up, 1 a Rails app, 2 a bad option.
+    def run: () -> Integer
+
+    # The files it writes, from the project's root, to what's in them.
+    def files: () -> Hash[String, String]
+
+    private
+
+    def parser: () -> OptionParser
+
+    # Says to use duel-rails's generator instead.
+    def rails: () -> Integer
+
+    # Writes +content+ to +path+, unless it exists, and says what it did.
+    def write: (String path, String content) -> void
+
+    # Adds Duel's Rake task to the Rakefile.
+    def add_rake_task: () -> void
+
+    # Adds StackProf to the Gemfile: in its development group, or at its end.
+    def add_stackprof: () -> void
+
+    # The Gemfile with StackProf last in its development group, or nil.
+    def in_development_group: (String text) -> String?
+
+    # What goes between a file's text and what's added at its end.
+    def gap: (String text) -> String
+
+    # The Gemfile with StackProf at its end.
+    def at_the_end: (String text) -> String
+
+    def said: (String what, String path) -> void
+
+    # What to do next, numbered, after a blank line.
+    def next_steps: () -> String
+
+    def render: (String name) -> String
+
+    # The library the gemspec names, or nil.
+    def library: () -> String?
+
+    # The library, without a gemspec: lib/'s only Ruby file, or nil.
+    def guess: () -> String?
+
+    # What each version's workers require.
+    def required: () -> String?
+
+    def benchmark_file: () -> String
+
+    def gemfile?: () -> bool
+
+    def ext: () -> bool
+
+    def version_file: () -> bool
+
+    # The Ruby the workflow sets up, or none.
+    def ruby_version: () -> String?
+
+    # The root of the project's git repository.
+    def repository: () -> String
+
+    # The project's directory, from its repository's root, or nil.
+    def working_directory: () -> String?
+
+    def workflow_name: () -> String
+
+    # What marks the workflow's comment on a pull request.
+    def marker: () -> String
+  end
+end

data/sig/duel/json_report.rbs

@@ -0,0 +1,47 @@
+module Duel
+  # A run's report as JSON, for a program to read.
+  # @api private
+  class JSONReport
+    # A value in the report: plain JSON types.
+    type value = String | Integer | Float | bool | nil | Array[value] | Hash[String, value]
+
+    # The report, by key.
+    type report = Hash[String, value]
+
+    # Its schema's version.
+    SCHEMA: Integer
+
+    @runner: Runner
+    @results: Array[Result]
+    @settings: Settings
+    @exit: Integer
+    @versions: Hash[String, Hash[String, String | bool | nil]]
+
+    # A run that didn't compare: +status+, its +exit+ status, and what it
+    # said.
+    def self.note: (String status, Integer exit, String message, Settings settings) -> report
+
+    # What every report starts with.
+    def self.head: (String status, Integer exit, String? message, Settings settings) -> report
+
+    def initialize: (Runner runner, Array[Result] results, settings: Settings, exit: Integer, baseline: Hash[String, String?],
+                     candidate: Hash[String, String | bool | nil]) -> void
+
+    def to_h: () -> report
+
+    private
+
+    def benchmark: (Result result) -> report
+
+    # Each timed measure, by metric.
+    def timed: (Result result) -> Hash[String, report]
+
+    # Each counted measure, by metric.
+    def counted: (Result result) -> Hash[String, report]
+
+    def peak_memory: (Result result) -> report?
+
+    # The verdicts across the board, by metric.
+    def across: () -> Hash[String, report]
+  end
+end