brutal 1.6.0.beta3 → 2.0.0

data/lib/brutal/manifest.rb

@@ -1,107 +1,148 @@
 # frozen_string_literal: true
 
-require_relative File.join("manifest", "file")
-
-class Brutal
-  # Brutal YAML manifest file parser.
+require "psych"
+
+module Brutal
+  # The sections of a `NAME_brutal.yaml` file, as the text written in it.
+  #
+  # The YAML file is read as a tree of nodes and never loaded into Ruby
+  # objects: `1,2`, `yes` and `~` stay the text `1,2`, `yes` and `~`. Only
+  # the line breaks that end a value are dropped. A value of several lines
+  # must be a literal block (`|`), which YAML does not fold. Anchors, aliases
+  # and tags are refused, as are unknown, duplicate, missing or empty
+  # sections.
+  #
+  # @!attribute [r] path
+  #   @return [String] the path of the manifest
+  # @!attribute [r] header
+  #   @return [String, nil] code run once, before the first example
+  # @!attribute [r] before
+  #   @return [String, nil] code run before each example
+  # @!attribute [r] subject
+  #   @return [String] the code of each example, with a `%{name}` for each context
+  # @!attribute [r] contexts
+  #   @return [Hash{String => Array<String>}] the code fragments of each context, in the order of the file
+  # @!attribute [r] actuals
+  #   @return [Array<String>] the expressions observed on the subject, with `%{subject}` for its value
+  # @!attribute [r] after
+  #   @return [String, nil] code run after each example
+  # @!attribute [r] footer
+  #   @return [String, nil] code run once, after the last example
+  Manifest = ::Data.define(:path, :header, :before, :subject, :contexts, :actuals, :after, :footer)
+
+  # Reading a manifest.
   class Manifest
-    # The _actuals_ top-level section key.
-    ACTUALS_KEY = "actuals"
-
-    # The _contexts_ top-level section key.
-    CONTEXTS_KEY = "contexts"
+    # The end of a manifest's file name.
+    SUFFIX = "_brutal.yaml"
 
-    # The _header_ top-level section key.
-    HEADER_KEY = "header"
+    NAME = /\A[A-Za-z0-9_][A-Za-z0-9_.-]*_brutal\.yaml\z/
+    BOM = "\xEF\xBB\xBF".b
+    CONTEXT = /\A[A-Za-z_][A-Za-z0-9_]*\z/
+    SECTIONS = %w[header before subject contexts actuals after footer].freeze
+    REQUIRED = %w[subject contexts actuals].freeze
 
-    # The _before_ top-level section key.
-    BEFORE_KEY = "before"
+    private_constant :NAME, :BOM, :CONTEXT, :SECTIONS, :REQUIRED
 
-    # The _subject_ top-level section key.
-    SUBJECT_KEY = "subject"
-
-    # The _after_ top-level section key.
-    AFTER_KEY = "after"
+    # Reads the manifest at `path`.
+    #
+    # @param path [String]
+    # @return [Brutal::Manifest]
+    # @raise [Brutal::Error] when the manifest is not valid
+    # @raise [SystemCallError] when the file cannot be read
+    def self.read(path)
+      unless NAME.match?(::File.basename(path).b)
+        raise Error, "the file name must be NAME#{SUFFIX}, NAME made of ASCII letters, digits, " \
+                     "\".\", \"_\" and \"-\", not starting with \".\" or \"-\""
+      end
+
+      sections = mapping(root(path), "the manifest")
+      check(sections)
+      new(path:, contexts: contexts(sections.fetch("contexts")),
+          actuals: sequence(sections.fetch("actuals"), "actuals"),
+          **(SECTIONS - %w[contexts actuals]).to_h { |name| [name.to_sym, optional(sections, name)] })
+    end
 
-    # The _footer_ top-level section key.
-    FOOTER_KEY = "footer"
+    # The root node of the only document of the file.
+    def self.root(path)
+      text = ::File.binread(path).delete_prefix(BOM).force_encoding(::Encoding::UTF_8)
+      raise Error, "the file is not valid UTF-8" unless text.valid_encoding?
 
-    # Default _actuals_ collection.
-    DEFAULT_ACTUALS = [].freeze
+      documents = ::Psych.parse_stream(text, filename: path).children
+      raise Error, "the file must hold one YAML document" unless documents.size == 1
 
