fix 1.0.0.beta11 → 1.0.0

data/lib/fix/dsl.rb

@@ -1,122 +1,174 @@
 # frozen_string_literal: true
 
-require "defi/method"
+require "defi"
+require "spectus"
 
+require_relative "environment"
+require_relative "level"
 require_relative "matcher"
-require_relative "requirement"
+require_relative "node"
 
 module Fix
-  # Abstract class for handling the domain-specific language.
+  # The language of a specification. The block of `Fix :Name do … end` runs
+  # on an instance of this class, thrown away afterwards, whose four words
+  # build the contexts of the specification: `let`, `with`, `on` and `it`.
+  # The matchers ({Fix::Matcher}) and the levels ({Fix::Level}) are words of
+  # it too.
   #
-  # @api private
+  # A gem may add a word that composes these four: fix-its adds `its`.
   class Dsl
-    extend Matcher
-    extend Requirement
+    include Level
+    include Matcher
 
-    # Sets a user-defined property.
-    #
-    # @example
-    #   require "fix"
-    #
-    #   Fix do
-    #     let(:name) { "Bob" }
-    #   end
-    #
-    # @param name [String, Symbol] The name of the property.
-    # @yield The block that defines the property's value
-    # @yieldreturn [Object] The value to be returned by the property
-    #
-    # @return [Symbol] A private method that define the block content.
-    #
-    # @api public
-    def self.let(name, &)
-      private define_method(name, &)
+    # The four words.
+    WORDS = %i[let with on it].freeze
+    private_constant :WORDS
+
+    # @yield the document of a specification
+    # @return [Array<Fix::Node>] its contexts, each before its children
+    def self.build(&)
+      dsl = new({}.freeze, [].freeze, "")
+      dsl.instance_exec(&)
+      dsl.nodes.freeze
     end
 
-    # Defines an example group with user-defined properties that describes a
-    # unit to be tested.
-    #
-    # @example
-    #   require "fix"
-    #
-    #   Fix do
-    #     with password: "secret" do
-    #       it MUST be true
-    #     end
-    #   end
-    #
-    # @param kwargs [Hash] The list of propreties.
-    # @yield The block that defines the specs for this context
-    # @yieldreturn [void]
-    #
-    # @api public
-    def self.with(**kwargs, &)
-      klass = ::Class.new(self)
-      klass.const_get(:CONTEXTS) << klass
-      kwargs.each { |name, value| klass.let(name) { value } }
-      klass.instance_eval(&)
-      klass
+    # @param lets [Hash{Symbol => Proc}] the lets inherited, frozen
+    # @param challenges [Array<Defi::Challenge>] the chain inherited, frozen
+    # @param chain [String] its text
+    # @param own [Array<Symbol>] the lets this context declares already,
+    #   those a `with` gave it
+    # @api private
+    def initialize(lets, challenges, chain, own = [])
+      @lets = lets
+      @challenges = challenges
+      @chain = chain
+      @own = own
+      @expectations = []
+      @children = []
     end
 
-    # Defines an example group that describes a unit to be tested.
-    #
-    # @example
-    #   require "fix"
-    #
-    #   Fix do
-    #     on :+, 2 do
-    #       it MUST be 42
-    #     end
-    #   end
-    #
-    # @param method_name [String, Symbol] The method to send to the subject.
-    # @param block [Proc] The block to define the specs.
-    #
-    # @api public
-    def self.on(method_name, *args, **kwargs, &block)
-      klass = ::Class.new(self)
-      klass.const_get(:CONTEXTS) << klass
+    # @return [Array<Fix::Node>] this context, then its children, as they
+    #   stand
+    def nodes
+      node = Node.new(lets: @lets, challenges: @challenges, chain: @chain, expectations: @expectations.dup.freeze)
+      [node] + @children
+    end
 
-      const_set(:"Child#{block.object_id}", klass)
+    # A parameter of the subject: its block runs where the subject is built,
+    # once per expectation, and may call other lets. A let is not visible
+    # from an expectation.
+    #
+    # @param name [Symbol] its name, which is not a method of the environment
+    #   nor a word of the language, and not a let of this context already
+    # @yieldreturn [Object] its value
+    # @return [nil]
+    # @raise [ArgumentError] otherwise, or without a block
+    def let(name, &block)
+      raise ::ArgumentError, "a block must be given" unless block
 
-      klass.define_singleton_method(:challenges) do
-        challenge = ::Defi::Method.new(method_name, *args, **kwargs)
-        super() + [challenge]
-      end
+      free!(name)
+      raise ::ArgumentError, "#{name} is already a let of this context" if @own.include?(name)
 
