brutal 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a7eb1b01e30dda0f5b204eef32ac2ec59c19384b37500f40587a1a522fce6db
-  data.tar.gz: be19e4c8f4741658ef2aea98891b8bf040a250361fe48fee5219b02cc297b10f
+  metadata.gz: 31ea2d6a9b38faaa03aaed25dfc8b18158a8d243b9aed42e0f4a3a488c8386a3
+  data.tar.gz: f73e4a2798de7a55deb006898919498a9d6344fcd3ec94728a379bf723370ae2
 SHA512:
-  metadata.gz: 565a5d6628dd7f3904f97343da33539eaddf97c6fa020d2c14736ed84a146c3fe3d0aa7eb6fdfc73a94a3238be3bba40d892f07281d231918022b2c96fb95ce6
-  data.tar.gz: 245f56b40a04d626c653e679b3634a5e1f3805a4f356c6f009759cb9e350e675b89e17e699e430fac5ffcb596e83c19190b929b4086b1da42254f2ffdbc7ea60
+  metadata.gz: f5a9b52b8608bdf327bb14ad782cde378901285a3d9de0b28d273184480586f868da0b10bf32ac47980bfbc0b637b6bc058de2c42bdb600b4add7bb1865207e0
+  data.tar.gz: 302e2bf37546bc813caa05eedb38f2ad496123e6ba37b186d449ea2e5782945ef5d652d8cdc05a25c08045a472144ad6efa30f4316c23f5e3ca9ecdbdd8c8818

data/LICENSE.md

@@ -1,6 +1,6 @@
-The MIT License (MIT)
+# The MIT License
 
-Copyright (c) 2020-2021 Cyril Kato
+Copyright (c) 2020-2022 Cyril Kato
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,10 +1,10 @@
 # Brutal 💎🔨
 
