reviewer 0.1.5 → 1.0.0

data/README.md

@@ -1,37 +1,326 @@
 # [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. Auto-setup detects tools from `Gemfile.lock`, and file mapping supports Minitest and RSpec conventions.
+
+## Before & After
+
+**Before** — five separate commands, each with their own flags:
+
+```
+bundle exec bundle-audit check --no-update
+bundle exec rake test
+bundle exec rubocop --parallel
+bundle exec fasterer
+bundle exec reek lib/
+```
 
----
+**After:**
 
-*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.*
+```
+rvw
+```
+
+```
+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
+```
+
+## Install & Setup
 
-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 .
+gem install reviewer
 ```
-...you could just type...
+
+Or add to your Gemfile:
+
+```ruby
+gem 'reviewer'
 ```
-$ rvw
+
+**Requires Ruby 3.2+**
+
+Then auto-generate `.reviewer.yml` from your `Gemfile.lock`:
+
+```bash
+rvw init
 ```
 
-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.
+```
+Created .reviewer.yml
 
-[![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)
+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.
+```
+
+Now run it:
+
+```bash
+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`).
+
+### 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 |
+
+## 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
+
+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
+```
+
+This outputs JSON describing all configured tools, keywords, and common scenarios.
 
 ## 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/RELEASING.md

@@ -0,0 +1,190 @@
+# Releasing Reviewer
+
+## Quick Reference
+
+```bash
+# 1. Update version and changelog
+# 2. Commit and push
+git add -A && git commit -m "Release vX.Y.Z" && git push
+
+# 3. Tag and push
+git tag vX.Y.Z && git push origin vX.Y.Z
+
+# Done - automation handles the rest
+```
+
+## How It Works
+
+Releases are fully automated via GitHub Actions:
+
+1. **Branch protection** requires CI to pass before merging to `main`
+2. When you push a version tag, the release workflow:
+   - Validates the tag points to a commit on `main` (ensures CI passed)
+   - Builds and publishes the gem to RubyGems
+   - Creates a GitHub Release with changelog excerpt
+
+No redundant test runs. If it's on `main`, it already passed CI.
+
+## Release Steps
+
+### 1. Update Version
+
+Edit `lib/reviewer/version.rb`:
+
+```ruby
+VERSION = 'X.Y.Z'
+```
+
+### 2. Update CHANGELOG
+
+Move items from `[Unreleased]` to a new version section:
+
+```markdown
+## [Unreleased]
+
+## [X.Y.Z] - YYYY-MM-DD
+
+### Added
+- New feature description
+
+### Fixed
+- Bug fix description
+```
+
+### 3. Commit, Tag, Push
+
+```bash
+git add lib/reviewer/version.rb CHANGELOG.md
+git commit -m "Release vX.Y.Z"
+git push origin main
+git tag vX.Y.Z
+git push origin vX.Y.Z
+```
+
+### 4. Verify
+
+- Watch the [Actions tab](https://github.com/garrettdimon/reviewer/actions) for workflow completion
+- Check [RubyGems](https://rubygems.org/gems/reviewer) for the new version
+- Check [GitHub Releases](https://github.com/garrettdimon/reviewer/releases) for the release page
+
+## Versioning Policy
+
+Follow [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** (x.0.0): Breaking changes to public API or configuration
+- **MINOR** (0.x.0): New features, deprecations
+- **PATCH** (0.0.x): Bug fixes, documentation
+
+### What's a Breaking Change?
+
+- Removing or renaming public classes/methods
+- Changing method signatures incompatibly
+- Changing default configuration behavior
+- Dropping Ruby version support
+
+## Local Tools
+
+### Full Preflight Check
+
+Run all checks before pushing:
+
+```bash
+bundle exec rake release:preflight
+```
+
+This runs tests, security audit, and release validation in sequence.
+
+### Individual Tasks
+
+| Task | Purpose |
+|------|---------|
+| `rake release:preflight` | Run all checks (test, audit, check) |
+| `rake release:check` | Validate version format, changelog entry, git state |
+| `rake release:audit` | Check for vulnerable dependencies |
+| `rake release:dry_run` | Build gem locally, show contents and size |
+| `rake test` | Run test suite |
+
+### Preview a Release
+
+Before tagging, preview what the gem will contain:
+
+```bash
+bundle exec rake release:dry_run
+```
+
+This builds the gem, displays its contents and size, then cleans up.
+
+## One-Time Setup
+
+### RubyGems Trusted Publishing
+
+1. Go to [rubygems.org/profile/oidc/pending_trusted_publishers](https://rubygems.org/profile/oidc/pending_trusted_publishers)
+2. Add trusted publisher:
+   - **Gem name:** `reviewer`
+   - **Repository owner:** `garrettdimon`
+   - **Repository name:** `reviewer`
+   - **Workflow filename:** `release.yml`
+   - **Environment:** `rubygems`
+
+### GitHub Environment
+
+1. Go to repository Settings > Environments
+2. Create environment named `rubygems`
+3. (Optional) Add required reviewers for extra safety
+
+### Repository Ruleset
+
+1. Go to repository Settings > Rules > Rulesets
+2. Edit the `main` ruleset (or create one targeting the default branch)
+3. Enable "Require status checks to pass" with these checks:
+   - `Security`
+   - `Test (Ruby 3.2)`
+   - `Test (Ruby 3.3)`
+   - `Test (Ruby 3.4)`
+   - `Test (Ruby 4.0)`
+   - `Changelog`
+   - `Version`
+
+## Troubleshooting
+
+### Release workflow fails with "must point to commit on main"
+
+You tagged a commit that isn't on the main branch. Delete the tag and re-tag a commit on main:
+
+```bash
+git tag -d vX.Y.Z              # Delete local tag
+git push origin :vX.Y.Z        # Delete remote tag
+git checkout main
+git pull
+git tag vX.Y.Z
+git push origin vX.Y.Z
+```
+
+### "You do not have permission to push to this gem"
+
+The RubyGems trusted publisher isn't configured, or the environment name doesn't match. Check the one-time setup steps above.
+
+### Forgot to update CHANGELOG
+
+Delete the tag, update CHANGELOG, amend the commit, re-tag:
+
+```bash
+git tag -d vX.Y.Z
+git push origin :vX.Y.Z
+# Update CHANGELOG.md
+git add CHANGELOG.md
+git commit --amend --no-edit
+git push --force-with-lease origin main
+git tag vX.Y.Z
+git push origin vX.Y.Z
+```
+
+## Manual Release (Fallback)
+
+If automation fails and you need to publish manually:
+
+```bash
+bundle exec rake release
+```
+
+This builds the gem and pushes to RubyGems using your local credentials.

data/Rakefile

@@ -10,3 +10,120 @@ Rake::TestTask.new(:test) do |t|
 end
 
 task default: :test
+
+# rubocop:disable Metrics/BlockLength
+namespace :release do
+  desc 'Run bundle-audit to check for vulnerable dependencies'
+  task :audit do
+    puts 'Running security audit...'
+    sh 'bundle exec bundle-audit check --update'
+  end
+
+  desc 'Validate version, changelog, and git state before release'
+  task :check do
+    require_relative 'lib/reviewer/version'
+    errors = ReleaseChecker.new(Reviewer::VERSION).validate
+    if errors.any?
+      puts "\nRelease check failed:"
+      errors.each { |e| puts "  - #{e}" }
+      exit 1
+    else
+      puts 'All release checks passed.'
+    end
+  end
+
+  desc 'Run all pre-release checks (tests, audit, release:check)'
+  task preflight: %i[test audit check] do
+    puts "\nAll preflight checks passed. Ready to release."
+  end
+
+  desc 'Build gem locally and show contents (dry run)'
+  task :dry_run do
+    require_relative 'lib/reviewer/version'
+    DryRun.new(Reviewer::VERSION).run
+  end
+end
+# rubocop:enable Metrics/BlockLength
+
+# Validates release readiness
+class ReleaseChecker
+  def initialize(version)
+    @version = version
+    @errors = []
+  end
+
+  def validate
+    puts "Checking release readiness for v#{@version}..."
+    check_version_format
+    check_changelog
+    check_git_clean
+    check_main_branch
+    @errors
+  end
+
+  private
+
+  def check_version_format
+    return if @version.match?(/\A\d+\.\d+\.\d+\z/)
+
+    @errors << "Version '#{@version}' is not valid semver (expected X.Y.Z)"
+  end
+
+  def check_changelog
+    changelog = File.read('CHANGELOG.md')
+    return if changelog.include?("[#{@version}]")
+
+    @errors << "CHANGELOG.md has no entry for version #{@version}"
+  end
+
+  def check_git_clean
+    return if `git status --porcelain`.empty?
+
+    @errors << 'Working directory has uncommitted changes'
+  end
+
+  def check_main_branch
+    current_branch = `git branch --show-current`.strip
+    return if current_branch == 'main'
+
+    @errors << "Not on main branch (currently on '#{current_branch}')"
+  end
+end
+
+# Builds gem and displays contents without publishing
+class DryRun
+  def initialize(version)
+    @version = version
+    @gem_file = "reviewer-#{version}.gem"
+  end
+
+  def run
+    build || abort('Gem build failed')
+    show_contents
+    show_size
+  ensure
+    cleanup if File.exist?(@gem_file)
+  end
+
+  private
+
+  def build
+    puts "Building #{@gem_file}..."
+    system 'gem build reviewer.gemspec --silent'
+  end
+
+  def show_contents
+    puts "\nGem contents:"
+    system "tar -tf #{@gem_file}"
+  end
+
+  def show_size
+    size = File.size(@gem_file)
+    puts "\nGem size: #{(size / 1024.0).round(1)} KB"
+  end
+
+  def cleanup
+    File.delete(@gem_file)
+    puts "Cleaned up #{@gem_file}"
+  end
+end

data/dependency_decisions.yml

@@ -0,0 +1,61 @@
+---
+- - :permit
+  - MIT
+  - :who:
+    :why: Standard permissive license
+    :versions: []
+    :when: 2025-12-22 19:15:00.637887000 Z
+- - :permit
+  - Apache 2.0
+  - :who:
+    :why: Standard permissive license
+    :versions: []
+    :when: 2025-12-22 19:15:01.182813000 Z
+- - :permit
+  - Simplified BSD
+  - :who:
+    :why: Standard permissive license
+    :versions: []
+    :when: 2025-12-22 19:15:01.670547000 Z
+- - :permit
+  - Simplified BSD, ruby
+  - :who:
+    :why: Ruby standard library license
+    :versions: []
+    :when: 2025-12-22 19:15:02.138662000 Z
+- - :permit
+  - ruby
+  - :who:
+    :why: Ruby license
+    :versions: []
+    :when: 2025-12-22 19:15:02.611904000 Z
+- - :permit
+  - same as ruby's
+  - :who:
+    :why: Ruby license variant
+    :versions: []
+    :when: 2025-12-22 19:15:03.091953000 Z
+- - :permit
+  - ISC
+  - :who:
+    :why: Standard permissive license
+    :versions: []
+    :when: 2025-12-22 19:15:03.570618000 Z
+- - :permit
+  - BSD
+  - :who:
+    :why: Standard permissive license
+    :versions: []
+    :when: 2025-12-22 19:15:04.055284000 Z
+- - :permit
+  - GPL-3.0-or-later
+  - :who:
+    :why: Acceptable for development tools
+    :versions: []
+    :when: 2025-12-22 19:15:12.998894000 Z
+- - :approve
+  - brakeman
+  - :who:
+    :why: Development-only security scanner with custom license
+    :versions: []
+    :when: 2025-12-22 19:15:13.454537000 Z