brutal 1.6.0.beta4 → 2.0.0

data/lib/brutal/runner.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module Brutal
+  # Runs the code of a manifest, in two ways.
+  #
+  # {record} runs the recording program in a child process forked through
+  # Aw, as `ruby` would run the test file: compiled at the top level, with
+  # `self` as `main`, the magic comments of the header, `__FILE__`, `$0` and
+  # `__dir__` those of the test file, no arguments and nothing on the
+  # standard input. What the code does to the process stays in the child,
+  # and only data come back.
+  #
+  # {run} runs a test file with the Ruby that runs brutal, in a new process,
+  # as `ruby test_NAME.rb` would.
+  #
+  # @api private
+  module Runner
+    CLASS = ::Kernel.instance_method(:class)
+    VARIABLE = ::Kernel.instance_method(:instance_variable_get)
+    SCALARS = [::NilClass, ::TrueClass, ::FalseClass, ::Integer, ::Float, ::Symbol].freeze
+    DEPTH = 100
+    CREATE = ::File::RDWR | ::File::CREAT | ::File::EXCL
+    LIMIT = 65_536
+
+    private_constant :CLASS, :VARIABLE, :SCALARS, :DEPTH, :CREATE, :LIMIT
+
+    # Raised in the child for a value that cannot leave it as data.
+    class Unsupported < ::StandardError
+    end
+
+    # What the recording program calls, as `$__brutal__`. Its state is read
+    # without calling its methods, which the code may redefine.
+    class Recorder
+      def initialize
+        @phase = nil
+        @snapshots = []
+      end
+
+      # @param phase [Integer] the index of the example about to run, or of the footer
+      # @return [nil]
+      def enter(phase)
+        @phase = phase
+        nil
+      end
+
+      # @param value [Object] an observed value
+      # @return [nil]
+      def observe(value)
+        @snapshots << Runner.snapshot(value)
+        nil
+      end
+    end
+
+    # Runs the recording program in a child process.
+    #
+    # @param source [String]
+    # @param path [String] the absolute path of the test file
+    # @return [Array((Integer, nil), Array<Array(Symbol, Object)>, (String, nil))] the last phase (nil for the
+    #   header), the snapshots, and the error, if any
+    # @raise [Brutal::Error] when the source does not compile, or the child ends without a result
+    def self.record(source, path)
+      program = compile(source, path)
+      fork do
+        recorder = Recorder.new
+        $__brutal__ = recorder # rubocop:disable Style/GlobalVars
+        ::ARGV.clear
+        $PROGRAM_NAME = path
+        $stdin.reopen(::File::NULL)
+        error = evaluate(program)
+        [VARIABLE.bind_call(recorder, :@phase), VARIABLE.bind_call(recorder, :@snapshots), error]
+      end
+    end
+
+    # Runs a test file with `RbConfig.ruby`, from the current directory, with nothing
+    # on its standard input and its standard output discarded. Its standard
+    # error goes to a file created next to it and removed at once: a process
+    # the test leaves running cannot keep brutal waiting.
+    #
+    # @param path [String]
+    # @return [String, nil] why it failed, from its standard error, or nil when it passed
+    def self.run(path)
+      log = ::File.join(::File.dirname(path), ".#{::File.basename(path)}.#{::Process.pid}.err")
+      pid = nil
+      ::File.open(log, CREATE, 0o600, binmode: true) do |errors|
+        ::File.unlink(log)
+        pid = ::Process.spawn(::RbConfig.ruby, path, in: ::File::NULL, out: ::File::NULL, err: errors)
+        _, status = ::Process.wait2(pid)
+        pid = nil
+        errors.rewind
+        failure(errors.read(LIMIT).to_s, status) unless status.success?
+      end
+    ensure
+      reap(pid)
+    end
+
+    # The first line of the standard error that is not a warning, and how
+    # the process ended.
+    def self.failure(errors, status)
+      line = ::String.new(errors, encoding: ::Encoding::UTF_8).scrub.lines.find { |text| !text.include?(": warning: ") }
+      "#{line&.chomp || "no message"} (#{status(status)})"
+    end
+
+    # Converts an observed value to data made of core classes only.
+    #
+    # @param value [Object]
+    # @return [Array(Symbol, Object)] `[:value, data]` or `[:unsupported, reason]`
+    def self.snapshot(value)
+      [:value, plain(value, 0)]
+    rescue Unsupported => e
+      [:unsupported, e.message]
+    end
+
+    # Runs a block in a child process.
+    def self.fork(&)
+      raise Error, "brutal needs fork(2), which this Ruby does not have" unless ::Aw.supported?
+
+      ::Aw.fork!(&)
+    rescue ::Aw::ChildError => e
+      raise Error, "the process running the code ended without a result (#{status(e.status)})"
+    end
+
+    # Compiles the source, in the parent: nothing runs.
+    def self.compile(source, path)
+      ::RubyVM::InstructionSequence.compile(source, path, path, 1)
+    rescue ::SyntaxError => e
+      raise Error, "the code does not compile: #{e.message}"
+    end
+
+    # Runs the program at the top level; returns what it raised, as text.
+    def self.evaluate(program)
+      program.eval
+      nil
+    rescue ::Exception => e # rubocop:disable Lint/RescueException
+      describe(e)
+    end
+
+    # The class and the message of an exception, built defensively: its
+    # methods may raise.
+    def self.describe(error)
+      name = CLASS.bind_call(error).name || "an anonymous exception"
+      message = error.message.to_s.encode(::Encoding::UTF_8, invalid: :replace, undef: :replace)
+      "#{name}: #{message}"
+    rescue ::Exception # rubocop:disable Lint/RescueException
+      "#{name || "an exception"}, whose message cannot be read"
+    end
+
+    # A copy of the value made of the classes Literal writes, by their exact
+    # class: an instance of a subclass, or of a class the parent does not
+    # know, cannot come back.
+    def self.plain(value, depth)
+      raise Unsupported, "is nested more than #{DEPTH} levels deep, or contains itself" if depth > DEPTH
+      raise Unsupported, "is a BasicObject" unless ::Kernel === value # rubocop:disable Style/CaseEquality
+
+      copy(value, CLASS.bind_call(value), depth + 1)
+    end
+
+    # A copy of a value of the given class.
+    def self.copy(value, klass, depth)
+      return value if SCALARS.include?(klass)
+      return ::String.new(value) if klass.equal?(::String)
+      return value.map { |item| plain(item, depth) } if klass.equal?(::Array)
+      return value.to_h { |key, item| [plain(key, depth), plain(item, depth)] } if klass.equal?(::Hash)
+
+      raise Unsupported, "is an instance of #{klass.name || "an anonymous class"}"
+    end
+
+    # How a process ended.
+    def self.status(status)
+      return "killed by SIG#{::Signal.signame(status.termsig)}" if status.signaled?
+
+      "exit status #{status.exitstatus}"
+    end
+
+    # Kills and reaps a process left running by an interruption.
+    def self.reap(pid)
+      return if pid.nil?
+
+      ::Process.kill(:KILL, pid)
+      ::Process.wait(pid)
+    end
+
+    private_class_method :failure, :fork, :compile, :evaluate, :describe, :plain, :copy, :status, :reap
+  end
+end

