reviewer 0.1.4 → 1.0.0

data/.reviewer.future.yml

@@ -0,0 +1,221 @@
+# This represents the long-term vision for reviewer. It's a sort of documentation-driven design, but
+#  it's also heavily based on the initial exploration and iteration to determine what's possible and
+#  what's practical based on testing out a variety of command types and structures.
+
+# Options for `rvw` command
+# -c <file>, --config=<file>
+# -f <file>,<file>..., --files=<file>,<file>...
+# -t <tag>,<tag>..., --tags=<tag>,<tag>...
+# -l <tool_key>,<tool_key>..., --tools=<tool_key>,<tool_key>...
+# -c <command>, --command=<command>
+# -k, --keywords
+# -s, --settings
+# -h, --help
+# -v, --version
+# <keyword>
+
+# Implicit Keywords:
+# - every <tag>
+# - every <tool_key>
+#   - <tool_key>:settings
+#   - <tool_key>:links
+#   - every <tool_key>:<link>
+#   - <tool_key>:commands
+#   - every <tool_key>:<command>
+
+# Reserved Keywords:
+# - every link type
+# - every command type
+# - staged               // currently staged git files
+# - untracked            // currently untracked git files
+# - fresh                // untracked files updated in last 5 minutes
+#   - fresh_15           //                             ... 15 minutes
+#   - fresh_30           //                             ... 30 minutes
+#   - fresh_60           //                             ... 60 minutes
+# - stale                // untracked files updated more than 5 minutes ago
+#   - stale_15           //                               ... 15 minutes
+#   - stale_30           //                               ... 30 minutes
+#   - stale_60           //                               ... 60 minutes
+# - branch|diff          // All files created or updated on the current branch
+# - last_commit          // All files created or updated in the last commit
+# - current              // alias for branch or diff?
+
+# Command Examples:
+
+# The Basics
+# - rvw           // runs :review command for all enabled tools
+# - rvw <command> // runs <command> for all enabled tools (not disabled or solo)
+# - rvw <keyword> // runs :review command for all enabled tools and translates the <keyword>
+# - rvw <tag>     // runs :review command for all enabled tools tagged with <tag>
+
+# Tools
+# - rvw <tool_key>           // shortcut for `rvw <tool_key>:review`
+# - rvw <tool_key>:<command> // runs <command> for <tool_key> in passthrough mode
+# - rvw <tool_key>:<link>    // opens the <link> via `open <link>` if present, otherwise, shares that it's not configured
+# - rvw <tool_key>:settings  // displays all settings for <tool_key>
+# - rvw <tool_key>:commands  // displays all configured commands for <tool_key>
+# - rvw <tool_key>:links     // displays all configured links for <tool_key>
+
+# Combos
+# - rvw <keyword> <tag>                          // ex. `rvw staged ruby` -> `rvw review staged ruby`
+# - rvw <command> <tag>                          // ex. `rvw format ruby` -> `rvw format ruby`
+# - rvw <command> <reserved_keyword>             // ex. `rvw install ruby`
+# - rvw <command> <reserved_keyword> <tag>       // ex. `rvw format last_commit ruby`
+# - rvw <command> <reserved_keyword> <tag> <tag> // ex. `rvw format last_commit ruby erb`
+
+reviewer:
+  # Whether to run tools consecutively or in parallel if available
+  # :linear - It would suck if your first command is `bundle audit` and fails but 6 other tools
+  #   are running in parallel but will take time to fail. So :linear with :stop as the behavior
+  #   ensures you don't attepmt commands.
+  # :parallel - Reviewer will attempt to run commands on multiple threads/processors for more speed.
+  #   Best used when groups of commands are not dependent on each other.
+  default_batch_mode: <:linear|:safe, :parallel|:fast>
+
+  # Fallback failure behavior for all commands where it isn't explicitly defined. Applies to
+  #   linear runs independent of each other. So if you have two batches (ex. ruby, javascript), and
+  #   one batch fails immediately, the remaining commands willn ot be run. But the other batch will
+  #   safely continue independently.
+  # Optional. Defaults to :fast.
+  # :stop - Don't run any additional commands in that batch.
+  # :continue - Keep running the other commands.
+  default_command_failure_behavior_in_batch: <:stop, :continue>
+
+  # Fallback install behavior for all commands where it isn't explicitly defined.
+  # Maybe if the install command is present, `:auto` is implied?
+  # Optional. Defaults to :guidance.
+  # - :guidance shows the installation command and/or link for manual installation.
+  # - :auto attempts to automatically install if the command is missing
+  # - :skip quietly moves on without worrying about it
+  default_install_behavior: <:guidance, :auto, :skip>
+
+  # Fallback behavior for displaying results.
+  # Optional. Defaults to :full
+  # - :full - Re-run the command directly so you see the full output
+  # - :fast - Show the results, but potentially lose colorizing and some formatting
+  default_results_behavior: <:full, :fast, :timer>
+
+  # Fallback definition for determining whether a command is slow.
+  # Only used if :default_results_behavior is :timer
+  # Optional. Defaults to 10 seconds
+  default_slow_window: <integer seconds>
+
+  # Fallback defintion for determining whether a command needs to be prepped again.
+  # Optional. Defaults to 6 hours
+  default_prep_window: <integer hours>
+
+  # Primarily for debugging/improving performance of reviewer. But if low-level performance info is
+  #   interesting, it can be enabled.
+  # Optional. Defaults to :min
+  # :min - Shows simply the total time for each command. Breaks out install/prep % if relevant.
+  timer_detail: <:min, :max>
+
+# Custom-defined keywords for shortcuts
+keywords:
+  # Compact version
+  mgc:   'format last_commit ruby erb'
+  # Long-form version of `mgc` (a little more self-documenting and explicit)
+  magic: '--command=format --keywords=last_commit --tags=ruby,erb'
+  # Long-form of `mgc` (most self-documentating and explicit)
+  magic:
+    - '--command=format'
+    - '--keywords=last_commit'
+    - '--tags=ruby,erb'
+
+# The real core of the configuration for each individual tool.
+tools:
+  <tool_key>: # Required. ex. 'rubocop', 'bundler-audit', etc.
+    status: <:enabled, :disabled, :solo> # Optional. Tools are enabled by default
+    name: # Optional. Defaults to <tool_key> capitalized
+    description: # Optional. Remind folks of the specific task this tool performs.
+    tags: [one, two, three] # Optional. For running groups of commands.
+    batch: # Optional. Only used if run in batch mode. ex. Run ruby commands on one thread and yarn commands on another.
+    install_behavior: <:auto, :guidance> # Optional. Defaults to Reviewer default.
+    failure_behavior: <:continue, :fast, :informative> # Optional
+    links:
+      home:
+      repo:
+      support:
+      install:
+      usage:
+      options:
+      syntax:
+      ignore:
+      disable:
+    files_syntax:
+      flag:
+      separator:
+      quotes:
+    shared_options: # Optional. Used for all commands.
+      prefix: 'bundle exec'
+      stale: <hours>
+      base: '<command>'
+      quiet: '--quiet'
+      max_exit_status:
+      flags:
+        <flag>: '<value>'
+      env:
+        <env_var>: '<value>'
+      raw:
+        - '<value>'
+    commands:
+      install:
+        desc:
+        stale:
+        prefix:
+        base:
+        quiet:
+        max_exit_status:
+        flags:
+        env:
+        raw:
+      prepare:
+        desc:
+        stale:
+        prefix:
+        base:
+        quiet:
+        max_exit_status:
+        flags:
+        env:
+        raw:
+      review:
+        desc:
+        stale:
+        prefix:
+        base:
+        quiet:
+        max_exit_status:
+        flags:
+        env:
+        raw:
+      format:
+        desc:
+        stale:
+        prefix:
+        base:
+        quiet:
+        max_exit_status:
+        flags:
+        env:
+        raw:
+      serve:
+        desc:
+        stale:
+        prefix:
+        base:
+        quiet:
+        max_exit_status:
+        flags:
+        env:
+        raw:
+      generate:
+        desc:
+        stale:
+        prefix:
+        base:
+        quiet:
+        max_exit_status:
+        flags:
+        env:
+        raw:

