reviewer 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91c7ece2434c770297548056ba752092b0cc16427e0b94c35f58acb29efd304b
-  data.tar.gz: b303dd4164e6181f9bb8c583a6eb55836018c17e5361fadecdcd95efab09f3aa
+  metadata.gz: 8d918dfc0f53f9d2283d846207fc760f0aa0cafaa2d9db0f2225396935cdbd38
+  data.tar.gz: 2f8635ce31fee7646608c5dd591c277190e918b3c940b773d04731254c3ea707
 SHA512:
-  metadata.gz: 47aa07e5a1e72001bcaa3f3b95319c0ca8c110ce894e99b731300f948e38139f8d807235a0be17e894763031e87c3a0a1459e91713cb31c9388b5494df200b25
-  data.tar.gz: dcddd952084467bcfcd6ad1d09edd9b8eea87352bc8ef5aae6e0655c77349cc99f6def176c65f7bfe1936f2371251e8a183e345e85a45d6dc95764415efea2a1
+  metadata.gz: fc770176795e88d1c88e56903eb1ce3d756f0f46176edc1d1a280bff14069b0739a27a4aefa6ca04313c08f1324e3f9d45da86860c9563c97f7a82472005f7ca
+  data.tar.gz: dbfdb47cbc0c321bc2338251b4a16242d976d4b6fb893019e7dc5578d875bfc85ef4124297864fa50cbe52cf7189471e6fc2ece940e114cf92fe8ab0e429e369

data/.reviewer.example.yml

@@ -1,43 +1,38 @@
-# 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.
-#  skip_in_batch: true           // Optional. Tools run in batch by default. Set to true to only run when explicitly named.
-#  disabled: true               // Deprecated. Use skip_in_batch instead. Still supported as fallback.
-#  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.
-#    pattern:                   // Optional. Glob pattern to filter files (e.g., '*.rb'). Only files matching this pattern are passed to the tool.
-#    map_to_tests:              // Optional. Maps source files to test files. Values: 'minitest' (test/*_test.rb) or 'rspec' (spec/*_spec.rb).
-#  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:
   skip_in_batch: true
   name: Tool
@@ -49,20 +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: '*.rb'
+    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,5 +1,44 @@
 ## [Unreleased]
 
+## [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

data/README.md

