nukadoko 0.1.0

data/lib/nukadoko/run.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "fileutils"
+require "time"
+
+# One run: for each environment, start its world, play every scenario's steps
+# in order, and write a record per step. A scenario stops at its first step
+# that does not pass and skips the rest. A control that fails at a Then runs
+# again for proof. The table and the summary come last.
+module Nukadoko
+  module Engine
+    class Run
+      def initialize(project, steps, scenarios, program, out: $stdout)
+        @project = project
+        @steps = steps
+        @scenarios = scenarios
+        @program = Program.new(program)
+        @out = out
+        @id = new_id("run")
+        @dir = File.join(project, ".nukadoko", "runs", @id)
+      end
+
+      def call
+        FileUtils.mkdir_p(File.join(@dir, "steps"))
+        executions = []
+        cells = Hash.new { |h, k| h[k] = [] }
+        @program.environments.each do |environment|
+          @out.puts "environment #{environment.name}"
+          world_dir = File.join(@dir, "worlds", environment.name)
+          FileUtils.mkdir_p(world_dir)
+          world = @program.start(environment, world_dir, @project)
+          @process_fixtures = FixtureCache.new
+          @browser = Browser.new(world.base_url, Nukadoko.config_options.fetch(:browser, {}))
+          @scenarios.each do |scenario|
+            role = Table.role(Table.condition_tags(scenario.tags), environment.conditions)
+            runs = [play(scenario, environment, role, world)]
+            runs << play(scenario, environment, role, world) while proving?(role, runs)
+            executions.concat(runs)
+            cells[scenario] << Table.cell(runs.map { _1[:execution] }).merge(environment: environment.name, role: role)
+          end
+        ensure
+          @browser&.close
+          @process_fixtures&.teardown
+          world&.stop
+        end
+        finish(executions, cells)
+      end
+
+      private
+
+      def proving?(role, runs)
+        role == "control" && runs.size < Table::PROOF_RUNS && runs.all? { _1[:execution].first == :fail } && runs.map { _1[:execution] }.uniq.size == 1
+      end
+
+      def finish(executions, cells)
+        rows = @scenarios.map do |scenario|
+          row_cells = cells[scenario]
+          { feature: scenario.uri, line: scenario.line, name: scenario.name, conditions: Table.condition_tags(scenario.tags),
+            cells: row_cells, verdict: Table.verdict(row_cells) }
+        end
+        write_summary(rows)
+        @out.puts "summary   #{File.join(".nukadoko/runs", @id, "summary.md")}"
+        { run_id: @id, run_dir: File.join(".nukadoko/runs", @id), scenarios: executions.map { _1[:json] },
+          table: { rows: rows }, passed: rows.none? { _1[:verdict] == "failed" } }
+      end
+
+      def play(scenario, environment, role, world)
+        @out.puts "scenario  #{scenario.uri}:#{scenario.line}  #{scenario.name}#{role == "control" ? "  (control)" : ""}"
+        results = []
+        stopped = nil
+        @scratch = Scratch.new
+        @scenario_fixtures = FixtureCache.new
+        records = scenario.steps.map do |line|
+          record = stopped ? skipped(line) : play_step(line, results, world)
+          stopped ||= [record[:outcome], line.line, record[:claim]] if record[:status] == "failed"
+          @out.puts "  #{record[:status]}  #{line.text}"
+          @out.puts "      #{record[:error]}" if record[:error]
+          record
+        end
+        @browser.end_scenario
+        @scenario_fixtures.teardown
+        @scratch.remove_all
+        execution = stopped ? stopped.compact : [:pass]
+        { execution: execution,
+          json: { feature: scenario.uri, line: scenario.line, scenario: scenario.name, environment: environment.name, role: role,
+                  status: stopped ? "failed" : "passed",
+                  steps: scenario.steps.zip(records).map do |line, record|
+                    { line: line.line, text: line.text, step: record[:step], status: record[:status], record: record[:step_record_id] }.compact
+                  end } }
+      end
+
+      def skipped(line) = { step: Engine.matches(@steps, line.text).first&.first&.step_name, status: "skipped" }
+
+      def play_step(line, results, world)
+        step, captures = Engine.matches(@steps, line.text).first
+        return { status: "failed", outcome: :broke, error: %(no step matches "#{line.text}") } unless step
+
+        id = new_id("step")
+        dir = File.join(@dir, "steps", id)
+        FileUtils.mkdir_p(dir)
+        log = []
+        record = { step_record_id: id, step: step.step_name, text: line.text, started_at: Time.now.utc.iso8601(3) }
+        fixtures = {}
+        finish = nil
+        processes = []
+        begin
+          args = bind_args(step, captures, line, results)
+          record[:args] = args
+          problems = step.args.problems(args)
+          raise TypeError, "args: #{problems.join("; ")}" if problems.any?
+
+          fixtures, finish = build_fixtures(step, dir, log, world)
+          Processes.collect(processes) { body(step, fixtures, args, line, record, results) }
+          record[:status] ||= "passed"
+        rescue StandardError => e
+          record.merge!(status: "failed", outcome: :broke, error: "#{e.class}: #{e.message}")
+        ensure
+          finish&.call
+          log.concat(fixtures[:request].log) if fixtures[:request]
+          record[:finished_at] = Time.now.utc.iso8601(3)
+          record[:processes] = processes if processes&.any?
+          record[:calls] = fixtures[:call].calls if fixtures[:call]&.calls&.any?
+          record[:observed] = { http: log.size, processes: processes&.size || 0 }
+          File.write(File.join(dir, "http.jsonl"), log.map { JSON.generate(_1) }.join("\n"))
+          File.write(File.join(dir, "record.json"), JSON.pretty_generate(record))
+        end
+        record
+      end
+
+      # A Then step's claims are judged on what it observed, or on its args
+      # when it reads nothing itself; any other step runs and returns.
+      def body(step, fixtures, args, line, record, results)
+        if step.claims
+          own = fixtures.slice(*step.fixtures)
+          read = -> { step.method_defined?(:observe) ? step.new.observe(**own, args: step.inputs.load(args)) : args }
+          observed = step.poll ? Poll.new(step.poll, step.claims, args).call(record, &read) : read.()
+          judged = Claims.judge(step.claims, observed, args)
+          record[:claims] = judged
+          broken = judged.index { !_1[:holds] }
+          record.merge!(status: "failed", outcome: line_kind(line) == :then ? :fail : :broke, claim: broken, error: "claim #{broken} broke") if broken
+        else
+          value = step.new.run(**fixtures.slice(*step.fixtures), args: step.inputs.load(args))
+          problems = step.returns ? step.returns.problems(value) : []
+          raise TypeError, "returns: #{problems.join("; ")}" if problems.any?
+
+          if step.returns
+            dropped = step.returns.dropped(value)
+            record[:returns_dropped] = dropped if dropped.any?
+            value = step.returns.strip(value)
+          end
+          results << [step, value.transform_keys(&:to_s)]
+          record[:result] = value
+        end
+      end
+
+      # Captures first, then each `from` key from the nearest earlier step that
+      # gave it, then a table or docstring for the one required key still open.
+      def bind_args(step, captures, line, results)
+        args = captures.dup
+        step.from.each do |key, sources|
+          cls, value = results.reverse_each.find { |c, _| sources.any? { _1.first == c } }
+          raise ArgumentError, %(no earlier step in this scenario gave "#{key}") unless cls
+
+          args[key] = value.fetch(sources.find { _1.first == cls }[1].to_s)
+        end
+        open = step.args.fields.map { _1.name.to_s } - args.keys
+        attachment = line.table || line.doc_string
+        args[open.first] = attachment if attachment && open.any?
+        args
+      end
+
+      def line_kind(line) = line.kind == "Outcome" ? :then : :other
+
+      # A project fixture is built the first time a step of its scope names
+      # it, directly or through another fixture, and kept until the scope ends.
+      def project_fixture(name, world, chain)
+        fixture = Nukadoko.project_fixtures[name] or raise ArgumentError, "the Ruby engine has no fixture #{name} yet"
+        raise ArgumentError, "fixtures depend on each other in a cycle: #{[*chain, name].join(" -> ")}" if chain.include?(name)
+
+        cache = fixture.scope == :process ? @process_fixtures : @scenario_fixtures
+        return cache[name] if cache.key?(name)
+
+        deps = fixture.dependencies.to_h do |dep|
+          case dep
+          when :baseURL then [dep, world.base_url]
+          when :scratch then [dep, @scratch]
+          else [dep, project_fixture(dep, world, [*chain, name])]
+          end
+        end
+        cache.build(fixture, deps)
+      end
+
+      def build_fixtures(step, dir, log, world)
+        finish = nil
+        fixtures = (step.bag - [:call]).to_h do |name|
+          case name
+          when :request then [name, Request.new(world.base_url)]
+          when :baseURL then [name, world.base_url]
+          when :scratch then [name, @scratch]
+          when :page
+            page, finish = @browser.page_for(dir, log)
+            [name, page]
+          else [name, project_fixture(name, world, [])]
+          end
+        end
+        fixtures[:call] = Caller.new(step, fixtures) if step.fixtures.include?(:call)
+        [fixtures, finish]
+      end
+
+      def write_summary(rows)
+        verdicts = rows.map { _1[:verdict] }.tally.map { |v, n| "#{n} #{v}" }.join(", ")
+        lines = ["# nukadoko run #{rows.none? { _1[:verdict] == "failed" } ? "passed" : "failed"}: #{rows.size} criteria, #{verdicts}", ""]
+        rows.each do |r|
+          cells = r[:cells].map { |c| "#{c[:environment]} #{c[:outcome]}#{c[:line] ? "@#{c[:line]}" : ""}#{c[:role] == "control" ? " (control)" : ""}" }
+          lines << "- #{r[:verdict]}  #{r[:feature]}:#{r[:line]}  #{r[:name]}  #{cells.join(", ")}"
+        end
+        File.write(File.join(@dir, "summary.md"), "#{lines.join("\n")}\n")
+      end
+
+      def new_id(kind) = "#{kind}-#{Time.now.utc.strftime("%Y%m%d-%H%M%S")}-#{SecureRandom.alphanumeric(4).downcase}"
+    end
+  end
+end

data/lib/nukadoko/schema.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+# One declaration of a step's args or returns gives three things: the check
+# a value must pass at run time, the RBS a Steep user checks the step body
+# against, and the Data class the body receives. A type is a symbol for a
+# scalar, `[:array, type]` for a list, or a nested Schema for an object.
+module Nukadoko
+  class Schema
+    Field = Data.define(:name, :type, :description)
+
+    def self.build(&block)
+      schema = new
+      schema.instance_eval(&block) if block
+      schema
+    end
+
+    attr_reader :fields
+
+    def initialize(fields = [])
+      @fields = fields
+    end
+
+    # `null: true` lets the value be nil as well, as zod's `.nullable()` does.
+    def string(name, description = nil, null: false) = add(name, :string, description, null)
+    def boolean(name, description = nil, null: false) = add(name, :boolean, description, null)
+    def integer(name, description = nil, null: false) = add(name, :integer, description, null)
+    def number(name, description = nil, null: false) = add(name, :number, description, null)
+    def unknown(name, description = nil) = add(name, :unknown, description)
+    def enum(name, values, description = nil, null: false) = add(name, [:enum, values.map(&:to_s)], description, null)
+    def strings(name, description = nil, null: false) = add(name, [:array, :string], description, null)
+    def table(name, description = nil, null: false) = add(name, [:array, [:array, :string]], description, null)
+    def object(name, description = nil, null: false, &block) = add(name, Schema.build(&block), description, null)
+
+    # Reuses a field another step declared, so two contracts that must agree
+    # on one shape are written once: `field :created, AnItemExists.returns[:body]`.
+    def field(name, other, description = nil) = add(name, other.type, description || other.description)
+
+    def [](name) = fields.find { _1.name == name.to_sym }
+
+    def without(names) = Schema.new(fields.reject { names.include?(_1.name.to_s) })
+
+    def data_class
+      @data_class ||= fields.empty? ? Data.define : Data.define(*fields.map(&:name))
+    end
+
+    def load(hash)
+      data_class.new(**fields.to_h { [_1.name, hash.fetch(_1.name.to_s)] })
+    end
+
+    # Every way `value` departs from the schema, as `path: problem` lines.
+    # A key the schema does not declare is no problem: as a zod object does,
+    # the schema drops it (`strip`), and `dropped` names where.
+    def problems(value, path = nil)
+      return ["#{path || "value"} must be an object, got #{value.inspect}"] unless value.is_a?(Hash)
+
+      hash = value.transform_keys(&:to_s)
+      fields.flat_map do |field|
+        key = join(path, field.name)
+        hash.key?(field.name.to_s) ? Schema.type_problems(field.type, hash[field.name.to_s], key) : ["#{key} is missing"]
+      end
+    end
+
+    # The value with every key the schema does not declare left out, at any
+    # depth, with string keys. Assumes `problems` found none.
+    def strip(value)
+      hash = value.transform_keys(&:to_s)
+      fields.to_h { [_1.name.to_s, Schema.strip_type(_1.type, hash[_1.name.to_s])] }
+    end
+
+    def self.strip_type(type, value)
+      case type
+      in [:nullable, inner] then value.nil? ? nil : strip_type(inner, value)
+      in [:array, item] then value.map { strip_type(item, _1) }
+      in Schema then type.strip(value)
+      else value
+      end
+    end
+
+    # The paths of the keys `strip` leaves out, so a record can say what the
+    # step returned and the contract did not keep.
+    def dropped(value, path = nil)
+      hash = value.transform_keys(&:to_s)
+      names = fields.map { _1.name.to_s }
+      (hash.keys - names).map { join(path, _1) } + fields.flat_map { Schema.dropped_type(_1.type, hash[_1.name.to_s], join(path, _1.name)) }
+    end
+
+    def self.dropped_type(type, value, path)
+      case type
+      in [:nullable, inner] then value.nil? ? [] : dropped_type(inner, value, path)
+      in [:array, item] then value.each_with_index.flat_map { dropped_type(item, _1, "#{path}[#{_2}]") }
+      in Schema then type.dropped(value, path)
+      else []
+      end
+    end
+
+    def self.type_problems(type, value, path)
+      ok =
+        case type
+        in :string then value.is_a?(String)
+        in :boolean then [true, false].include?(value)
+        in :integer then value.is_a?(Integer)
+        in :number then value.is_a?(Numeric)
+        in :unknown then true
+        in [:nullable, inner] then return value.nil? ? [] : type_problems(inner, value, path)
+        in [:enum, values] then values.include?(value.is_a?(Symbol) ? value.to_s : value)
+        in [:array, item]
+          return ["#{path} must be an array, got #{value.inspect}"] unless value.is_a?(Array)
+
+          return value.each_with_index.flat_map { |v, i| type_problems(item, v, "#{path}[#{i}]") }
+        in Schema then return type.problems(value, path)
+        end
+      ok ? [] : ["#{path} must be #{type}, got #{value.inspect}"]
+    end
+
+    # The JSON Schema `nuka describe` prints, as zod's own conversion gives it:
+    # the root is closed, and an inner object is closed only on the output
+    # side (`returns`), where zod drops the keys it does not declare.
+    def json_schema(root: true, output: false)
+      schema = { type: "object", properties: fields.to_h { [_1.name, Schema.json_type(_1.type, output).merge(_1.description ? { description: _1.description } : {})] } }
+      schema[:required] = fields.map(&:name) if fields.any?
+      return { "$schema": "https://json-schema.org/draft/2020-12/schema", **schema, additionalProperties: false } if root
+
+      output ? schema.merge(additionalProperties: false) : schema
+    end
+
+    def self.json_type(type, output = false)
+      case type
+      in :string then { type: "string" }
+      in :boolean then { type: "boolean" }
+      in :integer then { type: "integer" }
+      in :number then { type: "number" }
+      in :unknown then {}
+      in [:nullable, inner] then { anyOf: [json_type(inner, output), { type: "null" }] }
+      in [:enum, values] then { type: "string", enum: values }
+      in [:array, item] then { type: "array", items: json_type(item, output) }
+      in Schema then type.json_schema(root: false, output: output)
+      end
+    end
+
+    def rbs_fields = fields.map { "attr_reader #{_1.name}: #{Schema.rbs_type(_1.type)}" }
+    def rbs_record = "{ #{fields.map { "#{_1.name}: #{Schema.rbs_type(_1.type)}" }.join(", ")} }"
+
+    def self.rbs_type(type)
+      case type
+      in :string then "String"
+      in :boolean then "bool"
+      in :integer then "Integer"
+      in :number then "Numeric"
+      in :unknown then "untyped"
+      in [:nullable, inner] then "(#{rbs_type(inner)})?"
+      in [:enum, values] then values.map(&:inspect).join(" | ")
+      in [:array, item] then "Array[#{rbs_type(item)}]"
+      in Schema then type.fields.empty? ? "Hash[Symbol, untyped]" : type.rbs_record
+      end
+    end
+
+    private
+
+    def add(name, type, description, null = false) = fields << Field.new(name.to_sym, null ? [:nullable, type] : type, description)
+    def join(path, name) = path ? "#{path}.#{name}" : name.to_s
+  end
+end

data/lib/nukadoko/signature.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# The RBS of each step, written from the same declarations check reads, so a
+# project that runs Steep gets the body checked against its own contract:
+# args it does not declare, a return value of the wrong shape, and, in a
+# Then step, an args key the claim keeps from observe.
+module Nukadoko
+  module Signature
+    FIXTURE_TYPES = { request: "Nukadoko::Engine::Request", scratch: "Nukadoko::Engine::Scratch", call: "Nukadoko::Engine::Caller", baseURL: "String", page: "untyped", context: "untyped" }.freeze
+
+    def self.of(steps)
+      steps.map { of_step(_1) }.join("\n")
+    end
+
+    def self.of_step(step)
+      params = step.fixtures.map { "#{_1}: #{FIXTURE_TYPES.fetch(_1, "untyped")}" } + ["args: Args"]
+      returns = step.returns ? step.returns.rbs_record : "Hash[Symbol, untyped]"
+      [
+        "class #{step.name} < Nukadoko::Step",
+        "  class Args",
+        *step.inputs.rbs_fields.map { "    #{_1}" },
+        "  end",
+        "",
+        "  def #{step.body}: (#{params.join(", ")}) -> #{returns}",
+        "end",
+        ""
+      ].join("\n")
+    end
+  end
+end

data/lib/nukadoko/step.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+# A step is a class under features/steps/, one per file, named by its file.
+# Everything except the body is a class-level declaration, so check reads the
+# contract without calling the body, and `Method#parameters` names the
+# fixtures the body asks for.
+module Nukadoko
+  class Step
+    class << self
+      attr_reader :file
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@file, caller_locations(1, 1).first.absolute_path)
+        Step.registry << subclass
+      end
+
+      def registry = (@registry ||= [])
+
+      def pattern(text = nil) = text ? (@pattern = text) : @pattern
+      def description(text = nil) = text ? (@description = text) : @description
+      def mutates(value = nil) = value.nil? ? @mutates : (@mutates = value)
+      def claims(list = nil) = list ? (@claims = list) : @claims
+      def poll(value = nil) = value.nil? ? @poll : (@poll = value)
+
+      # The steps this one may run through the `call` fixture. A part with no
+      # pattern exists only for calls.
+      def parts(list = nil) = list ? (@parts = list.freeze) : (@parts || [])
+
+      def args(&block) = block ? (@args = Schema.build(&block)) : (@args ||= Schema.new)
+      def returns(&block) = block ? (@returns = Schema.build(&block)) : @returns
+
+      # Args an earlier step of the scenario returned, by key: one source as
+      # `[Step, :field]`, or several as a list of them, where the nearest
+      # earlier one that ran gives the value.
+      def from(map = nil)
+        return @from || {} unless map
+
+        @from = map.to_h { |key, source| [key.to_s, source.first.is_a?(Array) ? source : [source]] }
+      end
+
+      # observe never sees the args a claim compares with, so it cannot pick
+      # what to read by the answer it will be judged against.
+      def inputs = claims ? args.without(expected_keys(claims)) : args
+
+      def step_name = File.basename(file, ".rb").tr("_", "-")
+
+      # A step that runs code may change the world unless it says it does
+      # not; a claim step has no action, so it never does.
+      def mutating? = claims ? false : mutates != false
+      def body = claims ? :observe : :run
+      def line = method_defined?(body) ? instance_method(body).source_location&.last : nil
+
+      def fixtures
+        return [] unless method_defined?(body)
+
+        instance_method(body).parameters.filter_map { |kind, name| name if kind == :keyreq && name != :args }
+      end
+
+      # The fixtures the engine builds before the body runs: the step's own,
+      # and those of every part it can reach, since the bag is closed before
+      # any call happens.
+      def bag(seen = [])
+        return [] if seen.include?(self)
+
+        reachable = parts.select { _1.is_a?(Class) && _1 < Step }.flat_map { _1.bag([*seen, self]) }
+        (fixtures + reachable - (seen.empty? ? [] : [:call])).uniq
+      end
+
+      private
+
+      def expected_keys(node)
+        case node
+        in Array then node.flat_map { expected_keys(_1) }
+        in Hash then node.flat_map { |k, v| k.to_s == "expected" ? expected_key(v) : expected_keys(v) }
+        else []
+        end
+      end
+
+      def expected_key(value)
+        case value
+        in String then [value]
+        in { from: String => key } then [key]
+        else []
+        end
+      end
+    end
+  end
+
+  # Each step file is registered for autoload under its class name first, so a
+  # step can name another in `from` or `field` whatever order the files load in.
+  def self.load_steps(dir)
+    files = Dir.glob(File.join(dir, "**/*.rb")).sort.map { File.expand_path(_1) }
+    files.each { Object.autoload(File.basename(_1, ".rb").split("_").map(&:capitalize).join.to_sym, _1) }
+    files.each { require _1 }
+    Step.registry
+  end
+end