-    # Default _contexts_ collection.
-    DEFAULT_CONTEXTS = {}.freeze
+      documents.first.root
+    rescue ::Psych::SyntaxError => e
+      raise Error, "invalid YAML at line #{e.line}, column #{e.column}: #{e.problem}"
+    end
 
-    # Default _header_ code to evaluate.
-    DEFAULT_HEADER = ""
+    # Refuses unknown and missing sections.
+    def self.check(sections)
+      unknown = sections.keys - SECTIONS
+      raise Error, "unknown section #{unknown.first.dump}" unless unknown.empty?
 
-    # Default _before_ code to evaluate.
-    DEFAULT_BEFORE = ""
+      missing = REQUIRED - sections.keys
+      raise Error, "the section #{missing.first} is missing" unless missing.empty?
+    end
 
-    # Default _after_ code to evaluate.
-    DEFAULT_AFTER = ""
+    # The fragments of each context, by name.
+    def self.contexts(node)
+      contexts = mapping(node, "contexts").to_h do |name, list|
+        unless CONTEXT.match?(name)
+          raise Error, "the context #{name.dump} must be named with letters, digits and _, not starting with a digit"
+        end
 
-    # Default _footer_ code to evaluate.
-    DEFAULT_FOOTER = ""
+        [name, sequence(list, "contexts.#{name}")]
+      end
+      raise Error, "contexts must not be empty" if contexts.empty?
 
-    # Parse a file at `pathname`.  Returns the YAML manifest instance.
-    def self.parse_file(pathname)
-      load(File.new(pathname).parse)
+      contexts.freeze
     end
 
-    # Load the configuration parameters.
-    #
-    # @param params [Hash] Receive the 7 top-level section parameters.
-    def self.load(params)
-      new(
-        actuals:  params.fetch(ACTUALS_KEY, DEFAULT_ACTUALS),
-        contexts: params.fetch(CONTEXTS_KEY, DEFAULT_CONTEXTS),
-        header:   params.fetch(HEADER_KEY, DEFAULT_HEADER),
-        before:   params.fetch(BEFORE_KEY, DEFAULT_BEFORE),
-        subject:  params.fetch(SUBJECT_KEY),
-        after:    params.fetch(AFTER_KEY, DEFAULT_AFTER),
-        footer:   params.fetch(FOOTER_KEY, DEFAULT_FOOTER)
-      )
+    # The text of an optional section, or nil.
+    def self.optional(sections, name)
+      scalar(sections[name], name) if sections.key?(name)
     end
 
-    # Specifies templates to challenge evaluated subjects & get results.
-    attr_reader :actuals
-
-    # Specifies a list of variables to populate the subject's template.
-    attr_reader :contexts
+    # A mapping, as a hash of its keys' text to its value nodes.
+    def self.mapping(node, where)
+      plain(node, ::Psych::Nodes::Mapping, where, "a mapping")
+      node.children.each_slice(2).with_object({}) do |(key, value), hash|
+        name = scalar(key, "a key of #{where}")
+        raise Error, "#{where} has the key #{name.dump} twice" if hash.key?(name)
 
-    # Specifies a block of lines to be executed once before all examples.
-    attr_reader :header
+        hash[name] = value
+      end
+    end
 
-    # Specifies a block of lines to be executed before each example.
-    attr_reader :before
+    # A non-empty sequence, as the text of its items.
+    def self.sequence(node, where)
+      plain(node, ::Psych::Nodes::Sequence, where, "a list")
+      raise Error, "#{where} must not be empty" if node.children.empty?
 
-    # Specifies the template of the code to be declined across contexts.
-    attr_reader :subject
+      node.children.each_with_index.map { |item, index| scalar(item, "#{where}[#{index}]") }.freeze
+    end
 
-    # Specifies a block of lines to be executed after each example.
-    attr_reader :after
+    # The text of a scalar, without the line breaks that end it. Only a
+    # literal block may span several lines: YAML folds the others.
+    def self.scalar(node, where)
+      plain(node, ::Psych::Nodes::Scalar, where, "text")
+      if node.style != ::Psych::Nodes::Scalar::LITERAL && node.end_line > node.start_line
+        raise Error, "#{where} spans several lines: write it as a literal block (|)"
+      end
 
