reviewer 0.1.5 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4269dc4784c9a22232bd47db41cff0bf7d57b023ee50dc5fc455a650fb138b2a
-  data.tar.gz: 73d9261188abd69db6aa23aa7db6f76a59696b1dac3e35eb1a5615e013b40354
+  metadata.gz: 8d918dfc0f53f9d2283d846207fc760f0aa0cafaa2d9db0f2225396935cdbd38
+  data.tar.gz: 2f8635ce31fee7646608c5dd591c277190e918b3c940b773d04731254c3ea707
 SHA512:
-  metadata.gz: 66894ea63a67d4964e93a5ab83ce92b95e0757d38af05a1587e136d0cc2d61fcf146d2c30534ce3f58aa4f08ed406e328ecad1293a617df73b2d1167c6146782
-  data.tar.gz: 0614f40cbd184e0e20aad58a8f4c320af3a5db358078cecdfac236047a0c85060b15b7dccbade7c599c4ebc030ea0eb4348d239fbbf3f25a48079f6f3a0464f7
+  metadata.gz: fc770176795e88d1c88e56903eb1ce3d756f0f46176edc1d1a280bff14069b0739a27a4aefa6ca04313c08f1324e3f9d45da86860c9563c97f7a82472005f7ca
+  data.tar.gz: dbfdb47cbc0c321bc2338251b4a16242d976d4b6fb893019e7dc5578d875bfc85ef4124297864fa50cbe52cf7189471e6fc2ece940e114cf92fe8ab0e429e369

data/.reviewer.example.yml

@@ -1,42 +1,40 @@
-# Quick overview of the options configuration for command-line tools.
-# It can be handy to leave this section in your configuration file as a convenient reference.
+# Copy the settings a tool needs into `.reviewer.yml`. Only `commands.review` is required.
 #
-# <command_key>:                // ex. 'rubocop', 'bundler-audit', etc.
-#  disabled: true               // Optional. Tools are enabled by default
-#  name:                        // Optional. Will use the `command_key` if name isn't provided.
-#  description:                 // Optional. Serves as a handy reminder for the purpose of the command.
-#  tags: [ruby, dependencies]   // Optional. Lets you run commands tagged with the same word.
+# <tool-key>:
+#  skip_in_batch: true          # Exclude from bare `rvw`; keep available by key.
+#  name:                        # Defaults to the tool key.
+#  description:
+#  tags: [ruby, dependencies]
 #  links:
-#    home:                      // Optional. A link to the home page for the tool.
-#    install:                   // Optional. A link to the installation instructions for the tool.
-#    usage:                     // Optional. A link to the general usage instructions for the tool.
-#    ignore_syntax:             // Optional. A link to the syntax for ignoring some rules for small sections of code.
-#    disable_syntax:            // Optional. A link to the syntax for disabling entire rules for a tool.
+#    home:
+#    install:
+#    ignore_syntax:            # Shown after review failures.
+#    disable_syntax:           # Shown after review failures.
 #  commands:
-#    install:                   // Optional. Command to run to install the tool.
-#    prepare:                   // Optional. Command to run prior to the review phase. ex. 'bundle exec bundle-audit update'
-#    review:                    // Required. The only truly required field because this is the whole point.
-#    format:                    // Optional. Command to auto-update rule violations when possible.
-#    serve:                     // Optional. Command to start a local server with reports generated by the tool.
-#    generate:                  // Optional. Command to generate artifacts from the tool for viewing separately.
-#    max_exit_status:           // Optional, defaults to 0. Some tools like Yarn Audit essentially won't return less than a 3. This specifies the threshold that's still considered passing.
+#    install:                  # Displayed as guidance; never executed.
+#    prepare:                  # Attempted at most once every six hours, regardless of exit status.
+#    review:                   # Required.
+#    format:                   # Used by `fmt`.
+#    max_exit_status:          # Defaults to 0 for review commands.
 #  files:
