fix 1.0.0.beta12 → 1.0.0

data/lib/fix/spec.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "aw"
+require "defi"
+
+require_relative "dsl"
+require_relative "result"
+
+module Fix
+  # The lib directories of fix and of the gems it runs, each found by a
+  # method or a module its root file defines, not by the name of a file,
+  # which another file could bear: their frames are left out of a backtrace
+  # printed by {Spec#test}.
+  LIBRARIES = ([
+    ::Aw.method(:fork!).source_location,
+    ::Object.const_source_location("Defi"),
+    ::Object.const_source_location("Matchi"),
+    ::Spectus.method(:must).source_location
+  ].map { |location| "#{::File.dirname(location.fetch(0))}/" } << "#{::File.expand_path("..", __dir__)}/").freeze
+  private_constant :LIBRARIES
+
+  # A specification: its name and its contexts, built once by {Fix.spec} and
+  # never changed. Tested against a subject with {#run} or {#test}, it is
+  # also a matcher: {#match?} tests a value, as `it MUST fix(:Name)` does.
+  #
+  # @!attribute [r] name
+  #   @return [Symbol, nil] the name, nil for an anonymous specification
+  # @!attribute [r] nodes
+  #   @return [Array<Fix::Node>] the contexts, each before its children
+  #   @api private
+  Spec = ::Data.define(:name, :nodes) do
+    # Tests a subject against every expectation, each context in a child
+    # process, and gives the results. The block builds the subject: it runs
+    # once per expectation, where the lets live.
+    #
+    # @param fork [Boolean] whether each context runs in a child process;
+    #   `false` for a debugger only
+    # @yieldreturn [Object] the subject
+    # @return [Array<Fix::Result>] in the order of the contexts, then of
+    #   their expectations
+    # @raise [ArgumentError] without a block
+    # @raise [NotImplementedError] when this Ruby cannot fork
+    # @raise [Aw::ChildError] when a child died or delivered no result
+    # @raise [TypeError] when the `to_s` of a matcher is not a String; what a
+    #   child raised outside an expectation is raised here again
+    def run(fork: true, &subject)
+      raise ::ArgumentError, "a block must be given" unless subject
+
+      nodes.flat_map { |node| results(node, fork, subject) }
+    end
+
+    # Like {#run}, writing each result on the standard output as its
+    # context ends, one line each, with the backtrace of an error below.
+    #
+    # @param fork [Boolean] as for {#run}
+    # @yieldreturn [Object] the subject
+    # @return [Boolean] whether every expectation is met
+    # @raise (see #run)
+    def test(fork: true, &subject) # rubocop:disable Naming/PredicateMethod
+      raise ::ArgumentError, "a block must be given" unless subject
+
+      nodes.map do |node|
+        results(node, fork, subject).each { |result| $stdout.puts(lines(result)) }.all?(&:passed?)
+      end.all?
+    end
+
+    # Tests a value, as a matcher does: the block is called once, and its
+    # value is the subject of every expectation.
+    #
+    # @yieldreturn [Object] the value
+    # @return [Boolean] whether every expectation is met
+    # @raise (see #run)
+    def match?
+      raise ::ArgumentError, "a block must be given" unless block_given?
+
+      value = yield
+      run { value }.all?(&:passed?)
+    end
+
+    # @return [String] `fix NAME`, or `fix an anonymous specification`
+    def to_s
+      "fix #{name || "an anonymous specification"}"
+    end
+
+    alias_method :inspect, :to_s
+
+    private
+
+    # The results of a context, from a child process or not.
+    def results(node, fork, subject)
+      return [] if node.expectations.empty?
+
+      work = -> { examine(node, subject) }
+      spectus = fork ? ::Aw.fork!(&work) : work.call
+      node.expectations.zip(spectus).map do |expectation, result|
+        Result.new(location: expectation.location, chain: node.chain, result:)
+      end
+    end
+
+    # The results of the expectations of a context, in the process that works
+    # on them. A process the subject forked and let run on, instead of ending
+    # it with exit!, is not that one: it leaves here without a word.
+    def examine(node, subject)
+      pid = ::Process.pid
+      node.expectations.map do |expectation|
+        result = judge(node, expectation, subject)
+        ::Process.exit! unless ::Process.pid == pid
+
+        result
+      end
+    end
+
+    # One expectation, in a new environment: the subject is built, the
+    # chain is sent, and the requirement judges what came out. A method of
+    # the chain missing on its receiver makes a MAY an info, as a method
+    # missing on the actual value does for Spectus, when the error that
+    # came out is a NoMethodError by its class name: an exception of a
+    # subclass, which Ruby does not raise for a missing method, stays an
+    # error.
+    def judge(node, expectation, subject)
+      environment = Environment.new(node.lets)
+      missing = false
+      result = expectation.requirement.call do
+        value, missing = actual(node, environment, subject)
+        value.call
+      end
+      omission = missing && expectation.requirement.level.equal?(:MAY) && result.error_class == "NoMethodError"
+      omission ? result.with(outcome: :info) : result
+    end
+
+    # The subject through the chain: a value, and whether the chain stopped
+    # on a method missing on its receiver.
+    def actual(node, environment, subject)
+      object = environment.instance_exec(&subject)
+      node.challenges.each do |challenge|
+        value = challenge.to(object)
+        return [value, missing?(value.object, object, challenge)] if value.raised?
+
+        object = value.object
+      end
+      [::Defi::Value.new(object, false), false]
+    end
+
+    # Whether an exception is a NoMethodError for the method of the
+    # challenge on the very object it was sent to, read as NameError and
+    # BasicObject do, whatever the objects say. A NoMethodError built by
+    # hand without a receiver raises ArgumentError when asked for it: it
+    # names no object, so the method is not missing on one.
+    def missing?(exception, object, challenge)
+      return false unless ::NoMethodError === exception
+
+      receiver = ::NameError.instance_method(:receiver).bind_call(exception)
+      ::BasicObject.instance_method(:equal?).bind_call(receiver, object) &&
+        challenge.name.equal?(::NameError.instance_method(:name).bind_call(exception))
+    rescue ::ArgumentError
+      false
+    end
+
+    # The line of a result, then the frames of an error that are not ours,
+    # each on one line too.
+    def lines(result)
+      frames = result.outcome == :error ? (result.result.backtrace || []) : []
+      frames = frames.reject { |frame| frame.start_with?(*LIBRARIES) }
+      [result.to_s] + frames.map { |frame| "  #{frame.gsub(/\R/) { "\\n" }}" }
+    end
+  end
+end