@@ -6,15 +6,17 @@ Frictionless code quality.
 [![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 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. Auto-setup detects tools from `Gemfile.lock`, and file mapping supports Minitest and RSpec conventions.
+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.
 
 ## Before & After
 
 **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
@@ -24,11 +26,11 @@ bundle exec reek lib/
 
 **After:**
 
-```
+```console
 rvw
 ```
 
-```
+```text
 Bundle Audit Review Gem Dependencies for Security Issues
  ↳ bundle exec bundle-audit check --no-update
 Success 0.8s
@@ -46,281 +48,42 @@ Success 1.1s
 
 ## Install & Setup
 
-```bash
-gem install reviewer
-```
-
-Or add to your Gemfile:
+Reviewer requires Ruby 3.2 or newer.
 
-```ruby
-gem 'reviewer'
-```
-
-**Requires Ruby 3.2+**
-
-Then auto-generate `.reviewer.yml` from your `Gemfile.lock`:
-
-```bash
-rvw init
-```
-
-```
-Created .reviewer.yml
-
-Detected tools:
-  Bundle Audit            bundler-audit in Gemfile.lock
-  RuboCop                 rubocop in Gemfile.lock, .rubocop.yml
-  Minitest                minitest in Gemfile.lock, test/ directory
-
-Configure further:    https://github.com/garrettdimon/reviewer#configuration
-Run `rvw` to review your code.
+```console
+gem install reviewer
+rvw doctor
 ```
 
-Now run it:
+Use Doctor's configured-tool inventory and project discoveries to write the commands the project
+owns in `.reviewer.yml`, then inspect and run them:
 
-```bash
+```console
+rvw doctor
 rvw
 ```
 
-## Usage
-
-### Run a single tool without remembering its flags
-
-```bash
-rvw rubocop
-```
-
-Instead of `bundle exec rubocop --parallel`, use the YAML key. Reviewer applies your configured flags and options automatically.
-
-### Run a subset of tools by tag
-
-```bash
-rvw security
-```
-
-Instead of maintaining lists of which tools to run in which context, tag them in `.reviewer.yml` and filter on the fly:
-
-```
-rvw security ─── bundle-audit check --no-update
-             └── brakeman --no-pager -q
-```
-
-Tags work as positional args or with `-t ruby`. Tag ideas: language (`ruby`, `css`), purpose (`security`, `syntax`), speed (`fast`, `slow`), context (`ci`, `pr`).
+Or add `gem 'reviewer'` to the project's `Gemfile` before running `bundle install`.
 
-### Review only staged files
-
-```bash
-rvw staged
-```
-
-Instead of figuring out each tool's syntax for targeting files, use a keyword. Reviewer resolves git status, filters by each tool's file pattern, maps source files to test files, and applies each tool's file-passing syntax:
-
-```
-rvw staged ─── rubocop lib/reviewer.rb lib/reviewer/batch.rb
-           ├── rake test TEST=test/reviewer_test.rb test/reviewer/batch_test.rb
-           └── fasterer lib/reviewer.rb lib/reviewer/batch.rb
-```
-
-One command. Three tools. Each gets only its relevant files in its expected format.
-
-Also: `unstaged`, `modified`, `untracked`.
-
-### Target specific files
-
-```bash
-rvw -f app/models/user.rb,test/models/user_test.rb
-```
-
-Pass files once. Reviewer handles whether the tool expects a flag, a bare path, or something else.
-
-### Re-run only what failed
-
-```bash
-rvw failed
-```
-
-Reviewer tracks which tools failed. Fix the issue, re-run only those.
-
-### Combine everything
-
-```bash
-rvw rubocop staged
-rvw -t ruby modified
-rvw tests -f test/models/user_test.rb
-```
-
-Tools, tags, keywords, and files compose naturally.
-
-### Auto-fix with formatters
-
-```bash
-fmt
-fmt rubocop staged
-```
-
-Same interface as `rvw`, but runs the `format` command for each tool. Only tools with a `format` command configured will run.
-
-### Output formats
-
-| Flag | Format | Use case |
-|------|--------|----------|
-| _(default)_ | Streaming | Development — see output as it runs |
-| `--format summary` | Summary | Quick pass/fail with timing per tool |
-| `-j` / `--json` | JSON | CI, scripting, agent integration |
-| `-r` / `--raw` | Raw | Force direct output, no capturing |
+See [Getting started](docs/getting-started.md) for the Doctor-guided setup workflow and first review.
 
 ## Configuration
 
-### Minimal example
-
-The only requirement is a `review` command:
-
-```yaml
-rubocop:
-  commands:
-    review: bundle exec rubocop --parallel
-```
-
-### Full example
-
-```yaml
-rubocop:
-  name: RuboCop
-  description: Review Ruby syntax and formatting for consistency
-  tags: [ruby, syntax]
-  commands:
-    install: bundle exec gem install rubocop
-    prepare: bundle exec rubocop --regenerate-todo
-    review: bundle exec rubocop --parallel
-    format: bundle exec rubocop --auto-correct
-  files:
-    flag: ""
-    separator: " "
-    pattern: "*.rb"
-    map_to_tests: minitest
-  links:
-    home: https://rubocop.org
-    install: https://docs.rubocop.org/rubocop/installation.html
-  env:
-    RUBOCOP_OPTS: --color
-  flags:
-    color:
-```
-
-### Options reference
-
-| Option | Description |
-|--------|-------------|
-| `name` | Display name |
-| `description` | What the tool does |
-| `tags` | Categories for filtering (`[ruby, security]`) |
-| `skip_in_batch` | Set `true` to exclude from `rvw` but still run with `rvw tool_name` |
-| `commands.review` | Command to run for `rvw` **(required)** |
-| `commands.format` | Command to run for `fmt` |
-| `commands.install` | Command to install the tool |
-| `commands.prepare` | Command to run before review (cached 6 hours) |
-| `commands.max_exit_status` | Treat exit codes up to this value as success |
-| `files.review` | Command to use instead of `commands.review` when files are scoped |
-| `files.format` | Command to use instead of `commands.format` when files are scoped |
-| `files.flag` | CLI flag for passing files (empty string = bare paths) |
-| `files.separator` | How to join multiple file paths (default: space) |
-| `files.pattern` | Glob pattern to filter files (e.g., `*.rb`) |
-| `files.map_to_tests` | Map source files to test files (`minitest` or `rspec`) |
-| `links.home` | Project homepage |
-| `links.install` | Installation instructions |
-| `env` | Environment variables to set when running |
-| `flags` | CLI flags to append to the review command |
-
-### File-scoped commands
-
-Some tools use different commands for running the full suite vs. targeting specific files. Use `files.review` (or `files.format`) to specify an alternative command when files are passed:
-
-```yaml
-tests:
-  commands:
-    review: bundle exec rake test
-  files:
-    review: bundle exec ruby -Itest
-    pattern: "*_test.rb"
-    map_to_tests: minitest
-```
-
-`rvw` runs `bundle exec rake test` (full suite). `rvw staged` or `rvw tests -f test/models/user_test.rb` runs `bundle exec ruby -Itest` with the resolved files appended. The standard `files.flag` and `files.separator` still apply when appending files to the file-scoped command.
-
-### Notes
-
-- **Tool ordering** — Tools run in the order they appear in `.reviewer.yml`. Put fast tools first for quicker feedback.
-- **Environment variables** — Use `env` for things like `TESTOPTS: --seed=$SEED`. The `$SEED` placeholder is replaced with a consistent random seed across runs.
-- **Flags** — Keys with no value become boolean flags (`color:` becomes `--color`). Keys with values become `--key value`.
-- **Prepare caching** — The `prepare` command only runs if it hasn't been run in the last 6 hours, saving time on commands like `bundle-audit update`.
-
-## Workflows
-
-### Pre-commit
-
-Review only what you're about to commit:
-
-```bash
-rvw staged
-```
-
-### Pull request
+See the [configuration reference](docs/configuration.md) for the supported `.reviewer.yml` schema,
+command composition, and file targeting.
 
-Review everything that changed:
-
-```bash
-rvw modified
-```
-
-### CI
-
-Full review with JSON output for parsing:
-
-```bash
-rvw --json
-```
-
-Reviewer exits `0` when all tools pass, or with the highest exit status from any failing tool. Skipped and missing tools don't affect the exit code. This means `rvw` works directly as a CI gate — no wrapper script needed.
-
-### Development
-
-Run the full suite:
-
-```bash
-rvw
-```
-
-### Hotfix
-
-Run just security and tests on changed files:
-
-```bash
-rvw -t security modified
-rvw tests modified
-```
-
-### After a failure
-
-Fix the issue, then re-run only what failed:
-
-```bash
-rvw failed
-```
-
-## Agent Integration
-
-For AI agents and automation tools, use `--capabilities` to discover available tools:
-
-```bash
-rvw --capabilities
-```
+## Documentation
 
-This outputs JSON describing all configured tools, keywords, and common scenarios.
+- [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
 
-MIT License — see [LICENSE.txt](LICENSE.txt)
+MIT License — see [LICENSE.txt](LICENSE.txt).
 
 ## Code of Conduct
 
-See [CODE_OF_CONDUCT.md](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).