data/.reviewer.yml

@@ -1,33 +1,42 @@
 bundle_audit:
   name: Bundle Audit
   description: Review Gem Dependencies for Security Issues
-  tags: [critical, dependencies, ruby, dev]
+  tags: [critical, security, dependencies, ruby, dev]
   links:
     home: https://github.com/rubysec/bundler-audit
     install: https://github.com/rubysec/bundler-audit#install
   commands:
-    install: 'bundle exec gem install bundler-audit'
-    prepare: 'bundle exec bundle-audit update'
-    review: 'bundle exec bundle-audit check --no-update'
-    quiet_option: '--quiet'
+    install: "bundle exec gem install bundler-audit"
+    prepare: "bundle exec bundle-audit update"
+    review: "bundle exec bundle-audit check --no-update"
 
 tests:
   name: Minitest
   description: Unit Tests & Coverage
   tags: [ruby, tests, dev]
+  summary:
+    pattern: '(\d+)\s+tests?'
+    label: '\1 tests'
   links:
     home:
   commands:
-    review: "bundle exec rake TESTOPTS='--seed=$SEED'"
-    quiet_option: '--silent'
+    review: "bundle exec rake"
+  files:
+    review: "bundle exec ruby -Itest"
+    flag: ""
+    separator: " "
+    pattern: "*_test.rb"
+    map_to_tests: "minitest"
   reports:
     open_on_fail: true
     local_file: coverage/index.html