-#    flag:                      // Optional, defaults to '' (empty string). The name of the flag used to pass subsets of files to the command.
-#    separator:                 // Optional, defaults to ' ' (single space). The character used to separate lists of files and directories.
-#  env:                         // Optional. A way to specify necessary environment variables for the tools commands. The key is the variable name, and the value is, well, the value.
-#    example_one: value         //           - The names will automatically be capitalized, so you can freely use lower-case here.
-#    example_one: value         //           - Reviewer is smart enough to handle string values with spaces and automatically quote them.
-#  flags:                       // Optional. A way to specify flags *only for the review command*. The key is the flag name, and the value is, well, the value.
-#    example_one: value         //           - Reviewer is smart enough to handle single-letter (-f) and multi-letter (--format) flags.
-#    example_two: value         //           - It's highly-recommended to use the longer-name format for flags when possible to serve as self-documentation.
-#    example_three:             //           - If the flag doesn't need or have a value, leaving it blank will translate it to a flag without a value.
-#  other:                       // Optional. A way to specify paramters that don't follow the standard flags conventions.
-#    description: value         //           - The key (ex. 'description') only serves as documentation and won't be used. Instead, the raw value will be applied
+#    review:                   # Replaces `commands.review` for targeted files.
+#    format:                   # Replaces `commands.format` for targeted files.
+#    flag:                     # Defaults to an empty string for bare paths.
+#    separator:                # Defaults to one space.
+#    pattern:                  # Slashless patterns match basenames; slashes match repository paths.
+#    map_to_tests:             # `minitest` or `rspec`.
+#  env:
+#    key: value
+#  flags:                      # Applied only to review commands.
+#    verbose:
+#  summary:
+#    pattern:
+#    label:                    # Supports numbered captures.
 
 
-# In practice, a configuration block would look something like the block below.
+# Complete supported example:
 tool-name-key:
-  disabled: true
+  skip_in_batch: true
   name: Tool
   description: A tool that finds issues and fixes code.
   tags: [syntax, security]
@@ -46,18 +44,23 @@ tool-name-key:
     ignore_syntax: https://example.com/ignore
     disable_syntax: https://example.com/disable
   commands:
-    install: 'bundle install tool'
+    install: 'bundle exec gem install tool'
     prepare: 'bundle exec tool update'
     review: 'bundle exec tool'
     format: 'bundle exec tool --format'
     max_exit_status: 1
   files:
-    flag: 'files'
+    review: 'bundle exec tool --files'
+    format: 'bundle exec tool --format --files'
+    flag: ''
     separator: ','
+    pattern: '{lib,test}/**/*.rb'
+    map_to_tests: minitest
   env:
     report: false
   flags:
     format: json
     verbose:
-  other:
-    example: '--example | other'
+  summary:
+    pattern: '(\d+) issues?'
+    label: '\1 issues'

data/CHANGELOG.md

@@ -1,7 +1,86 @@
 ## [Unreleased]
 