data/lib/brutal.rb

@@ -1,40 +1,96 @@
 # frozen_string_literal: true
 
-%w[
-  format
-  manifest
-].each { |filename| require_relative(File.join("brutal", filename)) }
+require "aw"
 
-# The Brutal namespace.
-class Brutal
-  attr_reader :engine
+# Writes plain Ruby test files from YAML manifests. A manifest gives a
+# subject, contexts to combine and actuals to observe; brutal runs every
+# combination in a child process, records what the code returns, and writes
+# a test file that checks these values with `eql?`, without any framework.
+#
+# The test file describes what the code does, not what it should do: read
+# it before trusting it.
+#
+# @example
+#   Brutal.generate("test/calc_brutal.yaml").path # => "test/test_calc.rb"
+module Brutal
+  # Raised for a manifest brutal cannot turn into a test file: the message
+  # says why, without the path of the manifest.
+  class Error < ::StandardError
+  end
+
+  # A test file to write.
+  #
+  # @!attribute [r] path
+  #   @return [String] where to write it: `test_NAME.rb`, next to the manifest
+  # @!attribute [r] source
+  #   @return [String] its content
+  Test = ::Data.define(:path, :source)
 
-  def initialize(format)
-    @engine = Format.const_get(format)
+  # Reads a manifest, runs its code in a child process to record the values
+  # it returns, and builds the test file. Nothing is written.
+  #
+  # @param manifest_path [String] the path of a `NAME_brutal.yaml` file
+  # @return [Brutal::Test]
+  # @raise [Brutal::Error] when the manifest is not valid, the code does not
+  #   compile, raises, ends its process or skips a check, a value cannot be
+  #   written as a literal, or this Ruby cannot fork
+  # @raise [SystemCallError] when the manifest cannot be read
+  def self.generate(manifest_path)
+    program = Program.new(Manifest.read(manifest_path))
+    path = Output.target(manifest_path)
+    absolute = ::File.join(::File.realpath(::File.dirname(path)), ::File.basename(path))
+    Test.new(path:, source: program.test(literals(program, Runner.record(program.record, absolute))))
   end
 