data/lib/fix.rb

@@ -1,22 +1,52 @@
 # frozen_string_literal: true
 
-require_relative File.join("fix", "set")
-
+require_relative "fix/spec"
 require_relative "kernel"
 
-# Namespace for the Fix framework.
+# Specifications with the MUST, SHOULD and MAY of RFC 2119. A specification
+# says what a value must, should or may do, in a document free of logic;
+# any subject is then tested against it, each context in a process of its
+# own.
+#
+# @example
+#   Fix :Duck do
+#     on(:swims) { it MUST eq "Swoosh..." }
+#     on(:sings) { it MAY eq "♪... ♫..." }
+#   end
 #
-# @api public
+#   Fix[:Duck].test { Duck.new } # => true
 module Fix
-  # Test a built specification.
-  #
-  # @example Run _Answer_ specification against `42`.
-  #   Fix[:Answer].test { 42 }
-  #
-  # @param name [String, Symbol] The constant name of the specifications.
+  @specs = {}.freeze
+
+  # Builds a specification, and registers it under its name once it is
+  # built: a block that raises registers nothing.
   #
-  # @return [::Fix::Test] The specification document.
+  # @param name [Symbol, nil] the name, or nil for an anonymous specification
+  # @yield the document, written with {Fix::Dsl}
+  # @return [Fix::Spec]
+  # @raise [ArgumentError] without a block, with a name that is not a Symbol
+  #   or that is already registered, or for a mistake in a word of the
+  #   document
+  # @raise [NameError] for a let named in an expectation
+  # @raise [KeyError] for a `fix(:Name)` not registered yet
+  def self.spec(name = nil, &block)
+    raise ::ArgumentError, "a block must be given" unless block
+    raise ::ArgumentError, "the name must be a Symbol" unless name.nil? || ::Symbol === name
+
+    spec = Spec.new(name:, nodes: Dsl.build(&block))
+    return spec if name.nil?
+    raise ::ArgumentError, "#{name.inspect} is already a specification" if @specs.key?(name)
+
+    @specs = @specs.merge(name => spec).freeze
+    spec
+  end
+
+  # @param name [Symbol] the name of a registered specification
+  # @return [Fix::Spec]
+  # @raise [KeyError] when no specification has that name
   def self.[](name)