data/lib/nukadoko/table.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# The run's verdict table: a row per criterion (a scenario, or an Examples
+# row), a cell per environment. A cell is `required` where its environment
+# meets the row's condition tags and a `control` elsewhere. Only a control
+# that fails at a Then, the same way, in every proof run proves a row.
+module Nukadoko
+  module Engine
+    module Table
+      PROOF_RUNS = 2
+
+      def self.role(tags, conditions)
+        meets = tags.all? do |tag|
+          case tag
+          when /\A@with:([\w.-]+)=(\S+)\z/ then conditions[Regexp.last_match(1)].to_s == Regexp.last_match(2)
+          when /\A@with:([\w.-]+)\z/ then ![nil, false].include?(conditions[Regexp.last_match(1)])
+          when /\A@without:([\w.-]+)\z/ then [nil, false].include?(conditions[Regexp.last_match(1)])
+          else true
+          end
+        end
+        meets ? "required" : "control"
+      end
+
+      # What a cell's executions came to. An execution is `[:pass]`,
+      # `[:fail, line, claim]`, or `[:broke, line]`.
+      def self.cell(executions)
+        first = executions.first
+        if executions.uniq.size > 1
+          line = executions.find { _1.first != :pass }&.at(1)
+          { outcome: "flaky", line: line }
+        elsif first.first == :pass then { outcome: "pass" }
+        else { outcome: first.first.to_s, line: first[1] }
+        end.merge(runs: executions.size)
+      end
+
+      def self.verdict(cells)
+        required = cells.select { _1[:role] == "required" }
+        return "failed" if required.empty? || required.any? { _1[:outcome] != "pass" }
+
+        proven = cells.any? { _1[:role] == "control" && _1[:outcome] == "fail" && _1[:runs] >= PROOF_RUNS }
+        proven ? "proven" : "held"
+      end
+
+      def self.condition_tags(tags) = tags.grep(/\A@with(out)?:/)
+    end
+  end
+end