-    # Specifies a block of lines to be executed once after all examples.
-    attr_reader :footer
+      text = node.value.sub(/\n+\z/, "")
+      raise Error, "#{where} must not be empty" if text.strip.empty?
 
-    # Initialize a new configuration.
-    def initialize(actuals:, contexts:, header:, before:, subject:, after:, footer:)
-      raise ::TypeError, actuals.inspect  unless actuals.is_a?(::Array)
-      raise ::TypeError, contexts.inspect unless contexts.is_a?(::Hash)
-      raise ::TypeError, header.inspect   unless header.is_a?(::String)
-      raise ::TypeError, before.inspect   unless before.is_a?(::String)
-      raise ::TypeError, subject.inspect  unless subject.is_a?(::String)
-      raise ::TypeError, after.inspect    unless after.is_a?(::String)
-      raise ::TypeError, footer.inspect   unless footer.is_a?(::String)
+      text.freeze
+    end
 
-      @actuals  = actuals
-      @contexts = contexts
-      @header   = header
-      @before   = before
-      @subject  = subject
-      @after    = after
-      @footer   = footer
+    # Checks the type of a node, and that it has no alias, anchor or tag.
+    def self.plain(node, type, where, what)
+      raise Error, "#{where} must not be an alias" if node.instance_of?(::Psych::Nodes::Alias)
+      raise Error, "#{where} must be #{what}" unless node.instance_of?(type)
+      raise Error, "#{where} must not have an anchor or a tag" if node.anchor || node.tag
     end
+
+    private_class_method :root, :check, :contexts, :optional, :mapping, :sequence, :scalar, :plain
   end
 end

data/lib/brutal/output.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Brutal
+  # Where a test file goes, and how it is written: next to its manifest,
+  # whole or not at all, and only over a file that brutal wrote.
+  module Output
+    CREATE = ::File::WRONLY | ::File::CREAT | ::File::EXCL
+    private_constant :CREATE
+
+    # @param manifest_path [String] the path of a `NAME_brutal.yaml` file
+    # @return [String] the path of `test_NAME.rb`, in the same directory, spelled like the manifest's path
+    def self.target(manifest_path)
+      name = ::File.basename(manifest_path)
+      "#{manifest_path.delete_suffix(name)}test_#{name.delete_suffix(Manifest::SUFFIX)}.rb"
+    end
+
+    # @param path [String]
+    # @param source [String]
+    # @return [Boolean] whether the file at `path` is a regular file holding exactly `source`
+    def self.current?(path, source)
+      ::File.file?(path) && !::File.symlink?(path) && ::File.binread(path) == source.b
+    end
+
+    # Refuses to replace anything but a file that brutal wrote.
+    #
+    # @param path [String]
+    # @return [void]
+    # @raise [Brutal::Error] when `path` is a symbolic link, is not a regular file, or was not written by brutal
+    def self.check(path)
+      raise Error, "#{path} is a symbolic link" if ::File.symlink?(path)
+      return unless ::File.exist?(path)
+      raise Error, "#{path} is not a regular file" unless ::File.file?(path)
+
+      first = ::File.open(path, "rb") { |file| file.read(Program::MARK.bytesize) }
+      return if first == Program::MARK.b
+
+      raise Error, "#{path} was not written by brutal 2 (delete it once if brutal 1 wrote it)"
+    end
+
+    # Writes the source to a temporary file in the same directory, with the
+    # permissions of the file it replaces (never its setuid, setgid or sticky
+    # bits), hands it to the block, then renames it
+    # over `path`: a reader sees the old file or the new one, never a part of
+    # either. An unchanged file is left untouched, and handed to the block.
+    #
+    # @param path [String]
+    # @param source [String]
+    # @yieldparam file [String] the path of the temporary file, or of the
+    #   unchanged file; the block refuses it by raising
+    # @return [void]
+    # @raise [Brutal::Error] when `path` cannot be replaced (see {check})
+    # @raise [SystemCallError] when the file cannot be written
+    def self.write(path, source, &)
+      check(path)
+      if current?(path, source)
+        yield path if block_given?
+      else
+        replace(path, source, &)
+      end
+    end
+
+    # Writes the source to a temporary file, then installs it.
+    def self.replace(path, source, &)
+      temporary = ::File.join(::File.dirname(path), ".#{::File.basename(path)}.#{::Process.pid}.tmp")
+      create(temporary, source, (::File.stat(path).mode & 0o777 if ::File.exist?(path)))
+      install(temporary, path, &)
+    end
+
+    # Creates the temporary file, which must not exist yet: a file left by
+    # another process is an error, and is not removed.
+    def self.create(temporary, source, mode)
+      ::File.open(temporary, CREATE, 0o666, binmode: true) do |file|
+        file.chmod(mode) if mode
+        file.write(source)
+        file.fsync
+      rescue ::Exception # rubocop:disable Lint/RescueException
+        ::File.unlink(temporary)
+        raise
+      end
+    end
+
+    # Hands the temporary file to the block, then renames it over the path;
+    # removes it if either fails.
+    def self.install(temporary, path)
+      yield temporary if block_given?
+      ::File.rename(temporary, path)
+    rescue ::Exception # rubocop:disable Lint/RescueException
+      ::File.unlink(temporary)
+      raise
+    end
+
+    private_class_method :replace, :create, :install
+  end
+end