-    ::Fix::Set.load(name)
+    @specs.fetch(name) do
+      raise ::KeyError.new("no specification named #{name.inspect}", receiver: @specs, key: name)
+    end
   end
 end

data/lib/kernel.rb

@@ -1,38 +1,17 @@
 # frozen_string_literal: true
 
-require_relative File.join("fix", "doc")
-require_relative File.join("fix", "dsl")
-require_relative File.join("fix", "set")
-
-# The Kernel module.
+# The `Fix` method, private: callable at the top level of a file, not on an
+# object.
 module Kernel
-  # rubocop:disable Naming/MethodName
+  private
 
-  # Specifications are built with this method.
-  #
-  # @example Require an answer equal to 42.
-  #   # The spec
-  #   Fix :Answer do
-  #     it MUST equal 42
-  #   end
-  #
-  #   # A test
-  #   Fix[:Answer].test { 42 }
+  # Builds a specification: `Fix :Name do … end`, or `Fix do … end` for an
+  # anonymous one. See {Fix.spec}.
   #
-  # @param name [String, Symbol] The constant name of the specifications.
-  # @yield The specifications block that defines the test requirements
-  # @yieldreturn [void]
-  #
-  # @return [#test] The collection of specifications.
-  #
-  # @api public
-  def Fix(name = nil, &)
-    klass = ::Class.new(::Fix::Dsl)
-    klass.const_set(:CONTEXTS, [klass])
-    klass.instance_eval(&)
-    ::Fix::Doc.const_set(name, klass) unless name.nil?
-    ::Fix::Set.new(*klass.const_get(:CONTEXTS))
+  # @param name [Symbol, nil] the name
+  # @yield the document, written with {Fix::Dsl}
+  # @return [Fix::Spec]
+  def Fix(name = nil, &) # rubocop:disable Naming/MethodName
+    ::Fix.spec(name, &)
   end
-
-  # rubocop:enable Naming/MethodName
 end

metadata

@@ -1,57 +1,73 @@
 --- !ruby/object:Gem::Specification
 name: fix
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta12
+  version: 1.0.0
 platform: ruby
 authors:
 - Cyril Kato
 bindir: bin
 cert_chain: []
-date: 2024-12-31 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: aw
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: defi
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.0.0
+        version: '4.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.0.0
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: matchi
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 4.1.0
+        version: '6.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 4.1.0
+        version: '6.0'
 - !ruby/object:Gem::Dependency
   name: spectus
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 5.0.1
+        version: '6.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 5.0.1
-description: Specing framework.
+        version: '6.0'
+description: A specification says what a subject MUST, SHOULD or MAY do, and nothing
+  about how it is made. Any subject is then tested against it, each context in a child
+  process, and every expectation gets a result.
 email: contact@cyril.email
 executables: []
 extensions: []
@@ -60,22 +76,22 @@ files:
 - LICENSE.md
 - README.md
 - lib/fix.rb
-- lib/fix/doc.rb
 - lib/fix/dsl.rb
+- lib/fix/environment.rb
+- lib/fix/level.rb
 - lib/fix/matcher.rb
