brutal 1.6.0.beta4 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f39f334e466f02513f3458e0a3f20ac59a4a3d7bf76f1c0cb7bbe97128c4aae
-  data.tar.gz: 06ef4476162a2f4570107ee9c70a97320aeeb95ee8f2851e27d07dc7aed86fe3
+  metadata.gz: fac7c55010f838339f889a969e3ba78fc7ee40b279b0d426248b0eec5f5f8b0f
+  data.tar.gz: 5be3b432b0319f72073043ddb2c8fad5c2cf053da211f80c6a5588942beaf701
 SHA512:
-  metadata.gz: 22c03d27d6ab4e183f2469121e502bc0ad17705f90788dcb7b949b983cf70ba6f2e5344fa5db5f17a77a5cf6b66ec8a5c543bc7baf330b853acff70a82f8fdb7
-  data.tar.gz: 0f65b683c466789227826090f31a0e1ef976bb0d83d73f99549862be928c8643af0b5fac82bf0572db17dc978bc1a666a5dd1b4bcfeb7be5274b836e380a26db
+  metadata.gz: b52adf50058f49a60fb97d80f35340a845d489a1547cb9186ff2f6913990a064f23c65b2adf10968dec2fecc91e3f5b8259ab0c02b30a996776d123f85b3887a
+  data.tar.gz: 96ebc35d1e1326d99350e389787168e0dae7f65c26c273d943f4f516dac487505ed7e743bd556439cd03825d62bd357da37edd47071cb8b43d8c6f8821e0a596

data/LICENSE.md

@@ -1,6 +1,6 @@
 # The MIT License
 
-Copyright (c) 2020-2022 Cyril Kato
+Copyright (c) 2020-2026 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