-- TODO: Improve and streamline installation
-- TODO: Add support for targeting specific files
+## [1.1.0] - 2026-08-28
+
+Reviewer 1.1 makes review outcomes more precise and dependable for people and automated consumers.
+Every tool result now has an authoritative state, aggregate summaries account for every outcome, and
+schema-versioned JSON exposes complete run details without requiring agents or integrations to parse
+human-readable output or infer meaning from a success boolean.
+
+File-scoped runs now select valid files for each tool independently and preserve failed-review
+history across non-review runs. Structured Doctor reports make setup and diagnostics inspectable by
+people and agents, while `rvw init` begins its transition toward explicit, project-owned
+configuration.
+
+### Upgrade notes
+- Unknown positional and `-t` selectors now stop before running tools and exit 2. Check scripts that relied on an unknown selector falling through to a batch run.
+- Reviewer now exits 0 for a successful review, 1 for a failed review, and 2 for an invocation error instead of forwarding a tool's exit status.
+- Skipped results now report `state: "skipped"`, `success: false`, and null execution fields. Integrations should use `state` to interpret each result.
+- `rvw init` remains available with its existing generation behavior for one deprecation cycle, but now prints a warning. Use `rvw doctor` to inspect project discoveries before creating or editing `.reviewer.yml`; existing configurations require no migration.
+
+### Added
+- Top-level tags and the `failed` keyword to the capabilities payload
+- Schema-versioned JSON with authoritative result states, complete state totals, empty and error envelopes, and tool-provided `detail_summary` values
+- Structured Doctor output for configuration findings, configured tools, project discoveries, environment checks, and summary totals
+- Repository-relative and brace-alternative matching for `files.pattern`
+
+### Changed
+- Moved long-form guidance into version-controlled repository documentation; setup output and gem metadata now link to it
+- Doctor separates configured tools from sourced project discoveries in human and JSON reports
+- `rvw init` now prints a deprecation warning directing setup work through `rvw doctor`
+- `rvw failed` preserves the last executed review across skipped tools, missing tools, formatting runs, and fail-fast tails; a successful retry clears the failure
+- File targeting applies each tool's scope independently, supports mixed file types, filters nonexistent paths, and passes shell-sensitive filenames without interpretation
+- Development dependencies are separated from optional dogfood tools; `bin/setup` enables the local dogfood bundle group
+
+### Fixed
+- `rvw init` generates a configuration instead of exiting with an `ArgumentError` backtrace
+- Generated Reek configuration now distinguishes full-project and file-scoped review commands
+- Generated Minitest configuration now executes every file in a scoped review
+- Result summaries now total every state accurately and avoid claiming all-missing runs passed
+- Recognized empty JSON requests now return a documented envelope instead of no output
+
+## [1.0.0] - 2026-02-03
+
+### Added
+- Git-aware file targeting: `staged`, `unstaged`, `modified`, `untracked` keywords resolve files from git status and pass only relevant files to each tool
+- `failed` keyword: re-run only tools that failed in the previous run, scoped to their failed files
+- `--json` / `-j` flag for structured JSON output (CI, scripting, agent integration)
+- `--raw` / `-r` flag to force passthrough output (bypasses capturing)
+- `--format` flag with streaming, summary, and json modes
+- `--capabilities` / `-c` flag for agent discovery (outputs JSON describing tools, keywords, scenarios)
+- `skip_in_batch` config option: exclude tools from `rvw` while keeping them available via `rvw tool_name`
+- `files.pattern` config: glob pattern to filter which files are passed to each tool
+- `files.map_to_tests` config: map source files to test files (`minitest` or `rspec` conventions)
+- `files.review` / `files.format` config: alternative commands when files are scoped
+- First-run experience: interactive setup when no `.reviewer.yml` exists
+- `rvw init` command: auto-detect tools from Gemfile.lock and generate `.reviewer.yml`
+- `rvw doctor` command: diagnostics for configuration, tools, keywords, and environment
+- Keyword resolution summary: preview which tools and files will run before execution
+- Spell-check suggestions for mistyped keywords
+- Auto-detection catalog: bundler-audit, rubocop, standard, reek, flog, flay, brakeman, fasterer, minitest, rspec, eslint, prettier, stylelint, typescript, biome
+- Progress bar for captured output with timing estimates
+- PTY-based streaming capture for failed file extraction from single-tool runs
+
+### Fixed
+- Console width returns default in piped/CI contexts instead of 0
+- `rvw failed` no longer crashes on empty tag objects
+- MIT license restored in LICENSE.txt
+- `--help` and `--version` exit immediately instead of running tool suite
+- Valid JSON emitted for early exits (no matching tools, no files)
+
+### Changed
+- **Ruby 3.2+ required** (supports 3.2, 3.3, 3.4, and 4.0)
+- Architecture refactor: full dependency injection, no global state in business logic
+- Output decomposed into domain formatters (Runner, Batch, Session, Doctor, Setup, Report)
+- Session class owns run lifecycle; Reviewer module is pure wiring
+- Context struct threads shared dependencies through the call stack
+- Tool timing extracted to Tool::Timing collaborator with injected history
+- Result interpretation separated from Runner execution (Result.from_runner)
+- Tests no longer depend on global state or require reset between runs
+- Redesigned output: compact `↳ command` format, `✓ ~Xs` checkmark summaries
+- ANSI color output guarded for TTY (clean output in CI and pipes)
+- README rewritten with installation, usage, configuration, and workflow documentation
+- `disabled` config key deprecated in favor of `skip_in_batch`
 
 ## [0.1.4] - 2021-07-08
 

data/LICENSE.txt

@@ -1,5 +1,21 @@
-Copyright (c) Garrett Dimon
+The MIT License (MIT)
 
-Reviewer is an Open Source project licensed under the terms of
-the LGPLv3 license. Please see <http://www.gnu.org/licenses/lgpl-3.0.html>
-for license text.
+Copyright (c) 2021 Garrett Dimon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -1,37 +1,89 @@
 # [Reviewer](https://github.com/garrettdimon/reviewer)