-      klass.instance_eval(&block)
-      klass
+      @own << name
+      @lets = @lets.merge(name => block).freeze
+      nil
     end
 
-    # Defines a concrete spec definition.
-    #
-    # @example
-    #   require "fix"
-    #
-    #   Fix { it MUST be 42 }
-    #
-    #   Fix do
-    #     it { MUST be 42 }
-    #   end
-    #
-    # @api public
-    def self.it(requirement = nil, &block)
-      raise ::ArgumentError, "Must provide either requirement or block, not both" if requirement && block
-      raise ::ArgumentError, "Must provide either requirement or block" unless requirement || block
+    # A context where lets take the values given: the objects themselves,
+    # shared by the expectations of the context, which declares these lets.
+    #
+    # @param values [Hash{Symbol => Object}] the lets, by name
+    # @yield the context
+    # @return [nil]
+    # @raise [ArgumentError] for a name a let could not take, without a value
+    #   or without a block
+    def with(**values, &block)
+      raise ::ArgumentError, "a block must be given" unless block
+      raise ::ArgumentError, "a with gives a value to a let: with(name: 1)" if values.empty?
 
-      location = caller_locations(1, 1).fetch(0)
-      location = [location.path, location.lineno].join(":")
+      values.each_key { |name| free!(name) }
+      lets = @lets.merge(values.transform_values { |value| -> { value } }).freeze
+      context(lets, @challenges, @chain, values.keys, &block)
+    end
+
+    # A context about what a method of the subject returns, or raises: the
+    # method is sent, with its arguments, to the value of the context above.
+    # No block can be given to the method: the block is the context.
+    #
+    # @param name [Symbol] the method, followed by its positional and keyword
+    #   arguments, as they would be written after it
+    # @yield the context
+    # @return [nil]
+    # @raise [ArgumentError] when the name is not a Symbol, or without a block
+    def on(name, *, **, &block)
+      raise ::ArgumentError, "a block must be given" unless block
 
-      define_method(:"test_#{(requirement || block).object_id}") do
-        [location, requirement || singleton_class.class_eval(&block), self.class.challenges]
-      end
+      challenge = ::Defi::Challenge.new(name, *, **)
+      context(@lets, (@challenges + [challenge]).freeze, text("#{@chain}#{challenge}"), &block)
     end
 
-    # The list of challenges to be addressed to the object to be tested.
-    #
-    # @return [Array<Defi::Method>] A list of challenges.
-    def self.challenges
-      []
+    # An expectation: a requirement, built here and now with a level and a
+    # matcher, at the line of the call.
+    #
+    # @param requirement [Spectus::Requirement] `MUST eq(1)`, say
+    # @param location [Thread::Backtrace::Location, nil] where the expectation
+    #   is written, for a word that composes `it`; the caller of `it` otherwise
+    # @return [nil]
+    # @raise [ArgumentError] without a requirement, or with a block
+    # @raise [TypeError] when the `to_s` of the matcher is not a String
+    def it(requirement = nil, location: nil, &block)
+      raise ::ArgumentError, "it takes a requirement, not a block: it MUST eq(1)" if block
+      raise ::ArgumentError, "it takes a requirement: it MUST eq(1)" unless ::Spectus::Requirement === requirement
+      raise ::TypeError, "the to_s of the matcher must be a String" unless ::String === requirement.matcher.to_s
+
+      location ||= caller_locations(1, 1).fetch(0)
+      @expectations << Expectation.new(location: locate(location), requirement:)
+      nil
+    end
+
+    private
+
+    # A let named in an expectation is a mistake with a remedy.
+    def method_missing(name, ...)
+      return super unless @lets.key?(name)
+
+      raise ::NameError.new("#{name} is a let, visible in the subject block and in other lets only", name)
+    end
+
+    def respond_to_missing?(_name, _include_private = false)
+      false
+    end
+
+    # A child context, whose nodes follow this one's.
+    def context(lets, challenges, chain, own = [], &)
+      child = Dsl.new(lets, challenges, chain, own)
+      child.instance_exec(&)
+      @children.concat(child.nodes)
+      nil
+    end
+
+    # A name a let can take: a Symbol that is not a method of the environment,
+    # public or private, nor a public word of the language, so that nothing
+    # is redefined in silence.
+    def free!(name)
+      raise ::ArgumentError, "the name of a let must be a Symbol" unless ::Symbol === name
+      raise ::ArgumentError, "#{name} is a word of the specification language" if WORDS.include?(name)
+
+      owner = [Environment, Dsl].find { |klass| klass.method_defined?(name) }
+      owner ||= Environment if Environment.private_method_defined?(name)
+      raise ::ArgumentError, "#{name} is already a method of #{owner.instance_method(name).owner}" if owner
+    end
+
+    # `file:line`, the file relative to the current directory when it is
+    # under it.
+    def locate(location)
+      path = ::File.absolute_path(location.path).delete_prefix(::File.join(::Dir.pwd, ""))
+      text("#{path}:#{location.lineno}")
+    end
+
+    # A text of a result, valid UTF-8 and frozen, as those of Spectus.
+    def text(string)
+      string.encode(::Encoding::UTF_8, invalid: :replace, undef: :replace).freeze
     end
   end
 end