data/lib/nukadoko/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Nukadoko
+  VERSION = "0.1.0"
+end

data/lib/nukadoko/vocabulary.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# What `nuka steps` and `nuka describe` print: each step as data, in the
+# fields the TypeScript engine prints, so an agent picks a step from either
+# engine's vocabulary without opening a file.
+module Nukadoko
+  module Vocabulary
+    BROWSER = %i[page context pageAs].freeze
+
+    def self.entry(step, project)
+      {
+        name: step.step_name, kind: "typed", file: step.file.delete_prefix("#{project}/"),
+        patterns: [step.pattern].compact, description: step.description, mutates: step.mutating?,
+        parts: step.parts.empty? ? nil : step.parts.map(&:step_name),
+        from: from(step), claims: step.claims, poll: step.poll,
+        needs: step.bag.map(&:to_s).sort, needs_browser: step.bag.intersect?(BROWSER)
+      }.compact
+    end
+
+    def self.describe(step, project)
+      # A step with no returns returns an empty object, as zod's default says.
+      returns = step.returns&.json_schema(output: true) || { "$schema": "https://json-schema.org/draft/2020-12/schema", default: {}, type: "object", properties: {}, additionalProperties: false }
+      entry(step, project).merge(args: step.args.json_schema, returns: returns)
+    end
+
+
+    def self.from(step)
+      return nil if step.from.empty?
+
+      step.from.transform_values do |sources|
+        named = sources.map { |cls, key| { step: cls.step_name, key: key.to_s } }
+        named.size == 1 ? named.first : named
+      end
+    end
+
+    def self.text(step)
+      lines = ["#{step.step_name}  typed  #{step.claims ? "claims" : step.mutating? ? "mutates" : "read-only"}",
+               "  #{step.pattern || "(no pattern)"}", "  #{step.description}"]
+      (step.claims || []).each { lines << "  claim: #{claim_text(_1)}" }
+      ((step.poll.is_a?(Hash) && step.poll[:settled]) || []).each { lines << "  settled: #{claim_text(_1)}" }
+      lines.join("\n")
+    end
+
+    def self.claim_text(claim)
+      return "each #{claim[:actual]}" if claim[:each]
+
+      actual = [claim[:actual], claim[:view] && "as #{claim[:view]}", claim[:at] && "at #{claim[:at]}"].compact.join(" ")
+      expected = case claim[:expected]
+                 in String => key then key
+                 in { literal: value } then value.to_json
+                 in { from: key } then "from #{key}"
+                 end
+      "#{actual} #{claim[:compare]} #{expected}"
+    end
+  end
+end

data/lib/nukadoko.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "nukadoko/version"
+require_relative "nukadoko/schema"
+require_relative "nukadoko/step"
+require_relative "nukadoko/pattern"
+require_relative "nukadoko/features"
+require_relative "nukadoko/claims"
+require_relative "nukadoko/check"
+require_relative "nukadoko/fixtures"
+require_relative "nukadoko/command"
+require_relative "nukadoko/project_fixtures"
+require_relative "nukadoko/parts"
+require_relative "nukadoko/poll"
+require_relative "nukadoko/definition"
+require_relative "nukadoko/vocabulary"
+require_relative "nukadoko/program"
+require_relative "nukadoko/table"
+require_relative "nukadoko/run"
+require_relative "nukadoko/signature"
+
+module Nukadoko
+  def self.program(**options) = (@program = options)
+  def self.program_options = @program || {}
+  def self.config(**options) = (@config = options)
+  def self.config_options = @config || {}
+end