-    local_uri: 'file:///Users/garrettdimon/Code/reviewer/coverage/index.html#_AllFiles'
+    local_uri: "file:///Users/garrettdimon/Code/reviewer/coverage/index.html#_AllFiles"
   env:
-    coverage: true
+    testopts: --seed=$SEED
+    # coverage: false
 
 reek:
+  # skip_in_batch: true # Reek provides guidance and is generally run solo
   name: Reek
   description: Examine Ruby Classes for Code Smells
   tags: [ruby, quality, dev]
@@ -35,14 +44,18 @@ reek:
     home: https://github.com/troessner/reek
     install: https://github.com/troessner/reek#quickstart
   commands:
-    install: 'bundle exec gem install reek'
-    review: 'bundle exec reek'
+    install: "bundle exec gem install reek"
+    review: "bundle exec reek --config .reek.yml lib/"
+  files:
+    flag: ""
+    separator: " "
+    pattern: "*.rb"
   flags:
     color:
     documentation:
 
 flog:
-  disabled: true # Flog provides guidance and is generally run solo
+  # skip_in_batch: true # Flog provides guidance and is generally run solo
   name: Flog
   description: Reports your most tortured ruby code in an easy to read pain report.
   tags: [ruby, quality, dev]
@@ -50,15 +63,15 @@ flog:
     home: https://ruby.sadi.st/Flog.html
     install: https://ruby.sadi.st/Flog.html
   commands:
-    install: 'bundle exec gem install flog'
-    review: 'bundle exec flog -g lib'
+    install: "bundle exec gem install flog"
+    review: "bundle exec flog -g lib"
   flags:
     threshold: 10 # Percentage. i.e. Show the most concerning 10% of results
     group:
     methods-only:
 
 flay:
-  disabled: true # Flay provides guidance and is generally run solo
+  # skip_in_batch: true # Flay provides guidance and is generally run solo
   name: Flay
   description: Review ruby code for structural similarities and refactoring opportunities.
   tags: [ruby, quality, dev]
@@ -66,38 +79,188 @@ flay:
     home: https://ruby.sadi.st/Flay.html
     install: https://ruby.sadi.st/Flay.html
   commands:
-    install: 'bundle exec gem install flay'
-    review: 'bundle exec flay ./lib'
+    install: "bundle exec gem install flay"
+    review: "bundle exec flay ./lib"
   flags:
     liberal:
     summary:
 
-
 rubocop:
   name: Rubocop
   description: Review Ruby Syntax & Formatting for Consistency
-  tags: [ruby, syntax]
+  tags: [ruby, syntax, dev]
+  summary:
+    pattern: '(\d+)\s+offenses?'
+    label: '\1 offenses'
   links:
     home: https://rubocop.org
     install: https://docs.rubocop.org/rubocop/1.13/installation.html
     ignore_syntax: https://docs.rubocop.org/rubocop/configuration.html#ignoredmethods
     disable_syntax: https://docs.rubocop.org/rubocop/configuration.html#disabling-cops-within-source-code
   commands:
-    install: 'bundle exec gem install rubocop'
-    review: 'bundle exec rubocop --parallel'
-    format: 'bundle exec rubocop --auto-correct'
-    quiet_option: '--format q'
-    files_flag: ''
-    files_list_separator: ' '
+    install: "bundle exec gem install rubocop"
+    review: "bundle exec rubocop --parallel"
+    format: "bundle exec rubocop --auto-correct"
+  files:
+    flag: ""
+    separator: " "
+    pattern: "*.rb"
   flags:
     color:
 