-[![RuboCop Status](https://github.com/fixrb/brutal/workflows/RuboCop/badge.svg)][workflow_rubocop]
-[![Build Status](https://api.travis-ci.org/fixrb/brutal.svg?branch=main)][travis]
-[![Gem Version](https://badge.fury.io/rb/brutal.svg)][gem]
-[![Inline docs](https://inch-ci.org/github/fixrb/brutal.svg?branch=main)][inchpages]
-[![Documentation](http://img.shields.io/:yard-docs-38c800.svg)][rubydoc]
+[![Version](https://img.shields.io/github/v/tag/fixrb/brutal?label=Version&logo=github)](https://github.com/fixrb/brutal/tags)
+[![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/fixrb/brutal/main)
+[![Ruby](https://github.com/fixrb/brutal/workflows/Ruby/badge.svg?branch=main)](https://github.com/fixrb/brutal/actions?query=workflow%3Aruby+branch%3Amain)
+[![RuboCop](https://github.com/fixrb/brutal/workflows/RuboCop/badge.svg?branch=main)](https://github.com/fixrb/brutal/actions?query=workflow%3Arubocop+branch%3Amain)
+[![License](https://img.shields.io/github/license/fixrb/brutal?label=License&logo=github)](https://github.com/fixrb/brutal/raw/main/LICENSE.md)
 
 > A _code-first_ approach to automate the writing of unit tests.
 
@@ -12,26 +12,26 @@
 
 [![I Hate Tests](https://github.com/fixrb/brutal/raw/main/img/rubyhack-2019-ruby3-what-s-missing-by-yukihiro-matsumoto.jpg)](https://www.youtube.com/embed/cmOt9HhszCI?start=1732&end=1736 "I don't like tests. It's not DRY.")
 
-> I don't like tests. It's not DRY.<br/>
+> I don't like tests. It's not DRY.
 > -- [Matz](https://github.com/matz)
 
 ## Overview
 
-Let __Brutal__ shape for you in no time the actual behavior of your code through as many combinations of contexts as needed.
+Let __Brutal__ craft for you in no time a (potentially huge) framework-less vanilla Ruby file describing the actual behavior of your code across as many context combinations as necessary.
 
-By delegating to __Brutal__ the repetitive (and redundant) task of writing tests, you'll be able to focus on your core business: the code itself.
+By delegating to __Brutal__ the repetitive (and redundant) task of writing tests, you will be able to focus on your core business: the code itself.
+
+![Brutal-Driven Development](https://github.com/fixrb/brutal/raw/main/img/brutal-driven-development.jpg)
 
 ## Warning
 
-__Brutal__ development process does not prevent from bugs.
+The _Brutal-Driven Development_ process does not prevent bugs from appearing in the code.
+
+A generated test suite acts as a _picture of the code's behavior_. Therefore, if the code is wrong, the picture of the code's behavior will also be wrong.
 
-As a _picture of the behavior of the code_,
-a generated test suite is wrong as long as the code is wrong,
-regardless of whether all true expectations.
+The mere fact that all expectations are true does not mean that the code behaves as it should.
 
-However, this document becomes relevant when it shows that the code behaves as it is supposed to.
-It is therefore important to read it well.
-This is the price for _Brutal-Driven Development_.
+It is therefore the responsibility of the developer to analyze the generated behavioral pictures to ensure that the code reacts as it is supposed to according to the contexts in which it is evaluated.
 
 ## Installation
 
@@ -43,11 +43,15 @@ gem "brutal"
 
 And then execute:
 
-    $ bundle install
+```sh
+bundle install
+```
 
 Or install it yourself as:
 
-    $ gem install brutal
+```sh
+gem install brutal
+```
 
 ## Quick Start
 
@@ -55,63 +59,40 @@ Just type `brutal` in a Ruby project's folder and watch the magic happen.
 
 ## Usage
 
-The `brutal.yml` file is a manifest you can use to define your __Brutal__ meta-spec.
-It has 4 top-level sections:
+__Brutal__ needs a configuration file to know how to write your tests.
+Currently, only the YAML format is supported.
+This file is composed of 4 top-level sections:
 
 * `header` - Specifies the code to execute before generating the test suite.
 * `subject` - Specifies the template of the code to be declined across contexts.
 * `contexts` - Specifies a list of variables to populate the subject's template.
 * `actuals` - Specifies templates to challenge evaluated subjects & get results.
 
-### Getting started
-
-1. Create a `brutal.yml` file in your application's root directory.
-The following example `brutal.yml` defines the shape of a Hello test suite:
+This file is by default called `.brutal.yml`, but it would be possible to name it differently by passing it as an argument to the brutal command such as:
 
-```yaml
----
-subject: |
-  "Hello " + "%{string}"
-
-contexts:
-  string:
-    - Alice
-    - Bob
-
-actuals:
-  - "%{subject}.to_s"
-  - "%{subject}.length"
+```sh
+brutal test_hello_world.yml
 ```
 
-2. Run the `brutal` command from the same directory.
-
-3. Read the generated `test.rb` file in the same directory:
-
-```ruby
-# Brutal test suite
-
-# ------------------------------------------------------------------------------
+This would create a `test_hello_world.rb` file containing the test suite.
 
-actual = begin
-  "Hello " + "Alice"
-end
+To avoid accidentally overwriting a file, the `--no-force` option can be used:
 
-raise if actual.to_s != "Hello Alice"
-raise if actual.length != 11
+```sh
+brutal test_hello_world.yml --no-force
+```
 
-# ------------------------------------------------------------------------------
+> A test_hello_world.rb file already exists!
 
-actual = begin
-  "Hello " + "Bob"
-end
+### Getting started
 
-raise if actual.to_s != "Hello Bob"
-raise if actual.length != 9
-```
+1. Create a `.brutal.yml` file in your application's root directory. For example: <https://github.com/fixrb/brutal/blob/v1.4.0/examples/hello_world_v1/.brutal.yml>
+2. Run the `brutal` command from the same directory.
+3. Read the generated `test.rb` file in the same directory: <https://github.com/fixrb/brutal/blob/v1.4.0/examples/hello_world_v1/test.rb>
 
 ### More examples
 
-https://github.com/fixrb/brutal/raw/main/examples/
+<https://github.com/fixrb/brutal/blob/v1.4.0/examples/>
 
 ## Rake integration example
 
@@ -123,6 +104,10 @@ Rake::TestTask.new do |t|
 end
 ```
 
+## Test suite
+
+__Brutal__'s test set is brutally self-generated here: [./test.rb](https://github.com/fixrb/brutal/blob/main/test.rb)
+
 ## Contact
 
 * Source code: https://github.com/fixrb/brutal
@@ -133,19 +118,11 @@ __Brutal__ follows [Semantic Versioning 2.0](https://semver.org/).
 
 ## License
 
-The [gem](https://rubygems.org/gems/brutal) is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The [gem](https://rubygems.org/gems/brutal) is available as open source under the terms of the [MIT License](https://github.com/fixrb/brutal/raw/main/LICENSE.md).
 
 ***
 
-<p>
-  This project is sponsored by:<br />
-  <a href="https://sashite.com/"><img
-    src="https://github.com/fixrb/brutal/raw/main/img/sashite.png"
-    alt="Sashite" /></a>
-</p>
-
-[workflow_rubocop]: https://github.com/fixrb/brutal/actions?query=workflow%3ARuboCop
-[gem]: https://rubygems.org/gems/brutal
-[travis]: https://travis-ci.org/fixrb/brutal
-[inchpages]: https://inch-ci.org/github/fixrb/brutal
-[rubydoc]: https://rubydoc.info/gems/brutal/frames
+This project is sponsored by [Sashité](https://github.com/sashite/):
+
+![Sashité logo](https://github.com/fixrb/brutal/raw/main/img/sponsor/dark/en/sashite.png#gh-dark-mode-only "Sashité")
+![Sashité logo](https://github.com/fixrb/brutal/raw/main/img/sponsor/light/en/sashite.png#gh-light-mode-only "Sashité")

data/bin/brutal

@@ -3,4 +3,4 @@
 
 require_relative File.join("..", "lib", "brutal")
 
-Brutal.generate!
+Brutal.generate! ARGV.fetch(0, Brutal::File::DEFAULT_CONFIG_FILENAME), force: ARGV.none?("--no-force")

data/lib/brutal/configuration.rb

@@ -5,9 +5,14 @@ module Brutal
   #
   # @since 1.0.0
   class Configuration
+    ACTUALS_KEY   = "actuals"
+    CONTEXTS_KEY  = "contexts"
+    HEADER_KEY    = "header"
+    SUBJECT_KEY   = "subject"
+
     DEFAULT_ACTUALS   = [].freeze
     DEFAULT_CONTEXTS  = {}.freeze
-    DEFAULT_HEAD      = "# Brutal test suite"
+    DEFAULT_HEADER    = "# Brutal test suite"
     DEFAULT_SUBJECT   = ""
 
     # Load the configuration parameters.
@@ -15,10 +20,10 @@ module Brutal
     # @param params [Hash] Receive the 4 top-level section parameters.
     def self.load(params)
       new(
-        actuals:  params.fetch("actuals", DEFAULT_ACTUALS),
-        contexts: params.fetch("contexts", DEFAULT_CONTEXTS),
-        header:   params.fetch("header", DEFAULT_HEAD),
-        subject:  params.fetch("subject", DEFAULT_SUBJECT)
+        actuals:  params.fetch(ACTUALS_KEY, DEFAULT_ACTUALS),
+        contexts: params.fetch(CONTEXTS_KEY, DEFAULT_CONTEXTS),
+        header:   params.fetch(HEADER_KEY, DEFAULT_HEADER),
+        subject:  params.fetch(SUBJECT_KEY, DEFAULT_SUBJECT)
       )
     end
 

data/lib/brutal/file/read.rb

@@ -1,19 +1,14 @@
 # frozen_string_literal: true
 
 module Brutal
-  # Brutal::File
-  #
-  # @since 1.1.0
   module File
     # Brutal::File::Read
     #
     # @since 1.1.0
     class Read
-      NAME = ".brutal.yml"
-
       attr_reader :name
 
-      def initialize(name = NAME)
+      def initialize(name)
         @name = name
       end
 

data/lib/brutal/file/write.rb

@@ -1,19 +1,14 @@
 # frozen_string_literal: true
 
 module Brutal
-  # Brutal::File
-  #
-  # @since 1.1.0
   module File
     # Brutal::File::Write
     #
     # @since 1.1.0
     class Write
-      NAME = "test.rb"
-
       attr_reader :name
 
-      def initialize(name = NAME)
+      def initialize(name)
         @name = name
       end
 

data/lib/brutal/file.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+%w[
+  read
+  write
+].each { |filename| require_relative(File.join("file", filename)) }
+
+module Brutal
+  # Brutal::File
+  module File
+    DEFAULT_CONFIG_FILENAME = ".brutal.yml"
+    DEFAULT_GENERATED_FILENAME = "test.rb"
+
+    def self.generated_pathname(pathname)
+      filename = pathname.split(separator).fetch(-1)
+
+      if filename == DEFAULT_CONFIG_FILENAME
+        directory_parts = pathname.split(separator)[..-2]
+        path_parts = directory_parts + [DEFAULT_GENERATED_FILENAME]
+        return path_parts.join(separator)
+      end
+
+      pathname.gsub(/.[^.]+\z/, ".rb")
+    end
+
+    def self.override_protection(pathname)
+      return true unless ::File.exist?(pathname)
+
+      abort "A #{pathname} file already exists!"
+    end
+
+    def self.separator
+      ::File::SEPARATOR
+    end
+    private_class_method :separator
+  end
+end

data/lib/brutal/scaffold.rb

@@ -41,23 +41,36 @@ module Brutal
     # Return a string representation.
     #
     # @return [String]
-    #
-    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
     def to_s
-      "#{header.chomp}\n#{blank_line}" + combinations_values.map do |values|
-        attributes = context_names.each_with_index.inject({}) do |h, (name, i)|
-          h.merge(name.to_sym => inspect(values.fetch(i)))
-        end
+      ruby_lines.join(separator_ruby_code)
+    end
 
-        actual_str = format(inspect(subject), **attributes)
+    def attributes(*values)
+      context_names.each_with_index.inject({}) do |h, (name, i)|
+        h.merge(name.to_sym => inspect(values.fetch(i)))
+      end
+    end
 
-        string = <<~CODE
-          actual = begin
-          #{actual_str.gsub(/^/, '  ')}
-          end
+    def context_names
+      contexts.keys.sort
+    end
 
-        CODE
+    def contexts_values
+      context_names.map { |context_name| contexts.fetch(context_name) }
+    end
 
+    def combinations_values
+      Array(contexts_values[0]).product(*Array(contexts_values[1..]))
+    end
+
+    def ruby_lines
+      [header_ruby_code] + actual_ruby_codes
+    end
+
+    def actual_ruby_codes
+      combinations_values.map do |values|
+        actual_str = format(inspect(subject), **attributes(*values))
+        string = actual_ruby_code(actual_str)
         actual = eval(actual_str) # rubocop:disable Security/Eval, Lint/UselessAssignment
 
         actuals.each do |actual_value|
@@ -66,26 +79,35 @@ module Brutal
         end
 
         string
-      end.join(blank_line)
+      end
     end
-    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
-    def blank_line
-      "\n"              \
-      "# #{'-' * 78}\n" \
-      "\n"
+    def actual_ruby_code(actual_str)
+      <<~RUBY_CODE
+        actual = begin
+        #{actual_str.gsub(/^/, '  ')}
+        end
+
+      RUBY_CODE
     end
 
-    def context_names
-      contexts.keys.sort
+    def header_ruby_code
+      <<~RUBY_CODE
+        #{header.chomp}
+      RUBY_CODE
     end
 
-    def contexts_values
-      context_names.map { |context_name| contexts.fetch(context_name) }
+    def separator_ruby_code
+      <<~RUBY_CODE
+
+        #{thematic_break_ruby_code}
+      RUBY_CODE
     end
 
-    def combinations_values
-      Array(contexts_values[0]).product(*Array(contexts_values[1..]))
+    def thematic_break_ruby_code
+      <<~RUBY_CODE
+        # #{'-' * 78}
+      RUBY_CODE
     end
   end
 end

data/lib/brutal/yaml.rb

@@ -7,8 +7,18 @@ module Brutal
   #
   # @since 1.1.0
   module Yaml
+    FILENAME_EXTENSIONS = %w[
+      yaml
+      yml
+    ].freeze
+
     def self.parse(yaml)
       ::YAML.safe_load(yaml, symbolize_names: false)
     end
+
+    def self.parse?(pathname)
+      filename_extension = pathname.split(".")[1..][-1]
+      FILENAME_EXTENSIONS.include?(filename_extension)
+    end
   end
 end

data/lib/brutal.rb

@@ -2,23 +2,42 @@
 
 %w[
   configuration
-  file/read
-  file/write
+  file
   scaffold
   yaml
-].each { |file_name| require_relative(File.join("brutal", file_name)) }
+].each { |filename| require_relative(File.join("brutal", filename)) }
 
 # The Brutal namespace.
 module Brutal
-  def self.generate!
-    yaml = File::Read.new.call
-    hash = Yaml.parse(yaml)
+  def self.generate!(pathname, force: true)
+    hash = parse(pathname)
     conf = Configuration.load(hash)
+
     ruby = Scaffold.new(conf.header,
                         conf.subject,
                         *conf.actuals,
                         **conf.contexts)
 
-    File::Write.new.call(ruby)
+    write(pathname, ruby, force: force)
+  end
+
+  def self.parse(pathname)
+    return Yaml.parse(read(pathname)) if Yaml.parse?(pathname)
+
+    raise ::ArgumentError, "Unrecognized extension.  " \
+                           "Impossible to parse #{pathname.inspect}."
+  end
+  private_class_method :parse
+
+  def self.read(pathname)
+    File::Read.new(pathname).call
+  end
+  private_class_method :read
+
+  def self.write(pathname, ruby, force:)
+    new_pathname = File.generated_pathname(pathname)
+    File.override_protection(new_pathname) unless force
+    File::Write.new(new_pathname).call(ruby)
   end
+  private_class_method :write
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: brutal
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Cyril Kato
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-05-12 00:00:00.000000000 Z
+date: 2022-08-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -38,6 +38,20 @@ dependencies:
     - - ">="
       - !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
@@ -134,6 +148,7 @@ files:
 - bin/brutal
 - lib/brutal.rb
 - lib/brutal/configuration.rb
+- lib/brutal/file.rb
 - lib/brutal/file/read.rb
 - lib/brutal/file/write.rb
 - lib/brutal/scaffold.rb
@@ -141,7 +156,8 @@ files:
 homepage: https://github.com/fixrb/brutal
 licenses:
 - MIT
-metadata: {}
+metadata:
+  rubygems_mfa_required: 'true'
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -157,7 +173,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.1.6
 signing_key: 
 specification_version: 4
 summary: A code-first approach to automate the writing of unit tests.