@@ -2,147 +2,225 @@
 
 [![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.
 
-## Intro
+> I don't like tests. It's not DRY.
+> -- [Matz](https://github.com/matz), [RubyHack 2019](https://www.youtube.com/embed/cmOt9HhszCI?start=1732&end=1736)
 
-[![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.")
+![Brutal-Driven Development](https://github.com/fixrb/brutal/raw/main/img/brutal-driven-development.png)
 
-> I don't like tests. It's not DRY.
-> -- [Matz](https://github.com/matz)
+Brutal writes plain Ruby test files from YAML manifests. A manifest gives a subject, contexts to combine and actuals to observe; brutal runs every combination, records what the code returns, and writes a test file that checks each of these values, without any framework: `ruby test_user.rb` runs it.
 
-## Overview
+A test file written by brutal is a picture of what the code does, not of what it should do. If the code is wrong, the picture is wrong too, and every check passes: read the test file before you trust it, as you would read any code under review.
 
-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.
+## Installation
 
-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.
+```ruby
+# Gemfile
+gem "brutal", require: false
+```
 
-![Brutal-Driven Development](https://github.com/fixrb/brutal/raw/main/img/brutal-driven-development.jpg)
+or `gem install brutal` for the command alone.
 
-## Warning
+Brutal requires Ruby 3.3 or later and `fork(2)`: it runs the code in a child process through [Aw](https://github.com/fixrb/aw), on Linux and macOS, with CRuby. Windows and JRuby are not supported.
 
-The _Brutal-Driven Development_ process does not prevent bugs from appearing in the code.
+## Usage
 
-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.
+Given this class:
 
-The mere fact that all expectations are true does not mean that the code behaves as it should.
+```ruby
+# lib/greeter.rb
+class Greeter
+  def initialize(name)
+    @name = name.capitalize
+  end
+
+  def salute
+    "Hello #{@name}!"
+  end
+end
+```
 
-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.
+a manifest is a file named `NAME_brutal.yaml`:
 
-## Installation
+```yaml
+# test/greeter_brutal.yaml
+header: |
+  require_relative "../lib/greeter"
 
-Add this line to your application's Gemfile:
+subject: |
+  Greeter.new(%{name})
 
-```ruby
-gem "brutal", ">= 1.6.0.beta4", require: false
-```
+contexts:
+  name:
+    - '"Alice"'
+    - '"world"'
 
-And then execute:
+actuals:
+  - "%{subject}.salute"
+  - "%{subject}.salute.length"
+```
 
 ```sh
-bundle install
+bundle exec brutal test/greeter_brutal.yaml
 ```
 
-Or install it yourself as:
+Brutal writes `test/test_greeter.rb` next to it:
 
-```sh
-gem install brutal --pre
-```
+```ruby
+# Generated by brutal from greeter_brutal.yaml: edit the manifest, then run brutal again.
 
-## Usage
+require_relative "../lib/greeter"
 
-### YAML manifest
+# ------------------------------------------------------------------------------
 
-__Brutal__ needs configuration files in YAML format to know how to write tests.
-Configuration file names are suffixed by `_brutal.yaml` and composed of 7 top-level sections:
+actual = begin
+  Greeter.new("Alice")
+end
 
-* `header` - Specifies a block of lines to be executed once before all examples.
-* `before` - Specifies a block of lines to be executed before each example.
-* `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.
-* `after` - Specifies a block of lines to be executed after each example.
-* `footer` - Specifies a block of lines to be executed once after all examples.
+::Kernel.raise "name = \"Alice\": actual.salute" unless ("Hello Alice!").eql?((
+  actual.salute
+))
+::Kernel.raise "name = \"Alice\": actual.salute.length" unless (12).eql?((
+  actual.salute.length
+))
 
-### Command line
+# ------------------------------------------------------------------------------
 
-The `brutal` command comes with several options you can use to customize Brutal's behavior.
+actual = begin
+  Greeter.new("world")
+end
 
-For a full list of options, run the `brutal` command with the `--help` flag:
+::Kernel.raise "name = \"world\": actual.salute" unless ("Hello World!").eql?((
+  actual.salute
+))
+::Kernel.raise "name = \"world\": actual.salute.length" unless (12).eql?((
+  actual.salute.length
+))
+```
 
 ```sh
-brutal --help
+ruby test/test_greeter.rb
 ```
 
-```txt
-Usage: brutal [options] [files or directories]
+A check that fails raises a `RuntimeError` that names the example and the actual; the rest of the file does not run. More examples are in [examples/](https://github.com/fixrb/brutal/tree/main/examples/).
 
-    --format=FORMAT Choose "ruby" (default).
-    --help          Display this help.
-    --version       Display the version.
-```
+## The manifest
 
-Assuming that in the workspace there is a configuration file named `user_brutal.yaml`, the test suite can be generated via one of these commands:
+A manifest is a UTF-8 file (a BOM is accepted) holding one YAML document of seven sections; all but `contexts` hold Ruby code:
 
-```sh
-brutal user_brutal.yaml
-```
+* `header` (optional): run once, before the first example.
+* `before` (optional): run before each example.
+* `subject`: the code of each example, with a `%{name}` for each context.
+* `contexts`: for each name, a list of code fragments to put in place of `%{name}`.
+* `actuals`: the expressions to observe, with `%{subject}` for the value of the subject.
+* `after` (optional): run after each example.
+* `footer` (optional): run once, after the last example.
 
-or:
+There is one example for every combination of the contexts, in the order of the file, the first context varying the slowest. In each example, the value of the subject is held in a local variable named `actual`, and each actual is checked in turn.
 
-```sh
-brutal .
-```
+The values are read as text, never converted to YAML types: `1,2`, `yes`, `~` or `12:30` stay the Ruby code `1,2`, `yes`, `~` and `12:30` (`1,2` makes sense in a subject such as `[%{v}]`). Only the line breaks that end a value are dropped. YAML's own rules still apply: quotes and escapes are read as YAML reads them, a value that starts with a YAML indicator (`%`, `[`, `{`, `&`, `*`, `!`, `|`, `>`, `@`, `#`…) or holds `: ` or ` #` must be quoted (an unquoted ` #` starts a comment, silently), and in a flow list (`[a, b]`) a comma separates items. A value of several lines must be a literal block (`|`), which YAML does not fold. A fragment is code: a string needs its quotes (`'"Alice"'`), and a plain `Alice` is a constant.
 
-or even:
+`%{name}` is replaced in the subject, and `%{subject}` in the actuals; nothing else is interpreted, and any other `%` is a `%`. Brutal refuses a placeholder without a context, a context the subject does not use, an actual that uses anything but `%{subject}`, a placeholder in another section, unknown, duplicate, missing or empty sections, and YAML anchors, aliases and tags. `NAME` is made of ASCII letters, digits, `.`, `_` and `-`, and does not start with a dot or a dash; a context name is made of ASCII letters, digits and `_`, and does not start with a digit.
 
-```sh
-brutal
-```
+Each section, each subject once its fragments are in place, and each actual must be complete code on its own, and must not hold an end of file (an `__END__` line, a NUL, a ^D or a ^Z): a part cannot open a block, a string or a comment that another part closes, so it cannot skip, swallow or reorder a check. A part can still read differently once combined, through a local variable of an earlier part (`foo -1` is a call alone, a subtraction after `foo = 10`); the recording and the test file read it the same way.
 
-This would create a `test_user.rb` file containing the test suite.
+In the test file, a subject or an actual of one line is indented; one of several lines is written as it is, so that a multi-line string or a heredoc keeps its content. The other sections are written as they are.
 
-Assuming now that in the workspace there are a large number of configuration files named in the `spec/` folder, the complete test suite could be generated recursively via this command:
+## How the code runs
 
-```sh
-brutal spec/
+Brutal runs the code in a child process, as `ruby` will run the test file: at the top level, with `self` as `main`, the magic comments of the header (`# frozen_string_literal: true`), the local variables of each section visible to the next ones, `__dir__` the directory of the test file, `__FILE__` and `$0` its absolute path, no arguments and nothing on the standard input. It runs in the current directory: use `require_relative` and `__dir__` rather than paths relative to it. What the code does to the process (a monkey patch, a global, a constant, the current directory, `ENV`, a crash) stays in the child; what it does outside, to files or other processes, happens.
+
+Then brutal runs the test file with the Ruby that runs brutal, in a new process, from the current directory, under a temporary name next to it (`.test_NAME.rb.PID.tmp`), before it writes it; an unchanged test file is run where it is. It must pass; when it does not, brutal reports the first line of its standard error that is not a warning. This catches what differs between brutal's child and a real run: the child was forked from brutal, so it has the constants `Aw`, `Brutal`, `Psych` and `StringIO` (and Psych's `to_yaml`), which the test file alone does not; and a hash, an object id or a random number may differ from one process to the next. A value that happens to be the same in both runs (the current minute, a small random number) is not caught: do not observe it. Do not observe `__FILE__` or `$0` either: they are the absolute path of the test file in the recording, a temporary name in brutal's run, and what you type in yours; during the recording, the test file does not exist yet, or is the previous one.
+
+So the code runs twice. Its output shows once, the test file's run being silent, but its side effects happen twice. `--check` runs it once, and writes nothing.
+
+Brutal runs every manifest it is given: a manifest is code, and runs with your rights. Run brutal on your own manifests only.
+
+## Expected values
+
+An observed value is written as a Ruby literal, the same whatever the version of Ruby and the locale: `nil`, `true`, `false`, an `Integer`, a finite `Float`, a `String` in UTF-8, in binary, or with ASCII characters only, a `Symbol`, and an `Array` or a `Hash` of these, by their exact class. Non-ASCII and invisible characters are escaped (`"caf\u00E9"`), and a hash is written with `=>`.
+
+Anything else is refused, with the example and the actual: an object, a `Struct`, a `Set`, a `Range`, a `Rational`, a `Time`, a subclass of `String`, `Array` or `Hash`, `NaN`, an infinite `Float`, a string with non-ASCII characters in another encoding, a structure nested more than 100 levels deep or that contains itself. Observe a projection instead: `.to_s`, `.to_a`, `.to_h`, `.size`, an attribute. Mind that some projections depend on the version of Ruby: `{a: 1}.to_s` is `"{:a=>1}"` before Ruby 3.4 and `"{a: 1}"` since, and the text of an error message changes from one version to another.
+
+Each value is checked with `eql?`, the expected value receiving the call: `1` and `1.0` differ, and an object that claims to equal everything does not pass. `eql?` does not tell `0.0` from `-0.0`, nor the encoding of a string of ASCII characters. Once the test file is written, a string, an array or a hash of a subclass with the same content would pass it, and a hash compares its pairs with `eql?`; an object that is not a hash but converts to one (`to_hash`) is compared by its own `eql?`.
+
+## The command
+
+```txt
+Usage: brutal [--check] PATH...
+
+Writes test_NAME.rb next to each NAME_brutal.yaml given as PATH, or found
+in a directory given as PATH and its subdirectories.
+
+    --check     Run the code, write nothing; fail when a test file is missing or differs.
+    --help, -h  Show this help.
 ```
 
-This would create one test file per configuration file matching `./spec/**/*_brutal.yaml` in to `./spec/**/test_*.rb`.
+A directory is searched with its subdirectories, in order; hidden files and directories, symbolic links to directories, and anything but a regular file (a symbolic link to one counts) are left out, and a directory that cannot be read is an error, and no manifest of that PATH runs. A manifest given twice, or through a symbolic link to its directory, runs once. Point brutal at your test directory: a directory holding installed gems (`vendor/bundle`) holds code you did not write. An argument that starts with `-` is an option: a path that does is written `./-x`.
 
-### Some examples
+A test file is written whole or not at all, through a temporary file renamed over it, with the permissions of the file it replaces (not its setuid, setgid or sticky bits); an unchanged file is left untouched, but run again. Brutal only replaces a file it wrote, whose first line is `# Generated by brutal from`, and checks this before running the code: a test file written by hand, or by brutal 1, a symbolic link or a directory in its place is an error.
 
-<https://github.com/fixrb/brutal/tree/main/examples/>
+Each manifest that fails is reported on the standard error, with its path and the reason, and the others still run. The exit status is 0 when every manifest succeeded, 1 when one failed or a path designates no manifest, and 2 for a usage error. Interrupted, brutal kills the code it runs, writes nothing more, and ends by the signal.
 
-## Rake integration example
+`--check` generates every test file in memory and compares it with the one in place, without running it: run it in CI, so that a test file cannot drift from its manifest. It reports a missing test file, one out of date and one brutal did not write, but not a test file whose manifest was removed.
 
-Generated test suite files could be matched as follows:
+## Rake integration
 
 ```ruby
+# Rakefile
+require "rake/testtask"
+
+desc "Write the test files of the brutal manifests"
+task :brutal do
+  require "brutal"
+  raise "brutal failed" unless Brutal::CLI.run(["test"]).zero?
+end
+
 Rake::TestTask.new do |t|
-  t.pattern = "**/test_*.rb"
+  t.pattern = "test/**/test_*.rb"
 end
 ```
 
-## Contact
+In CI, run `bundle exec brutal --check test` before the tests.
 
-* Source code: https://github.com/fixrb/brutal
+## Things to know
+
+- The test file is plain Ruby, run by `ruby` or any test runner that loads files. It uses one local variable, `actual`, at the top level of the file; under `ruby -w`, a manifest whose actuals do not use `%{subject}` warns that `actual` is unused.
+- A failing check raises, and stops its file. `Rake::TestTask` loads every test file in one process: the first failure stops the run, and what a test file changes (a monkey patch) reaches the files loaded after it. Brutal runs each test file alone.
+- An `exit`, an `exit!` or a signal during the recording, or a top-level `return` that skips a check of the recording, is reported as a failure of the manifest, and nothing is written. During the recording, `at_exit` handlers do not run.
+- There is no timeout: code that never ends keeps brutal waiting, and so does, during the recording, a process the code forks and leaves running. Killed with `SIGKILL`, brutal leaves its child running, and may leave a `.test_NAME.rb.PID.tmp` file next to the test file.
+- A magic comment that must be on the first line (`# encoding:`, `# warn_indent:`) has no effect in the header, which starts on the third line; `# frozen_string_literal:` and `# shareable_constant_value:` do. The test file is read as UTF-8.
+- On macOS, code that uses Objective-C classes may crash in the child process: run brutal with `OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES`.
+- A check is `::Kernel.raise … unless (expected).eql?((actual))`: code that redefines `Kernel.raise`, or `eql?` on core classes (a refinement included), ends the process from an `at_exit` handler or a `TracePoint`, or behaves differently when it finds brutal (`$__brutal__`), changes the checks. Brutal does not guard against code that sets out to defeat it.
+
+## Changes in 2.0
+
+Compared with 1.6.0.beta4:
+
+- The code no longer runs inside brutal, through `eval` in a method of the generator, in the directory of the manifest, but in a child process, at the top level, from the current directory, as the test file runs: `self`, local variables across sections, reopened classes, magic comments and `__dir__` behave as in the test file, and nothing leaks from a manifest to the next one or to brutal. Before it is written, the test file must pass when `ruby` runs it.
+- An expected value is written as a literal by brutal, never as its `inspect`: a value whose `inspect` is not Ruby (`#<Point …>`, which turned the rest of the line into a comment and hid the next check), an unparenthesized `Range` or a `Rational` is refused instead of written. Literals are the same whatever the version of Ruby and the locale.
+- A check is `(expected).eql?((actual))`: the expected value decides, an `Integer` that becomes a `Float` fails, and an actual is parenthesized on its own lines, so that a `rescue` modifier, an `&&` or a trailing comment stays inside it. A check that fails names the example and the actual.
+- Each section, subject and actual must be complete code on its own, without an end of file.
+- A test file is written whole, through a temporary file, and only over a file brutal wrote. A manifest that fails no longer empties its test file.
+- The manifest is read as text: YAML no longer turns `1,2` into `12` or `yes` into `true`, and fragments are no longer stripped. A value of several lines must be a literal block. `%{name}` is replaced by brutal itself: a `%` in the code is written once, and a `%%` that 1.x needed must be undoubled. Anchors, tags, unknown or duplicate sections, empty sections, a scalar context, a missing `contexts` or `actuals` section, unused contexts and placeholders outside the subject and the actuals are refused. Contexts combine in the order of the file, instead of the alphabetical order of their names. A manifest's name is limited to ASCII letters, digits, `.`, `_` and `-`, and does not start with `.` or `-`.
+- Code of several lines is no longer indented, which changed multi-line strings and heredocs.
+- `brutal` requires a path, and no longer searches the current directory by default. `--check` is new; `--format` and `--version` are gone. A failing manifest is reported with its path and the others still run, where 1.x stopped at the first, with a backtrace.
+- The test file starts with a line saying it was generated, and has no default comments. Test files written by brutal 1 do not carry it: delete them once, then run brutal again.
+- Ruby 3.3 or later, and Aw 1.0.
+
+Compared with 1.5.0, the last stable release, a manifest is no longer any YAML file (`.brutal.yml` by default, written to `test.rb`, or `foo.yaml` to `foo.rb`), and `--no-force` is gone: every manifest is `NAME_brutal.yaml`, written to `test_NAME.rb`. The `before`, `after` and `footer` sections are new, and an unknown section, which 1.5.0 ignored, is refused.
 
 ## Versioning
 
-__Brutal__ follows [Semantic Versioning 2.0](https://semver.org/).
+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://github.com/fixrb/brutal/raw/main/LICENSE.md).
 
-***
-
-This project is sponsored by [Sashité](https://github.com/sashite/):
+## Sponsors
 
-![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é")
+This project is sponsored by [Sashité](https://sashite.com/)

data/bin/brutal

@@ -1,18 +1,13 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require_relative File.join("..", "lib", "brutal", "command_line_arguments_parser")
-
-formats, pathnames = Brutal::CommandLineArgumentsParser.new(*ARGV).call
-
 require_relative File.join("..", "lib", "brutal")
 
-formats.each do |format|
-  generator = Brutal.new(format)
-
-  pathnames.each do |pathname|
-    Dir.chdir(pathname.dirname) do
-      generator.call(pathname.basename)
-    end
-  end
+begin
+  exit Brutal::CLI.run(ARGV)
+rescue Interrupt
+  # Aw has killed and reaped the child. End by the signal, as an interrupted
+  # command does, so that a shell loop stops too, but without a backtrace.
+  Signal.trap(:INT, "SYSTEM_DEFAULT")
+  Process.kill(:INT, Process.pid)
 end

data/lib/brutal/cli.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Brutal
+  # The `brutal` command.
+  module CLI
+    # @return [String]
+    USAGE = <<~TXT
+      Usage: brutal [--check] PATH...
+
+      Writes test_NAME.rb next to each NAME_brutal.yaml given as PATH, or found
+      in a directory given as PATH and its subdirectories.
+
+          --check     Run the code, write nothing; fail when a test file is missing or differs.
+          --help, -h  Show this help.
+    TXT
+
+    OPTIONS = %w[--check --help -h].freeze
+    HELP = %w[--help -h].freeze
+    private_constant :OPTIONS, :HELP
+
+    # Runs the command. A manifest that fails is reported on `err`, and the
+    # others still run.
+    #
+    # @param arguments [Array<String>] the options and paths
+    # @param out [IO] where the help goes
+    # @param err [IO] where the errors go
+    # @return [Integer] 0 when every manifest succeeded, 1 when one failed or a path
+    #   designates no manifest, 2 for a usage error
+    def self.run(arguments, out: $stdout, err: $stderr)
+      options, paths = arguments.partition { |argument| argument.start_with?("-") }
+      problem = problem(options, paths)
+      return usage(err, problem) if problem
+      return help(out) if options.intersect?(HELP)
+
+      succeeded?(paths, options.include?("--check"), err) ? 0 : 1
+    end
+
+    # What is wrong with the arguments, if anything.
+    def self.problem(options, paths)
+      unknown = options - OPTIONS
+      return "unknown option #{unknown.first}" unless unknown.empty?
+
+      "no path given" if paths.empty? && !options.intersect?(HELP)
+    end
+
+    # Processes the manifests of every path, each once (a manifest is known
+    # by its name and the real path of its directory, as its test file is);
+    # true when all succeeded.
+    def self.succeeded?(paths, check, err)
+      found = paths.map { |path| manifests(path, err) }
+      unique = found.compact.flatten.uniq do |path|
+        ::File.join(::File.realpath(::File.dirname(path)), ::File.basename(path))
+      end
+      unique.map { |path| process(path, check, err) }.all? && !found.include?(nil)
+    end
+
+    # The manifests a path designates: the path itself, or the manifests in
+    # a directory and its subdirectories, in order. Hidden files and
+    # directories, and symbolic links to directories, are left out. Nil,
+    # after a message, when there is none.
+    def self.manifests(path, err)
+      return [path] if ::File.file?(path)
+
+      found = ::File.directory?(path) ? search(path) : []
+      return found unless found.empty?
+
+      report(err, path, ::File.exist?(path) ? "no manifest found" : "no such file or directory")
+      nil
+    rescue ::SystemCallError => e
+      report(err, path, e.message)
+      nil
+    end
+
+    # The regular files named `*_brutal.yaml` in a directory and its
+    # subdirectories; a directory that cannot be read is an error.
+    def self.search(directory)
+      ::Dir.children(directory).sort.flat_map do |name|
+        path = ::File.join(directory, name)
+        if name.start_with?(".") then []
+        elsif ::File.directory?(path) then ::File.symlink?(path) ? [] : search(path)
+        else name.end_with?(Manifest::SUFFIX) && ::File.file?(path) ? [path] : []
+        end
+      end
+    end
+
+    # Generates the test file of a manifest, then writes it, or compares it
+    # with the file in place. A file brutal cannot replace is refused before
+    # the code runs.
+    def self.process(path, check, err)
+      Output.check(Output.target(path))
+      return current?(Brutal.generate(path), path, err) if check
+
+      Brutal.write(Brutal.generate(path))
+      true
+    rescue Error, ::SystemCallError => e
+      report(err, path, e.message)
+      false
+    end
+
+    # Whether the test file in place is the one brutal would write.
+    def self.current?(test, path, err)
+      return true if Output.current?(test.path, test.source)
+
+      report(err, path, "#{text(test.path)} is #{::File.exist?(test.path) ? "not up to date" : "missing"}")
+      false
+    end
+
+    # Reports why a path failed, as `brutal: PATH: REASON`.
+    def self.report(err, path, reason)
+      err.puts("brutal: #{text(path)}: #{text(reason)}")
+    end
+
+    # A string relabelled as UTF-8, its bytes unchanged: the file system and
+    # the locale name a path in an encoding of their own, in which it could
+    # not join the text of a manifest.
+    def self.text(string)
+      string.dup.force_encoding(::Encoding::UTF_8)
+    end
+
+    # Prints the help.
+    def self.help(out)
+      out.puts(USAGE)
+      0
+    end
+
+    # Prints a usage error, then the help.
+    def self.usage(err, message)
+      err.puts("brutal: #{message}", "", USAGE)
+      2
+    end
+
+    private_class_method :problem, :succeeded?, :manifests, :search, :process, :current?, :report, :text, :help, :usage
+  end
+end

data/lib/brutal/literal.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Brutal
+  # Writes an observed value as a Ruby literal, the same whatever the version
+  # of Ruby and the locale: `nil`, `true`, `false`, an `Integer`, a finite
+  # `Float`, a `String` in UTF-8, in binary or with ASCII characters only, a
+  # `Symbol`, and an `Array` or a `Hash` of these. Anything else is refused,
+  # never written as its `inspect`.
+  module Literal
+    SYMBOL = /\A[A-Za-z_][A-Za-z0-9_]*[?!]?\z/
+    private_constant :SYMBOL
+
+    # @param value [Object] a value made of the classes above only
+    # @return [String] Ruby source code that evaluates to a value `eql?` to it
+    # @raise [Brutal::Error] when the value cannot be written as a literal
+    def self.dump(value)
+      case value
+      when nil, true, false, ::Integer then value.inspect
+      when ::Float then float(value)
+      when ::String then string(value)
+      when ::Symbol then symbol(value)
+      when ::Array then "[#{value.map { |item| dump(item) }.join(", ")}]"
+      when ::Hash then pairs(value)
+      else raise Error, "is an instance of #{value.class}"
+      end
+    end
+
+    # A finite Float, as Float#to_s writes it: the shortest exact form.
+    def self.float(value)
+      raise Error, "is the Float #{value}" unless value.finite?
+
+      value.to_s
+    end
+
+    # A String with its escapes from String#dump, which ignores the locale;
+    # `.b` keeps a binary string binary.
+    def self.string(value)
+      return value.dump if value.encoding == ::Encoding::UTF_8 || value.ascii_only?
+      return "#{value.dump}.b" if value.encoding == ::Encoding::BINARY
+
+      raise Error, "is a String in #{value.encoding}"
+    end
+
+    # A Symbol, quoted unless its name is a plain identifier.
+    def self.symbol(value)
+      name = value.name
+      return ":#{name}" if SYMBOL.match?(name)
+      return ":#{name.dump}" if name.encoding == ::Encoding::UTF_8 || name.ascii_only?
+
+      raise Error, "is a Symbol in #{name.encoding}"
+    end
+
+    # A Hash, with `=>` for every key.
+    def self.pairs(value)
+      return "{}" if value.empty?
+
+      "{#{value.map { |key, item| "#{dump(key)} => #{dump(item)}" }.join(", ")}}"
+    end
+
+    private_class_method :float, :string, :symbol, :pairs
+  end
+end