data/lib/fix/environment.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Fix
+  # Where a subject is built: an object with a method for each let, whose
+  # value is computed once, the first time it is called, by running the
+  # block of the let here, so that a let can call another. A new environment
+  # is made for each expectation. It is an ordinary object, so that the
+  # blocks of a specification can call `Kernel` and the private methods of
+  # the top level, as any Ruby code does.
+  #
+  # @api private
+  class Environment
+    # @param lets [Hash{Symbol => Proc}] the lets of a context
+    def initialize(lets)
+      values = {}
+      lets.each do |name, block|
+        define_singleton_method(name) do
+          values.fetch(name) { values[name] = instance_exec(&block) }
+        end
+      end
+    end
+  end
+
+  private_constant :Environment
+end

data/lib/fix/level.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "spectus"
+
+module Fix
+  # The requirement levels of RFC 2119, as the words of a specification:
+  # each one turns a matcher into a `Spectus::Requirement`. A MAY has no
+  # negative form.
+  module Level
+    # @param matcher [#match?] the matcher
+    # @return [Spectus::Requirement] an absolute requirement
+    def MUST(matcher) # rubocop:disable Naming/MethodName
+      ::Spectus.must(matcher)
+    end
+
+    # @param matcher [#match?] the matcher
+    # @return [Spectus::Requirement] an absolute prohibition
+    def MUST_NOT(matcher) # rubocop:disable Naming/MethodName
+      ::Spectus.must_not(matcher)
+    end
+
+    # @param matcher [#match?] the matcher
+    # @return [Spectus::Requirement] a recommendation
+    def SHOULD(matcher) # rubocop:disable Naming/MethodName
+      ::Spectus.should(matcher)
+    end
+
+    # @param matcher [#match?] the matcher
+    # @return [Spectus::Requirement] a negated recommendation
+    def SHOULD_NOT(matcher) # rubocop:disable Naming/MethodName
+      ::Spectus.should_not(matcher)
+    end
+
+    # @param matcher [#match?] the matcher
+    # @return [Spectus::Requirement] an option
+    def MAY(matcher) # rubocop:disable Naming/MethodName
+      ::Spectus.may(matcher)
+    end
+  end
+end

data/lib/fix/matcher.rb

@@ -3,239 +3,98 @@
 require "matchi"
 
 module Fix
-  # Collection of expectation matchers.
-  #
-  # @api private
+  # The matchers of a specification, as words: each one builds a matcher of
+  # Matchi, or returns a specification, which is a matcher too, and raises
+  # `ArgumentError` at load for an argument the matcher refuses. Any object
+  # with `match?` and `to_s` is accepted by the levels as well.
   module Matcher
-    # Equivalence matcher
-    #
-    # @example
-    #   matcher = eq("foo")
-    #   matcher.match? { "foo" } # => true
-    #   matcher.match? { "bar" } # => false
-    #
-    # @param expected [#eql?] An expected equivalent object.
-    #
-    # @return [#match?] An equivalence matcher.
-    #
-    # @api public
+    # @param expected [Object] the expected value
+    # @return [Matchi::Eq] `eql?` to the expected value, of its class
     def eq(expected)
       ::Matchi::Eq.new(expected)
     end
 
-    alias eql eq
-
-    # Identity matcher
-    #
-    # @example
-    #   object = "foo"
-    #   matcher = be(object)
-    #   matcher.match? { object } # => true
-    #   matcher.match? { "foo" } # => false
-    #
-    # @param expected [#equal?] The expected identical object.
-    #
-    # @return [#match?] An identity matcher.
-    #
-    # @api public
+    # @param expected [Object] the expected object
+    # @return [Matchi::Be] the very same object
     def be(expected)
       ::Matchi::Be.new(expected)
     end
 