-- lib/fix/requirement.rb
-- lib/fix/run.rb
-- lib/fix/set.rb
+- lib/fix/node.rb
+- lib/fix/result.rb
+- lib/fix/spec.rb
 - lib/kernel.rb
-homepage: https://fixrb.dev/
+homepage: https://fixrb.dev/gems/fix/
 licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/fixrb/fix/issues
   documentation_uri: https://rubydoc.info/gems/fix
-  source_code_uri: https://github.com/fixrb/fix
-  wiki_uri: https://github.com/fixrb/fix/wiki
   rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/fixrb/fix
 rdoc_options: []
 require_paths:
 - lib
@@ -83,14 +99,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 4.0.23
 specification_version: 4
-summary: Specing framework.
+summary: Specifications in the words of RFC 2119, tested against a subject
 test_files: []

data/lib/fix/doc.rb

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-module Fix
-  # Module for storing spec documents.
-  #
-  # @api private
-  module Doc
-    # @param name [String, Symbol] The constant name of the specifications.
-    def self.fetch(name)
-      const_get("#{name}::CONTEXTS")
-    end
-
-    # @param contexts [Array<::Fix::Dsl>] The list of contexts document.
-    def self.specs(*contexts)
-      contexts.flat_map do |context|
-        env = context.new
-
-        env.public_methods(false).map do |public_method|
-          [env] + env.public_send(public_method)
-        end
-      end
-    end
-  end
-end

data/lib/fix/requirement.rb

@@ -1,87 +0,0 @@
-# frozen_string_literal: true
-
-require "spectus/requirement/optional"
-require "spectus/requirement/recommended"
-require "spectus/requirement/required"
-
-module Fix
-  # Collection of expectation matchers.
-  #
-  # @api private
-  module Requirement
-    # rubocop:disable Naming/MethodName
-
-    # This method mean that the definition is an absolute requirement of the
-    # specification.
-    #
-    # @param matcher [#match?] The matcher.
-    #
-    # @return [Requirement::Required] An absolute requirement level instance.
-    #
-    # @api public
-    def MUST(matcher)
-      ::Spectus::Requirement::Required.new(negate: false, matcher:)
-    end
-
-    # This method mean that the definition is an absolute prohibition of the specification.
-    #
-    # @param matcher [#match?] The matcher.
-    #
-    # @return [Requirement::Required] An absolute prohibition level instance.
-    #
-    # @api public
-    def MUST_NOT(matcher)
-      ::Spectus::Requirement::Required.new(negate: true, matcher:)
-    end
-
-    # This method mean that there may exist valid reasons in particular
-    # circumstances to ignore a particular item, but the full implications must be
-    # understood and carefully weighed before choosing a different course.
-    #
-    # @param matcher [#match?] The matcher.
-    #
-    # @return [Requirement::Recommended] A recommended requirement level instance.
-    #
-    # @api public
-    def SHOULD(matcher)
-      ::Spectus::Requirement::Recommended.new(negate: false, matcher:)
-    end
-
-    # This method mean that there may exist valid reasons in particular
-    # circumstances when the particular behavior is acceptable or even useful, but
-    # the full implications should be understood and the case carefully weighed
-    # before implementing any behavior described with this label.
-    #
-    # @param matcher [#match?] The matcher.
-    #
-    # @return [Requirement::Recommended] A not recommended requirement level
-    #   instance.
-    #
-    # @api public
-    def SHOULD_NOT(matcher)
-      ::Spectus::Requirement::Recommended.new(negate: true, matcher:)
-    end
-
-    # This method mean that an item is truly optional.
-    # One vendor may choose to include the item because a particular marketplace
-    # requires it or because the vendor feels that it enhances the product while
-    # another vendor may omit the same item. An implementation which does not
-    # include a particular option must be prepared to interoperate with another
-    # implementation which does include the option, though perhaps with reduced
-    # functionality. In the same vein an implementation which does include a
-    # particular option must be prepared to interoperate with another
-    # implementation which does not include the option (except, of course, for the
-    # feature the option provides).
-    #
-    # @param matcher [#match?] The matcher.
-    #
-    # @return [Requirement::Optional] An optional requirement level instance.
-    #
-    # @api public
-    def MAY(matcher)
-      ::Spectus::Requirement::Optional.new(negate: false, matcher:)
-    end
-
-    # rubocop:enable Naming/MethodName
-  end
-end