-  def call(pathname)
-    manifest = Manifest.parse_file(pathname)
-    scaffold = brutalizer(manifest)
-    pathname = new_pathname(pathname)
-    pathname.write(scaffold)
+  # Writes a test file, once the Ruby that runs brutal has run it, in a new
+  # process, and it passed: the code runs a second time. An unchanged file is
+  # run too.
+  #
+  # @param test [Brutal::Test]
+  # @return [void]
+  # @raise [Brutal::Error] when the test file fails, or cannot replace the file in place
+  # @raise [SystemCallError] when the file cannot be written
+  def self.write(test)
+    Output.write(test.path, test.source) do |temporary|
+      error = Runner.run(temporary)
+      # The name of the temporary file, which is ASCII, gives way to the test
+      # file's: the directory is the same, whatever the encoding of its name.
+      error &&= error.gsub(::File.basename(temporary), ::File.basename(test.path))
+      raise Error, "the test file fails when ruby runs it: #{error}" if error
+    end
   end
 
-  private
+  # The literal of each observed value, once the recording ran to its end.
+  def self.literals(program, recording)
+    phase, snapshots, error = recording
+    raise Error, "#{program.phase(phase)}: #{error}" if error
+    unless snapshots.size == program.size
+      raise Error, "observed values: #{snapshots.size}, expected: #{program.size}; a check was skipped or repeated"
+    end
 
-  def brutalizer(conf)
-    engine.new(conf.header, conf.before, conf.subject, conf.after, conf.footer, *conf.actuals, **conf.contexts)
-  end
+    snapshots.each_with_index.map do |(kind, data), index|
+      literal, reason = literal(kind, data)
+      raise Error, "#{program.label(index)} #{reason}, which brutal cannot write as a literal" if reason
 
-  def new_pathname(pathname)
-    pathname.dirname + "#{new_prefix}#{pathname.basename.sub(Manifest::File::Name::SUFFIX_REGEX, new_suffix)}"
+      literal
+    end
   end
 
-  def new_prefix
-    engine.const_get(:Filename).const_get(:PREFIX)
-  end
+  # `[literal, nil]`, or `[nil, reason]` for a value that has no literal.
+  def self.literal(kind, data)
+    return [nil, data] if kind == :unsupported
 
-  def new_suffix
-    engine.const_get(:Filename).const_get(:SUFFIX)
+    [Literal.dump(data), nil]
+  rescue Error => e
+    [nil, e.message]
   end
+
+  private_class_method :literals, :literal
 end
+
+require_relative "brutal/cli"
+require_relative "brutal/literal"
+require_relative "brutal/manifest"
+require_relative "brutal/output"
+require_relative "brutal/program"
+require_relative "brutal/runner"

metadata

@@ -1,128 +1,32 @@
 --- !ruby/object:Gem::Specification
 name: brutal
 version: !ruby/object:Gem::Version
-  version: 1.6.0.beta4
+  version: 2.0.0
 platform: ruby
 authors:
 - Cyril Kato
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-09-19 00:00:00.000000000 Z
+date: 2026-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: bundler
+  name: aw
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
+        version: '1.0'
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rubocop-gitlab-security
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rubocop-md
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rubocop-performance
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rubocop-rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rubocop-thread_safety
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: yard
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-description: A code-first approach to automate the writing of unit tests.
+        version: '1.0'
+description: 'Writes framework-free Ruby test files from YAML manifests: runs every
+  combination of contexts in a child process, and checks each observed value with
+  eql?.'
 email: contact@cyril.email
 executables:
 - brutal
@@ -133,19 +37,22 @@ files:
 - README.md
 - bin/brutal
 - lib/brutal.rb
-- lib/brutal/command_line_arguments_parser.rb
-- lib/brutal/format.rb
-- lib/brutal/format/ruby.rb
-- lib/brutal/format/ruby/filename.rb
+- lib/brutal/cli.rb
+- lib/brutal/literal.rb
 - lib/brutal/manifest.rb
-- lib/brutal/manifest/file.rb
-- lib/brutal/manifest/file/name.rb
-homepage: https://github.com/fixrb/brutal
+- lib/brutal/output.rb
+- lib/brutal/program.rb
+- lib/brutal/runner.rb
+homepage: https://fixrb.dev/gems/brutal/
 licenses:
 - MIT
 metadata:
+  bug_tracker_uri: https://github.com/fixrb/brutal/issues
+  changelog_uri: https://github.com/fixrb/brutal#changes-in-20
+  documentation_uri: https://rubydoc.info/gems/brutal
   rubygems_mfa_required: 'true'
-post_install_message: 
+  source_code_uri: https://github.com/fixrb/brutal
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -153,15 +60,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
-rubygems_version: 3.1.6
-signing_key: 
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
-summary: A code-first approach to automate the writing of unit tests.
+summary: Plain Ruby tests, written from what the code does
 test_files: []

data/lib/brutal/command_line_arguments_parser.rb

@@ -1,115 +0,0 @@
-# frozen_string_literal: true
-
-require_relative File.join("manifest", "file", "name")
-
-require "pathname"
-
-class Brutal
-  # Accept an arbitrary number of arguments passed from the command-line.
-  class CommandLineArgumentsParser
-    MANIFEST_FILENAME_PATTERN = ::File.join("**", Manifest::File::Name::SUFFIX_PATTERN)
-    CURRENT_DIRECTORY_CONTEXT = "."
-    GEM_NAME                  = "brutal"
-    HELP_OPTION               = "--help"
-    VERSION_OPTION            = "--version"
-    RUBY_FORMAT_OPTION        = "--format=ruby"
-    DEFAULT_FORMAT_OPTION     = RUBY_FORMAT_OPTION
-
-    FORMAT_OPTIONS = {
-      RUBY_FORMAT_OPTION => :Ruby
-    }.freeze
-
-    DEFAULT_FORMAT  = FORMAT_OPTIONS.fetch(DEFAULT_FORMAT_OPTION)
-    DEFAULT_FORMATS = [DEFAULT_FORMAT].freeze
-
-    attr_reader :pathnames
-
-    def initialize(*args)
-      args.each do |arg|
-        help!     if arg == HELP_OPTION
-        version!  if arg == VERSION_OPTION
-      end
-
-      @formats   = []
-      @pathnames = []
-
-      args << CURRENT_DIRECTORY_CONTEXT unless any_path_given?(*args)
-      args.each { |arg| parse!(arg) }
-    end
-
-    def call
-      [formats, pathnames]
-    end
-
-    private
-
-    def formats
-      @formats.empty? ? DEFAULT_FORMATS : @formats
-    end
-
-    def parse!(arg)
-      case arg
-      when RUBY_FORMAT_OPTION
-        @formats << FORMAT_OPTIONS.fetch(RUBY_FORMAT_OPTION)
-      else
-        load!(::Pathname.new(arg))
-      end
-    end
-
-    def help!
-      puts help_message
-      exit
-    end
-
-    def help_message
-      <<~TXT
-        Usage: #{$PROGRAM_NAME} [options] [files or directories]
-
-            --format=FORMAT Choose "ruby" (default).
-            --help          Display this help.
-            --version       Display the version.
-      TXT
-    end
-
-    def load!(pathname)
-      if pathname.directory?
-        pathname.glob(MANIFEST_FILENAME_PATTERN).each { |filename| load!(filename) }
-      elsif pathname.file?
-        load_file!(pathname)
-      else
-        raise ::ArgumentError, "#{pathname} is neither a file nor a directory."
-      end
-    end
-
-    def load_file!(pathname)
-      if pathname.fnmatch?(MANIFEST_FILENAME_PATTERN, ::File::FNM_PATHNAME | ::File::FNM_DOTMATCH)
-        @pathnames << pathname
-      else
-        warn "Skipping #{pathname} because not matched against #{MANIFEST_FILENAME_PATTERN}."
-      end
-    end
-
-    def any_path_given?(*args)
-      path_args(*args).any?
-    end
-
-    def path_args(*args)
-      args - FORMAT_OPTIONS.keys
-    end
-
-    def version!
-      abort "Gem not found on the system.  Unknown version." if not_loaded_spec?
-
-      puts loaded_spec.version
-      exit
-    end
-
-    def loaded_spec
-      ::Gem.loaded_specs[GEM_NAME]
-    end
-
-    def not_loaded_spec?
-      loaded_spec.nil?
-    end
-  end
-end

data/lib/brutal/format/ruby/filename.rb

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-class Brutal
-  module Format
-    class Ruby
-      module Filename
-        # Brutal Ruby format file prefix.
-        PREFIX = "test_"
-
-        # Brutal Ruby format file suffix.
-        SUFFIX = ".rb"
-      end
-    end
-  end
-end