-    alias equal be
-
-    # Comparisons matcher
-    #
-    # @example
-    #   matcher = be_within(1).of(41)
-    #   matcher.match? { 42 } # => true
-    #   matcher.match? { 43 } # => false
-    #
-    # @param delta [Numeric] A numeric value.
-    #
-    # @return [#match?] A comparison matcher.
-    #
-    # @api public
+    # @param delta [Numeric] the tolerance
+    # @return [Matchi::BeWithin] to complete with `of(expected)`
     def be_within(delta)
       ::Matchi::BeWithin.new(delta)
     end
 
-    # Regular expressions matcher
-    #
-    # @example
-    #   matcher = match(/^foo$/)
-    #   matcher.match? { "foo" } # => true
-    #   matcher.match? { "bar" } # => false
-    #
-    # @param expected [#match] A regular expression.
-    #
-    # @return [#match?] A regular expression matcher.
-    #
-    # @api public
+    # @param expected [Regexp] the pattern
+    # @return [Matchi::Match] a String or a Symbol matching the pattern
     def match(expected)
       ::Matchi::Match.new(expected)
     end
 
-    # Expecting errors matcher
-    #
-    # @example
-    #   matcher = raise_exception(NameError)
-    #   matcher.match? { Boom } # => true
-    #   matcher.match? { true } # => false
-    #
-    # @param expected [Exception, #to_s] The expected exception name.
-    #
-    # @return [#match?] An error matcher.
-    #
-    # @api public
-    def raise_exception(expected)
-      ::Matchi::RaiseException.new(expected)
+    # @param expected [Class, String, Symbol] the exception class, or its name
+    # @param message [String, Regexp, nil] the expected message
+    # @return [Matchi::RaiseException] raising that exception
+    def raise_exception(expected, message = nil)
+      ::Matchi::RaiseException.new(expected, message)
     end
 
-    # True matcher
-    #
-    # @example
-    #   matcher = be_true
-    #   matcher.match? { true } # => true
-    #   matcher.match? { false } # => false
-    #   matcher.match? { nil } # => false
-    #   matcher.match? { 4 } # => false
-    #
-    # @return [#match?] A `true` matcher.
-    #
-    # @api public
+    # @return [Matchi::Be] `true` itself
     def be_true
-      be(true)
+      ::Matchi::Be.new(true)
     end
 
-    # False matcher
-    #
-    # @example
-    #   matcher = be_false
-    #   matcher.match? { false } # => true
-    #   matcher.match? { true } # => false
-    #   matcher.match? { nil } # => false
-    #   matcher.match? { 4 } # => false
-    #
-    # @return [#match?] A `false` matcher.
-    #
-    # @api public
+    # @return [Matchi::Be] `false` itself
     def be_false
-      be(false)
+      ::Matchi::Be.new(false)
     end
 
-    # Nil matcher
-    #
-    # @example
-    #   matcher = be_nil
-    #   matcher.match? { nil } # => true
-    #   matcher.match? { false } # => false
-    #   matcher.match? { true } # => false
-    #   matcher.match? { 4 } # => false
-    #
-    # @return [#match?] A `nil` matcher.
-    #
-    # @api public
+    # @return [Matchi::Be] `nil` itself
     def be_nil
-      be(nil)
+      ::Matchi::Be.new(nil)
     end
 
-    # Type/class matcher
-    #
-    # @example
-    #   matcher = be_an_instance_of(String)
-    #   matcher.match? { "foo" } # => true
-    #   matcher.match? { 4 } # => false
-    #
-    # @param expected [Class, #to_s] The expected class name.
-    #
-    # @return [#match?] A type/class matcher.
-    #
-    # @api public
+    # @param expected [Class, String, Symbol] the class, or its name
+    # @return [Matchi::BeAnInstanceOf] an instance of that very class
     def be_an_instance_of(expected)
       ::Matchi::BeAnInstanceOf.new(expected)
     end
 