data/lib/brutal/program.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module Brutal
+  # The test a manifest describes, as Ruby source code, in two forms with the
+  # same lines: one that records the observed values, and the test file,
+  # which checks them.
+  #
+  # `%{name}` in the subject is replaced by each fragment of the context
+  # `name`, for every combination of the contexts, and `%{subject}` in an
+  # actual by `actual`, the local variable that holds the subject's value.
+  # Nothing else is interpreted: a `%` is a `%`.
+  class Program
+    # The first line of every test file, without the name of the manifest.
+    MARK = "# Generated by brutal from "
+
+    PLACEHOLDER = /%\{([A-Za-z_][A-Za-z0-9_]*)\}/
+    SEPARATOR = "# #{"-" * 78}".freeze
+    SECTIONS = %i[header before after footer].freeze
+
+    private_constant :PLACEHOLDER, :SEPARATOR, :SECTIONS
+
+    # @return [Array<Hash{String => String}>] the fragment of each context, for each example
+    attr_reader :cases
+
+    # @param manifest [Brutal::Manifest]
+    # @raise [Brutal::Error] when a placeholder or a context is unknown or
+    #   unused, or a section, a subject or an actual is not complete code on
+    #   its own
+    def initialize(manifest)
+      @manifest = manifest
+      check
+      names = manifest.contexts.keys
+      first, *rest = manifest.contexts.values
+      @cases = first.product(*rest).map { |fragments| names.zip(fragments).to_h.freeze }.freeze
+      parse
+      freeze
+    end
+
+    # @return [Integer] the number of observed values: one per example and actual
+    def size
+      cases.size * @manifest.actuals.size
+    end
+
+    # The program that records the observed values: `$__brutal__` receives
+    # `enter` with the index of each example (`cases.size` for the footer),
+    # and `observe` with each observed value.
+    #
+    # @return [String]
+    def record
+      source(separator: ->(index) { "$__brutal__.enter(#{index})" }, assertion: ->(_index) { "$__brutal__.observe((" })
+    end
+
+    # The test file: each observed value must be `eql?` to its literal.
+    #
+    # @param literals [Array<String>] the literal of each observed value, in order
+    # @return [String]
+    def test(literals)
+      assertion = ->(index) { "::Kernel.raise #{label(index).dump} unless (#{literals.fetch(index)}).eql?((" }
+      source(separator: ->(_index) { SEPARATOR }, assertion:)
+    end
+
+    # Where an observed value comes from, for messages.
+    #
+    # @param index [Integer] the index of an observed value
+    # @return [String] the fragments of its example, and its actual
+    def label(index)
+      example, actual = index.divmod(@manifest.actuals.size)
+      "#{phase(example)}: #{observation(@manifest.actuals.fetch(actual))}"
+    end
+
+    # Names a part of the program, for messages.
+    #
+    # @param index [Integer, nil] the index of an example, nil for the header, `cases.size` for the footer
+    # @return [String]
+    def phase(index)
+      return "the header" if index.nil?
+      return "the footer" if index == cases.size
+
+      cases.fetch(index).map { |name, fragment| "#{name} = #{fragment}" }.join(", ")
+    end
+
+    private
+
+    # Refuses a placeholder without context, a context without placeholder,
+    # and a placeholder where brutal does not replace it.
+    def check
+      names = @manifest.contexts.keys
+      used = placeholders(@manifest.subject)
+      refuse(used - names, "the subject uses %{NAME}, which is not a context")
+      refuse(names - used, "the context NAME is not used in the subject")
+      refuse(@manifest.actuals.flat_map { |actual| placeholders(actual) } - ["subject"],
+             "an actual can only use %{subject}, not %{NAME}")
+      SECTIONS.each do |section|
+        refuse(placeholders(@manifest.public_send(section).to_s), "the #{section} uses %{NAME}, which is not replaced")
+      end
+    end
+
+    # Refuses code that is not complete on its own: each part must parse
+    # alone, so that no part can change how the others parse, or hide a
+    # check.
+    def parse
+      SECTIONS.each { |section| alone(@manifest.public_send(section), "the #{section}") }
+      cases.each_with_index { |fragments, index| alone(subject(fragments), "the subject, for #{phase(index)},") }
+      @manifest.actuals.each { |actual| alone(observation(actual), "the actual #{actual.dump}") }
+    end
+
+    # Compiles a part of the code alone, warnings off: nothing runs. The part
+    # starts on the third line, as the header does in the test file, so that a
+    # magic comment of the first line (`# encoding:`) is ignored as it is
+    # there; the line numbers of the part are kept.
+    def alone(code, part)
+      return if code.nil?
+      raise Error, "#{part} holds an end of file (__END__, NUL, ^D or ^Z)" if code.match?(/^__END__\r?$|[\0\x04\x1a]/)
+
+      verbose = $VERBOSE
+      $VERBOSE = nil
+      ::RubyVM::InstructionSequence.compile("\n\n#{code}", "<compiled>", "<compiled>", -1)
+    rescue ::SyntaxError => e
+      raise Error, "#{part} is not complete code on its own: #{e.message.sub("<compiled>:", "line ")}"
+    ensure
+      $VERBOSE = verbose unless verbose.nil?
+    end
+
+    # Raises the message, with the first name for NAME, if there is one.
+    def refuse(names, message)
+      raise Error, message.sub("NAME", names.first) unless names.empty?
+    end
+
+    # The names of the placeholders of a template.
+    def placeholders(template)
+      template.scan(PLACEHOLDER).flatten.uniq
+    end
+
+    # The program; `separator` and `assertion` give the lines that differ
+    # between its two forms, from the index of an example and of an observed
+    # value.
+    def source(separator:, assertion:)
+      [
+        "#{MARK}#{::File.basename(@manifest.path)}: edit the manifest, then run brutal again.", "",
+        *([@manifest.header, ""] if @manifest.header),
+        *cases.each_with_index.flat_map { |fragments, index| example(fragments, index, separator, assertion) },
+        *([separator.call(cases.size), "", @manifest.footer, ""] if @manifest.footer)
+      ].join("\n")
+    end
+
+    # The lines of one example.
+    def example(fragments, index, separator, assertion)
+      [
+        separator.call(index), "",
+        *([@manifest.before, ""] if @manifest.before),
+        "actual = begin", nest(subject(fragments)), "end", "",
+        *assertions(index, assertion),
+        *(["", @manifest.after] if @manifest.after),
+        ""
+      ]
+    end
+
+    # The lines of the assertions of one example.
+    def assertions(index, assertion)
+      @manifest.actuals.each_with_index.flat_map do |actual, position|
+        [assertion.call((index * @manifest.actuals.size) + position), nest(observation(actual)), "))"]
+      end
+    end
+
+    # The subject, with the fragment of each context for its placeholder.
+    def subject(fragments)
+      @manifest.subject.gsub(PLACEHOLDER) { fragments.fetch(::Regexp.last_match(1)) }
+    end
+
+    # An actual, with `actual` for `%{subject}`.
+    def observation(actual)
+      actual.gsub(PLACEHOLDER, "actual")
+    end
+
+    # Indents a code fragment of one line. A fragment of several lines is
+    # left as written: indenting it would change a multi-line string or a
+    # heredoc.
+    def nest(code)
+      code.include?("\n") ? code : "  #{code}"
+    end
+  end
+end