-by [Garrett Dimon](https://garrettdimon.com)
 
----
+Frictionless code quality.
 
-**Note:** As of December 2021, Reviewer is a work in progress. While it's working great reviewing its own code, it's not quite ready for wider usage. Once, it's ready, it will provide more helpful installation and usage details.
+[![build](https://github.com/garrettdimon/reviewer/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/garrettdimon/reviewer/actions/workflows/main.yml)
+[![coverage](https://img.shields.io/codecov/c/github/garrettdimon/reviewer?token=UuXUlQAA2e)](https://codecov.io/gh/garrettdimon/reviewer)
+[![gem version](https://img.shields.io/gem/v/reviewer)](https://rubygems.org/gems/reviewer)
+
+Reviewer wraps your code quality tools — tests, linters, security audits, formatters — into a single
+command with a consistent interface. Configure once, run everywhere.
 
----
+Reviewer works with any command-line tool but is built for Ruby projects. Doctor can inspect a
+project for known tool signals, and file mapping supports Minitest and RSpec conventions.
 
-*With Reviewer, you can seamlessly use multiple automated code review tools with orders of magnitude less friction so you can use them more frequently and consistently.*
+## Before & After
 
-So instead of remembering and typing...
-```bash
-$ yarn audit --level moderate
-$ bundle exec bundle-audit check --no-update
-$ bundle exec rubocop --parallel
-$ bundle exec erblint --lint-all --enable-all-linters
-$ yarn stylelint .
-$ yarn eslint .
+**Before** — five separate commands, each with their own flags:
+
+```console
+bundle exec bundle-audit check --no-update
+bundle exec rake test
+bundle exec rubocop --parallel
+bundle exec fasterer
+bundle exec reek lib/
 ```
-...you could just type...
+
+**After:**
+
+```console
+rvw
 ```
-$ rvw
+
+```text
+Bundle Audit Review Gem Dependencies for Security Issues
+ ↳ bundle exec bundle-audit check --no-update
+Success 0.8s
+
+Minitest Unit Tests & Coverage
+ ↳ bundle exec rake test
+Success 4.2s
+
+RuboCop Review Ruby Syntax & Formatting for Consistency
+ ↳ bundle exec rubocop --parallel
+Success 1.1s
+
+✓ ~6.1 seconds for 3 tools
 ```
 
-That's just the tip of the iceberg, though. For the full story on Reviewer's capabilities and benefits, the [Overview](https://github.com/garrettdimon/reviewer/wiki/Overview) is the best place to start. Or if you'd like to see how it's configured under the hood, the [Configuration Instructions](https://github.com/garrettdimon/reviewer/wiki/Configuration) go even deeper.
+## Install & Setup
 
-[![build](https://github.com/garrettdimon/reviewer/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/garrettdimon/reviewer/actions/workflows/main.yml)
-[![coverage](https://img.shields.io/codecov/c/github/garrettdimon/reviewer?token=UuXUlQAA2e)](https://codecov.io/gh/garrettdimon/reviewer)
-[![last commit](https://img.shields.io/github/last-commit/garrettdimon/reviewer/main)](https://github.com/garrettdimon/reviewer/commits/main)
-[![gem version](https://img.shields.io/gem/v/reviewer)](https://rubygems.org/gems/reviewer)
+Reviewer requires Ruby 3.2 or newer.
+
+```console
+gem install reviewer
+rvw doctor
+```
+
+Use Doctor's configured-tool inventory and project discoveries to write the commands the project
+owns in `.reviewer.yml`, then inspect and run them:
+
+```console
+rvw doctor
+rvw
+```
+
+Or add `gem 'reviewer'` to the project's `Gemfile` before running `bundle install`.
+
+See [Getting started](docs/getting-started.md) for the Doctor-guided setup workflow and first review.
+
+## Configuration
+
+See the [configuration reference](docs/configuration.md) for the supported `.reviewer.yml` schema,
+command composition, and file targeting.
+
+## Documentation
+
+- [Documentation index](docs/README.md)
+- [Usage](docs/usage.md)
+- [Recipes](docs/recipes.md)
+- [Contributing](docs/CONTRIBUTING.md)
+- [Ruby API reference](https://www.rubydoc.info/gems/reviewer)
 
 ## License
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+MIT License — see [LICENSE.txt](LICENSE.txt).
 
 ## Code of Conduct
-Everyone interacting in the Reviewer project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/reviewer/blob/master/CODE_OF_CONDUCT.md).
+
+See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).

data/docs/CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing to Reviewer
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/garrettdimon/reviewer).
+Participation in the project follows the [Code of Conduct](../CODE_OF_CONDUCT.md).
+
+## Project philosophy
+
+- Reduce the friction of running multiple code-quality tools.
+- Keep frequent reviews fast and their output focused.
+- Preserve a project's commands and configuration instead of imposing tool policy.
+- Make defaults simple while allowing each project to tune its workflow.
+- Run tools in a predictable order and stop after an actionable failure.
+- Report observations without turning Reviewer into a quality score.
+
+## Development setup
+
+This guide describes the [repository checkout](https://github.com/garrettdimon/reviewer), not the
+installed gem. The commands below run from a clone.
+
+Reviewer requires Ruby 3.2 or newer. Clone the repository, then install the development and dogfood
+dependencies:
+
+```console
+bin/setup
+```
+
+Use `bin/console` for an interactive Ruby session. Run the local executable with `exe/rvw` when
+exercising the CLI from the repository.
+
+## Tests
+
+Reviewer uses Minitest. Run only the test file covering the code you changed:
+
+```console
+bundle exec rvw tests -f test/reviewer/setup_test.rb
+```
+
+Write a failing test first, confirm the expected failure, make the minimum change, and rerun that
+focused file. Prefer the fixtures under `test/fixtures/` to factories or ad hoc configuration data.
+
+Before committing, use the repository's configured review gate on the staged changes:
+
+```console
+bundle exec rvw staged
+```
+
+## Pull requests
+
+Keep each pull request to one logical change. Explain why the change is needed, include the focused
+test evidence, and update user-facing documentation when behavior or configuration changes.
+
+Do not mix release preparation into a feature or fix. Maintainers release Reviewer using the
+[release guide](https://github.com/garrettdimon/reviewer/blob/main/RELEASING.md).
+
+## API documentation
+
+Public Ruby classes and methods are documented in the
+[Reviewer API reference](https://www.rubydoc.info/gems/reviewer).
+
+Return to the [documentation index](README.md).

data/docs/README.md

@@ -0,0 +1,20 @@
+# Reviewer documentation
+
+Reviewer runs a project's tests, linters, security audits, formatters, and other command-line review
+tools through one consistent interface. The project keeps its own commands in `.reviewer.yml`;
+Reviewer selects, composes, and runs them.
+
+## Start here
+
+- [Getting started](getting-started.md) — inspect the project, write a configuration, and run the
+  first review.
+- [Usage](usage.md) — select tools and files, format code, choose output, and use Reviewer in common
+  workflows.
+- [Configuration](configuration.md) — the complete `.reviewer.yml` reference and command-composition
+  rules.
+- [Recipes](recipes.md) — small configurations for common workflows.
+- [Contributing](CONTRIBUTING.md) — develop and contribute to Reviewer.
+
+For Ruby classes and methods, see the [Reviewer API reference](https://www.rubydoc.info/gems/reviewer).
+
+Return to the [project README](../README.md).

data/docs/configuration.md

@@ -0,0 +1,182 @@
+# Configuration
+
+Reviewer reads `.reviewer.yml` from the current directory. The file maps a tool key to its settings;
+only `commands.review` is required.
+
+```yaml
+rubocop:
+  commands:
+    review: bundle exec rubocop --parallel
+```
+
+Run that tool with `rvw rubocop`. Run every tool included in the default batch with `rvw`.
+
+## Tool order and selection
+
+Tools run in YAML order. Put checks that should stop the review near the beginning: Reviewer stops
+after the first executed failure, while a missing executable is reported and the batch continues.
+
+Set `skip_in_batch: true` to exclude a tool from bare `rvw` while keeping it available by an
+explicit tool key. Tags select enabled tools that share a configured category.
+
+```yaml
+brakeman:
+  name: Brakeman
+  description: Scan a Rails application for security issues
+  tags: [ruby, security]
+  skip_in_batch: true
+  commands:
+    review: bundle exec brakeman --no-pager -q
+```
+
+`disabled` is deprecated. Existing configurations still treat `disabled: true` as
+`skip_in_batch: true`, but `skip_in_batch` wins when both keys are present. Replace `disabled` when
+editing a configuration.
+
+## Commands
+
+```yaml
+bundle_audit:
+  commands:
+    install: bundle exec gem install bundler-audit
+    prepare: bundle exec bundle-audit update
+    review: bundle exec bundle-audit check --no-update
+    format: bundle exec bundle-audit update
+    max_exit_status: 0
+```
+
+| Setting | Behavior |
+|---|---|
+| `commands.review` | Required command used by `rvw` |
+| `commands.format` | Command used by `fmt`; tools without one are skipped during formatting |
+| `commands.prepare` | Runs before review or format at most once every six hours; failed attempts are cached too |
+| `commands.install` | Recovery hint that Reviewer may display; Reviewer does not execute it |
+| `commands.max_exit_status` | Highest review-command status considered successful; defaults to `0` |
+
+Commands in `.reviewer.yml` are shell strings owned by the project. Reviewer preserves each saved
+command as configured, then applies only the explicit composition settings below. `commands.install`
+is display-only: Reviewer has no installer and never executes it. Projects may replace or pin any
+saved command without changing Reviewer's behavior.
+
+## Command composition
+
+Reviewer builds an executable command in this order:
+
+1. Environment assignments from `env`.
+2. The selected base command.
+3. Configured `flags` for review commands.
+4. Resolved file arguments when file targeting applies.
+
+The base command is preserved as configured. With targeted files, `files.review` or `files.format`
+replaces the corresponding base command when present; Reviewer then appends the same configured flags
+and file arguments.
+
+```yaml
+tests:
+  commands:
+    review: bundle exec rake test
+  files:
+    review: bundle exec ruby -Itest -e 'ARGV.each { |file| require File.expand_path(file) }'
+    pattern: "*_test.rb"
+    map_to_tests: minitest
+```
+
+## File targeting
+
+```yaml
+rubocop:
+  commands:
+    review: bundle exec rubocop
+    format: bundle exec rubocop --autocorrect
+  files:
+    review: bundle exec rubocop
+    format: bundle exec rubocop --autocorrect
+    flag: ""
+    separator: " "
+    pattern: "*.rb"
+    map_to_tests: minitest
+```
+
+| Setting | Behavior |
+|---|---|
+| `files.review` | Replaces `commands.review` when files are targeted |
+| `files.format` | Replaces `commands.format` when files are targeted |
+| `files.flag` | Prefix before the resolved file list; empty means bare paths |
+| `files.separator` | Joins multiple shell-escaped paths; defaults to one space |
+| `files.pattern` | Keeps matching paths before the command runs |
+| `files.map_to_tests` | Maps Ruby source paths to existing `minitest` or `rspec` test paths |
+
+Only tools with a `files:` block receive resolved file arguments; tools without one run their
+configured command unchanged.
+
+Slashless patterns match each path's basename. Patterns containing `/` match normalized
+repository-relative paths with pathname semantics. In path patterns, `**/` crosses directory
+boundaries while bare `**` does not; brace alternatives such as `'{lib,test}/**/*.rb'` are
+supported. Source-to-test mapping runs before filtering, nonexistent resolved paths are omitted,
+and resolver output retains each matched path's original form. Reviewer shell-escapes each resolved
+path when appending it to the command.
+
+Source-to-test mapping recognizes Ruby files under `app/` and `lib/`, preserves matching test files,
+and omits mapped paths that do not exist.
+
+## Environment and flags
+
+```yaml
+tests:
+  commands:
+    review: bundle exec rake test
+  env:
+    testopts: --seed=$SEED
+  flags:
+    verbose:
+```
+
+Environment keys are uppercased and prepended as `KEY=value`. Values containing spaces are quoted.
+`$SEED` is replaced with a consistent random seed that `rvw failed` reuses.
+
+Flags apply only to review commands. A one-character key becomes a short flag such as `-v`; longer
+keys become long flags such as `--verbose`. Empty values produce a switch, and values containing
+spaces are quoted.
+
+## Links and failure guidance
+
+```yaml
+rubocop:
+  links:
+    home: https://rubocop.org
+    install: https://docs.rubocop.org/rubocop/installation.html
+    ignore_syntax: https://docs.rubocop.org/rubocop/configuration.html
+    disable_syntax: https://docs.rubocop.org/rubocop/configuration.html
+  commands:
+    review: bundle exec rubocop
+```
+
+`links.ignore_syntax` and `links.disable_syntax` may be shown after a review failure. Link values are
+informational and are never executed.
+
+## Summary details
+
+Summary output can extract a detail from captured standard output:
+
+```yaml
+tests:
+  commands:
+    review: bundle exec rake test
+  summary:
+    pattern: "(\\d+) tests?"
+    label: "\\1 tests"
+```
+
+`summary.pattern` is matched case-insensitively. `summary.label` is required when a pattern is
+configured; numbered captures such as `\\1` are replaced with values from the match.
+
+When extraction succeeds, `--format summary` prints the configured label after the tool's timing and
+`--json` includes it as `detail_summary` in that tool's result. The JSON key is absent when the
+configuration is incomplete or standard output does not match. This project-defined label is display
+text for consumers to surface, not a structured value to parse.
+
+## Complete example
+
+The repository's [example configuration](../.reviewer.example.yml) is the copyable reference for all
+supported settings. For task-oriented examples, see [recipes](recipes.md). Return to the
+[documentation index](README.md).