-    # Change matcher
-    #
-    # @example
-    #   object = []
-    #   matcher = change(object, :length).by(1)
-    #   matcher.match? { object << 1 } # => true
-    #
-    #   object = []
-    #   matcher = change(object, :length).by_at_least(1)
-    #   matcher.match? { object << 1 } # => true
-    #
-    #   object = []
-    #   matcher = change(object, :length).by_at_most(1)
-    #   matcher.match? { object << 1 } # => true
-    #
-    #   object = "foo"
-    #   matcher = change(object, :to_s).from("foo").to("FOO")
-    #   matcher.match? { object.upcase! } # => true
-    #
-    #   object = "foo"
-    #   matcher = change(object, :to_s).to("FOO")
-    #   matcher.match? { object.upcase! } # => true
-    #
-    # @param object [#object_id]  An object.
-    # @param method [Symbol]      The name of a method.
-    #
-    # @return [#match?] A change matcher.
+    # @param expected [Module, String, Symbol] the module, or its name
+    # @return [Matchi::BeAKindOf] an instance of that module or of a descendant
+    def be_a_kind_of(expected)
+      ::Matchi::BeAKindOf.new(expected)
+    end
+
+    # The object must exist when the specification is loaded: a let, which
+    # lives with the subject, cannot be observed.
     #
-    # @api public
+    # @param object [Object] the object to observe
+    # @param method [Symbol, String] the method whose value may change,
+    #   followed by its arguments and its block
+    # @return [Matchi::Change] a change, or one to refine with `by`,
+    #   `by_at_least`, `by_at_most`, `from … to` or `to`
     def change(object, method, ...)
       ::Matchi::Change.new(object, method, ...)
     end
 
-    # Satisfy matcher
-    #
-    # @example
-    #   matcher = satisfy { |value| value == 42 }
-    #   matcher.match? { 42 } # => true
-    #
-    # @yield [value] A block that defines the satisfaction criteria
-    # @yieldparam value The value to test
-    # @yieldreturn [Boolean] true if the value satisfies the criteria
-    #
-    # @return [#match?] A satisfy matcher.
-    #
-    # @api public
+    # @yieldparam value [Object] the actual value
+    # @yieldreturn [Boolean] whether it satisfies the block
+    # @return [Matchi::Satisfy]
     def satisfy(&)
       ::Matchi::Satisfy.new(&)
     end
 
-    private
-
-    # Predicate matcher, or default method missing behavior.
-    #
-    # @example Empty predicate matcher
-    #   matcher = be_empty
-    #   matcher.match? { [] } # => true
-    #   matcher.match? { [4] } # => false
-    def method_missing(name, ...)
-      return super unless predicate_matcher_name?(name)
-
-      ::Matchi::Predicate.new(name, ...)
-    end
-
-    # :nocov:
-
-    # Hook method to return whether the obj can respond to id method or not.
-    def respond_to_missing?(name, include_private = false)
-      predicate_matcher_name?(name) || super
-    end
+    # @param name [Symbol, nil] the name of a registered specification
+    # @yield the document of an anonymous specification, instead of a name
+    # @return [Fix::Spec] the specification, tested against the actual value
+    #   as a matcher
+    # @raise [KeyError] when no specification has that name
+    # @raise [ArgumentError] with both a name and a block, or neither
+    def fix(name = nil, &block)
+      raise ::ArgumentError, "a name or a block must be given, not both" if name.nil? == block.nil?
 
-    # :nocov:
-
-    # Predicate matcher name detector.
-    #
-    # @param name [Array, Symbol] The name of a potential predicate matcher.
-    #
-    # @return [Boolean] Indicates if it is a predicate matcher name or not.
-    def predicate_matcher_name?(name)
-      name.start_with?("be_", "have_") && !name.end_with?("!", "?")
+      name.nil? ? ::Fix.spec(&block) : ::Fix[name]
     end
   end
 end

data/lib/fix/node.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Fix
+  # A context of a specification, with everything needed to run its
+  # expectations: the lets in force, the chain of methods to send to the
+  # subject, and the expectations written in it.
+  #
+  # @!attribute [r] lets
+  #   @return [Hash{Symbol => Proc}] the lets, frozen
+  # @!attribute [r] challenges
+  #   @return [Array<Defi::Challenge>] the chain of the `on` above, frozen
+  # @!attribute [r] chain
+  #   @return [String] its text, as `.name(args)` each, empty at the root
+  # @!attribute [r] expectations
+  #   @return [Array<Fix::Expectation>] in the order written
+  #
+  # @api private
+  Node = ::Data.define(:lets, :challenges, :chain, :expectations)
+
+  # An expectation: a requirement at a line of the specification.
+  #
+  # @!attribute [r] location
+  #   @return [String] `file:line`
+  # @!attribute [r] requirement
+  #   @return [Spectus::Requirement]
+  #
+  # @api private
+  Expectation = ::Data.define(:location, :requirement)
+
+  private_constant :Node
+  private_constant :Expectation
+end