data/lib/fix/run.rb

@@ -1,55 +0,0 @@
-# frozen_string_literal: true
-
-require "expresenter/fail"
-
-module Fix
-  # Run class.
-  #
-  # @api private
-  class Run
-    # @return [::Fix::Dsl] A context instance.
-    attr_reader :environment
-
-    # @return [::Spectus::Requirement::Base] An expectation.
-    attr_reader :requirement
-
-    # @return [Array<::Defi::Method>] A list of challenges.
-    attr_reader :challenges
-
-    # @param environment  [::Fix::Dsl]                    A context instance.
-    # @param requirement  [::Spectus::Requirement::Base]  An expectation.
-    # @param challenges   [Array<::Defi::Method>]         A list of challenges.
-    def initialize(environment, requirement, *challenges)
-      @environment = environment
-      @requirement = requirement
-      @challenges  = challenges
-    end
-
-    # Verify if the object checks the condition.
-    #
-    # @param subject [Proc] The block of code to be tested.
-    #
-    # @raise [::Expresenter::Fail] A failed spec exception.
-    # @return [::Expresenter::Pass] A passed spec instance.
-    #
-    # @see https://github.com/fixrb/expresenter
-    def test(&subject)
-      requirement.call { actual_value(&subject) }
-    rescue ::Expresenter::Fail => e
-      e
-    end
-
-    private
-
-    # The test's actual value.
-    #
-    # @param subject [Proc] The block of code to be tested.
-    #
-    # @return [#object_id] The actual value to be tested.
-    def actual_value(&subject)
-      challenges.inject(environment.instance_eval(&subject)) do |obj, challenge|
-        challenge.to(obj).call
-      end
-    end
-  end
-end

data/lib/fix/set.rb

@@ -1,67 +0,0 @@
-# frozen_string_literal: true
-
-require "English"
-
-require_relative "doc"
-require_relative "run"
-
-module Fix
-  # Collection of specifications.
-  #
-  # @api private
-  class Set
-    # @return [Array] A list of specifications.
-    attr_reader :specs
-
-    # Load specifications from a constant name.
-    #
-    # @param name [String, Symbol] The constant name of the specifications.
-    # @return [Set] A new Set instance containing the loaded specifications.
-    #
-    # @api public
-    def self.load(name)
-      new(*Doc.fetch(name))
-    end
-
-    # Initialize a new Set with given contexts.
-    #
-    # @param contexts [Array<::Fix::Dsl>] The list of contexts document.
-    def initialize(*contexts)
-      @specs = Doc.specs(*contexts).shuffle
-    end
-
-    # Run the test suite against the provided subject.
-    #
-    # @yield The block of code to be tested
-    # @yieldreturn [Object] The result of the code being tested
-    # @return [Boolean] true if all tests pass, exits with false otherwise
-    # @raise [::SystemExit] The test set failed!
-    #
-    # @api public
-    def test(&)
-      suite_passed?(&) || ::Kernel.exit(false)
-    end
-
-    private
-
-    def suite_passed?(&subject)
-      specs.all? { |spec| run_spec(*spec, &subject) }
-    end
-
-    def run_spec(env, location, requirement, challenges, &subject)
-      ::Process.fork { lab(env, location, requirement, challenges, &subject) }
-      ::Process.wait
-      $CHILD_STATUS.success?
-    end
-
-    def lab(env, location, requirement, challenges, &)
-      result = Run.new(env, requirement, *challenges).test(&)
-      report!(location, result)
-      ::Kernel.exit(result.passed?)
-    end
-
-    def report!(path, result)
-      puts "#{path} #{result.colored_string}"
-    end
-  end
-end