+# The YARD Parser can also come in handy:
+#   https://yardoc.org/types
 inch:
+  # skip_in_batch: true
   tags: [docs, ruby, dev]
   name: Inch
-  description: Review Ruby Documentation
+  description: Review Ruby Documentation Quality
   links:
     home: https://rrrene.org/inch/
+    usage: https://www.rubydoc.info/gems/yard/file/docs/Tags.md
+  commands:
+    install: "bundle exec gem install inch"
+    review: "bundle exec inch"
+
+yard:
+  # skip_in_batch: true
+  tags: [docs, ruby, dev]
+  name: Yard
+  description: Generates Documentation
+  links:
+    home: https://yardoc.org
+    usage: https://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md#using
+    install: https://github.com/lsegal/yard#installing
+  commands:
+    install: "bundle exec gem install yard"
+    prepare: "yard doc 'lib/**/*.rb'"
+    review: "yard stats"
+    serve: "yard server --reload && open http://0.0.0.0:8808"
+    generate:
+    quiet_flag: "--quiet"
+
+alex:
+  skip_in_batch: true
+  tags: [language, docs]
+  name: Alex
+  description: Catch insensitive, inconsiderate writing
+  links:
+    home: https://alexjs.com
+  commands:
+    install: "yarn global add alex"
+    review: "alex ."
+
+# New tools for expanded testing coverage
+
+brakeman:
+  skip_in_batch: true # Requires Rails application, not applicable to gems
+  name: Brakeman
+  description: Static analysis security scanner for Ruby
+  tags: [security, ruby, dev]
+  links:
+    home: https://brakemanscanner.org
+    install: https://brakemanscanner.org/docs/install/
+  commands:
+    install: "bundle exec gem install brakeman"
+    review: "bundle exec brakeman --no-pager -q"
+
+fasterer:
+  name: Fasterer
+  description: Suggest performance improvements for Ruby code
+  tags: [ruby, quality, performance, dev]
+  links:
+    home: https://github.com/DamirSvrtan/fasterer
+  commands:
+    install: "bundle exec gem install fasterer"
+    review: "bundle exec fasterer"
+  files:
+    flag: ""
+    separator: " "
+    pattern: "*.rb"
+
+debride:
+  skip_in_batch: true # Broken on Ruby 3.4 (missing require for Racc, Timeout)
+  name: Debride
+  description: Find potentially unused methods and classes
+  tags: [ruby, quality, dev]
+  links:
+    home: https://github.com/seattlerb/debride
+  commands:
+    install: "bundle exec gem install debride"
+    review: "bundle exec debride lib/"
+
+rubycritic:
+  skip_in_batch: true # Generates HTML reports, best run manually
+  name: RubyCritic
+  description: Code quality analysis with HTML reports
+  tags: [ruby, quality, dev]
+  links:
+    home: https://github.com/whitesmith/rubycritic
+  commands:
+    install: "bundle exec gem install rubycritic"
+    review: "bundle exec rubycritic lib/ --no-browser -f console"
+
+metric_fu:
+  skip_in_batch: true # Meta-tool that runs many others, slow
+  name: MetricFu
+  description: Aggregate code metrics from multiple tools
+  tags: [ruby, quality, dev]
+  links:
+    home: https://github.com/metricfu/metric_fu
+  commands:
+    install: "bundle exec gem install metric_fu"
+    review: "bundle exec metric_fu"
+
+yardstick:
+  # skip_in_batch: true # Documentation coverage measurement
+  name: Yardstick
+  description: Measure YARD documentation coverage
+  tags: [docs, ruby, dev]
+  links:
+    home: https://github.com/dkubb/yardstick
+  commands:
+    install: "bundle exec gem install yardstick"
+    review: "bundle exec yardstick lib/"
+
+standard:
+  skip_in_batch: true # Conflicts with existing RuboCop configuration
+  name: Standard
+  description: Zero-configuration Ruby linter
+  tags: [ruby, syntax, dev]
+  links:
+    home: https://github.com/standardrb/standard
+  commands:
+    install: "bundle exec gem install standard"
+    review: "bundle exec standardrb"
+    format: "bundle exec standardrb --fix"
+
+rufo:
+  skip_in_batch: true # Alternative formatter to RuboCop
+  name: Rufo
+  description: Ruby code formatter
+  tags: [ruby, syntax, dev]
+  links:
+    home: https://github.com/ruby-formatter/rufo
+  commands:
+    install: "bundle exec gem install rufo"
+    review: "bundle exec rufo --check lib/"
+    format: "bundle exec rufo lib/"
+
+license_finder:
+  skip_in_batch: true # Slow - run manually with: rvw license_finder
+  name: License Finder
+  description: Check dependency licenses for compliance
+  tags: [dependencies, compliance, slow, dev]
+  links:
+    home: https://github.com/pivotal/LicenseFinder
+  commands:
+    install: "bundle exec gem install license_finder"
+    review: "bundle exec license_finder --decisions-file=./dependency_decisions.yml"
+
+notes:
+  name: Notes
+  description: Find TODO, FIXME, HACK, and OPTIMIZE comments
+  tags: [quality, dev]
   commands:
-    install: 'bundle exec gem install inch'
-    review: 'bundle exec inch'
+    review: "grep -rn --include='*.rb' -E '(TODO|FIXME|HACK|OPTIMIZE|XXX):?' lib/ test/ || true"
+  max_exit_status: 1

data/.rubocop.yml

@@ -1,5 +1,7 @@
 AllCops:
+  TargetRubyVersion: 3.2
   NewCops: enable
+  SuggestExtensions: false
   UseCache: true
   CacheRootDirectory: './'
   Exclude:
@@ -11,9 +13,40 @@ Layout/LineLength:
 
 # One case statement in a single method isn't complex.
 Metrics/CyclomaticComplexity:
-  IgnoredMethods: ['case']
+  AllowedMethods: ['case']
+
+# Development dependencies in gemspec is fine for this gem
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+# Keyword arguments are self-documenting at call sites, so they don't
+# create the readability problem that long positional lists do.
+Metrics/ParameterLists:
+  CountKeywordArgs: false
+
+# The CLI entry point is a routing method with one guard clause per line.
+# Each branch is a single method call — the structure is as clear as it gets.
+Metrics/AbcSize:
+  AllowedMethods: ['handle_early_exits']
 
 # 10 is a good goal but a little draconian
 Metrics/MethodLength:
   CountAsOne: ['array', 'hash', 'heredoc']
   Max: 15
+
+# Test classes naturally grow with coverage (see test/.rubocop.yml for higher limit)
+Metrics/ClassLength:
+  CountAsOne: ['array', 'hash', 'heredoc']
+  Max: 150
+
+Metrics/ModuleLength:
+  CountAsOne: ['array', 'hash', 'heredoc']
+  Max: 150
+
+# Fasterer prefers yield over block.call for performance
+Style/ExplicitBlockArgument:
+  Enabled: false
+
+# Fasterer prefers fetch with block over second argument for performance
+Style/RedundantFetchBlock:
+  Enabled: false

data/CHANGELOG.md

@@ -1,7 +1,47 @@
 ## [Unreleased]
 
-- TODO: Improve and streamline installation
-- TODO: Add support for targeting specific files
+## [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/Gemfile

@@ -5,4 +5,42 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in reviewer.gemspec
 gemspec
 
-gem 'rake', '~> 13.0'
+gem 'rake', '~> 13.2'
+
+# Security auditing - always run in CI
+gem 'bundler-audit'
+
+# Self-review tools - not required for running tests
+# Install with: bundle config set --local with lint && bundle install
+group :lint, optional: true do
+  # Ruby 3.4+ requires explicit racc (no longer a default gem)
+  gem 'racc'
+
+  # Style & Linting
+  gem 'rubocop'
+  gem 'rubocop-minitest'
+  gem 'rubocop-rake'
+  gem 'standard', '>= 1.35.1'
+
+  # Code Quality & Complexity
+  gem 'debride'
+  gem 'fasterer'
+  gem 'flay'
+  gem 'flog'
+  gem 'metric_fu'
+  gem 'reek'
+  gem 'rubycritic'
+
+  # Security
+  gem 'brakeman'
+
+  # Documentation
+  gem 'inch'
+  gem 'yardstick'
+
+  # Formatting
+  gem 'rufo'
+
+  # Compliance
+  gem 'license_finder'
+end