reviewer 0.1.4 → 1.0.0

data/lib/reviewer/context.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Reviewer
+  # Bundles the shared runtime dependencies that flow through the review/format lifecycle.
+  # Passed from Session → Batch → Runner → Command so that no class needs to reach
+  # into module-level globals for arguments, output, or history.
+  #
+  # @!attribute [rw] arguments
+  #   @return [Arguments] the parsed command-line arguments
+  # @!attribute [rw] output
+  #   @return [Output] the output channel for displaying content
+  # @!attribute [rw] history
+  #   @return [History] the YAML store for timing data and prepare timestamps
+  Context = Struct.new(:arguments, :output, :history, keyword_init: true)
+end

data/lib/reviewer/doctor/config_check.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Reviewer
+  module Doctor
+    # Validates the configuration file by delegating to Configuration::Loader
+    class ConfigCheck
+      attr_reader :report
+
+      # Creates a config check that validates the .reviewer.yml file
+      # @param report [Doctor::Report] the report to add findings to
+      # @param configuration [Configuration] the configuration to validate
+      #
+      # @return [ConfigCheck]
+      def initialize(report, configuration:)
+        @report = report
+        @configuration = configuration
+      end
+
+      # Checks for .reviewer.yml existence and validity
+      def check
+        config_file = @configuration.file
+
+        unless config_file.exist?
+          report.add(:configuration, status: :error,
+                                     message: 'No .reviewer.yml found', detail: 'Run `rvw init` to generate one')
+          return
+        end
+
+        report.add(:configuration, status: :ok, message: '.reviewer.yml found')
+        validate_via_loader
+      end
+
+      private
+
+      # Exercises the full Configuration::Loader pipeline (parse + validate) to surface config errors
+      def validate_via_loader
+        Configuration::Loader.configuration(file: @configuration.file)
+        report.add(:configuration, status: :ok, message: 'Configuration is valid')
+      rescue Configuration::Loader::InvalidConfigurationError => e
+        report.add(:configuration, status: :error, message: 'YAML syntax error', detail: e.message)
+      rescue Configuration::Loader::MissingReviewCommandError => e
+        report.add(:configuration, status: :error, message: 'Missing review command', detail: e.message)
+      end
+    end
+  end
+end

data/lib/reviewer/doctor/environment_check.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module Reviewer
+  module Doctor
+    # Checks environment prerequisites (git, Ruby version)
+    class EnvironmentCheck
+      attr_reader :report
+
+      # Creates an environment checker for Ruby and git availability
+      # @param report [Doctor::Report] the report to add findings to
+      #
+      # @return [EnvironmentCheck]
+      def initialize(report)
+        @report = report
+      end
+
+      # Checks Ruby version and git availability
+      def check
+        check_ruby_version
+        check_git
+      end
+
+      private
+
+      def check_ruby_version
+        report.add(:environment, status: :ok, message: "Ruby #{RUBY_VERSION}")
+      end
+
+      def check_git
+        stdout, _stderr, status = Open3.capture3('git --version')
+
+        unless status.success?
+          report.add(:environment, status: :warning,
+                                   message: 'Git not available',
+                                   detail: 'Git keywords (staged, modified, etc.) require git')
+          return
+        end
+
+        report.add(:environment, status: :ok, message: stdout.strip)
+        check_git_repo
+      end
+
+      def check_git_repo
+        _stdout, _stderr, status = Open3.capture3('git rev-parse --git-dir')
+
+        if status.success?
+          report.add(:environment, status: :ok, message: 'Inside a git repository')
+        else
+          report.add(:environment, status: :warning,
+                                   message: 'Not inside a git repository',
+                                   detail: 'Git keywords (staged, modified, etc.) will not work')
+        end
+      end
+    end
+  end
+end

data/lib/reviewer/doctor/formatter.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative '../output/formatting'
+
+module Reviewer
+  module Doctor
+    # Display logic for diagnostic reports
+    class Formatter
+      include Output::Formatting
+
+      attr_reader :output, :printer
+      private :output, :printer
+
+      SYMBOLS = { ok: "\u2713", warning: '!', error: "\u2717", info: "\u00b7", muted: "\u00b7" }.freeze
+      STYLES  = { ok: :success, warning: :warning, error: :failure, info: :muted, muted: :muted }.freeze
+
+      SECTION_LABELS = {
+        configuration: 'Configuration',
+        tools: 'Tools',
+        opportunities: 'Opportunities',
+        environment: 'Environment'
+      }.freeze
+
+      # Creates a formatter for diagnostic report display
+      # @param output [Output] the console output handler
+      #
+      # @return [Formatter]
+      def initialize(output)
+        @output = output
+        @printer = output.printer
+      end
+
+      # Renders a full diagnostic report
+      # @param report [Doctor::Report] the report to display
+      def print(report)
+        output.newline
+        Doctor::Report::SECTIONS.each do |section|
+          findings = report.section(section)
+          print_section(section, findings) if findings.any?
+        end
+        print_summary(report)
+      end
+
+      private
+
+      def print_section(section, findings)
+        printer.puts(:bold, SECTION_LABELS.fetch(section) { section.to_s.capitalize })
+        findings.each { |finding| print_finding(finding) }
+        output.newline
+      end
+
+      def print_finding(finding)
+        status = finding.status
+        message = finding.message
+        detail = finding.detail
+
+        symbol = SYMBOLS.fetch(status) { ' ' }
+        style = STYLES.fetch(status) { :default }
+
+        printer.print(style, "  #{symbol} ")
+        printer.puts(:default, message)
+        printer.puts(:muted, "    #{detail}") if detail
+      end
+
+      def print_summary(report)
+        if report.ok?
+          printer.puts(:success, 'No issues found')
+        else
+          printer.puts(:failure, pluralize(report.errors.size, 'issue found', 'issues found'))
+        end
+        output.newline
+      end
+    end
+  end
+end

data/lib/reviewer/doctor/keyword_check.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Reviewer
+  module Doctor
+    # Detects conflicts between configured tool names, tags, and reserved keywords
+    class KeywordCheck
+      attr_reader :report
+
+      RESERVED = Arguments::Keywords::RESERVED
+
+      # Creates a keyword check that scans for keyword conflicts in configuration
+      # @param report [Doctor::Report] the report to add findings to
+      # @param configuration [Configuration] the configuration to check
+      # @param tools [Tools] the tools collection to analyze
+      #
+      # @return [KeywordCheck]
+      def initialize(report, configuration:, tools:)
+        @report = report
+        @configuration = configuration
+        @tools = tools
+      end
+
+      # Checks for keyword conflicts between tool names, tags, and reserved keywords
+      def check
+        return unless @configuration.file.exist?
+
+        check_tool_names_vs_reserved
+        check_tags_vs_reserved
+        check_tool_names_vs_tags
+      rescue Configuration::Loader::MissingConfigurationError
+        # Tools may reference a stale config path — nothing to check
+      end
+
+      private
+
+      def all_tools = @all_tools ||= @tools.all
+
+      def tool_names = all_tools.map { |tool| tool.key.to_s }
+
+      def all_tags = all_tools.flat_map(&:tags).uniq
+
+      # Names of tools that use a given tag
+      def tools_with_tag(tag)
+        all_tools.select { |tool| tool.tags.include?(tag) }.map(&:name)
+      end
+
+      # Tags that belong to tools OTHER than the named tool
+      def tags_from_other_tools(tool_name)
+        all_tools.reject { |tool| tool.key.to_s == tool_name }.flat_map(&:tags).uniq
+      end
+
+      def check_tool_names_vs_reserved
+        (tool_names & RESERVED).each do |name|
+          report.add(:configuration,
+                     status: :warning,
+                     message: "Tool name '#{name}' shadows reserved keyword '#{name}'",
+                     detail: "Reserved keywords (#{RESERVED.join(', ')}) trigger special behavior. " \
+                             'Rename this tool to avoid unexpected results.')
+        end
+      end
+
+      def check_tags_vs_reserved
+        (all_tags & RESERVED).each do |tag|
+          report.add(:configuration,
+                     status: :warning,
+                     message: "Tag '#{tag}' shadows reserved keyword '#{tag}' (used by #{tools_with_tag(tag).join(', ')})",
+                     detail: "Reserved keywords (#{RESERVED.join(', ')}) trigger special behavior. " \
+                             'Rename this tag or use -t to pass tags explicitly.')
+        end
+      end
+
+      def check_tool_names_vs_tags
+        tool_names.each do |name|
+          next unless tags_from_other_tools(name).include?(name)
+
+          report.add(:configuration,
+                     status: :warning,
+                     message: "Tool name '#{name}' is also a tag on: #{tools_with_tag(name).join(', ')}",
+                     detail: "'rvw #{name}' will run both the '#{name}' tool and tagged tools. " \
+                             'Use -t to target tags explicitly if this is unintended.')
+        end
+      end
+    end
+  end
+end

data/lib/reviewer/doctor/opportunity_check.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Reviewer
+  module Doctor
+    # Suggests improvements based on current configuration and project state
+    class OpportunityCheck
+      attr_reader :report, :project_dir
+
+      # Creates an opportunity checker that scans for unconfigured tools and missing features
+      # @param report [Doctor::Report] the report to add findings to
+      # @param project_dir [Pathname] the project root for tool detection
+      # @param configuration [Configuration] the configuration to check
+      # @param tools [Tools] the tools collection to analyze
+      #
+      # @return [OpportunityCheck]
+      def initialize(report, project_dir, configuration:, tools:)
+        @report = report
+        @project_dir = project_dir
+        @configuration = configuration
+        @tools = tools
+      end
+
+      # Checks for unconfigured tools, missing file targeting, and missing format commands
+      def check
+        return unless @configuration.file.exist?
+
+        check_unconfigured_tools
+        check_missing_files_config
+        check_missing_format_command
+      end
+
+      private
+
+      def check_unconfigured_tools
+        detected = Setup::Detector.new(project_dir).detect
+        configured_keys = @tools.all.map(&:key)
+
+        detected.each do |result|
+          next if configured_keys.include?(result.key)
+
+          report.add(:opportunities, status: :info,
+                                     message: "#{result.name} detected but not configured",
+                                     detail: result.reasons.join(', '))
+        end
+      end
+
+      def check_missing_files_config
+        @tools.all.each do |tool|
+          next if tool.skip_in_batch?
+          next if tool.supports_files?
+          next unless catalog_supports?(tool.key, :files)
+
+          report.add(:opportunities, status: :info,
+                                     message: "#{tool.name} has no file targeting configured",
+                                     detail: 'Add a `files` section to enable staged/modified file scoping')
+        end
+      end
+
+      def check_missing_format_command
+        @tools.all.each do |tool|
+          next if tool.skip_in_batch?
+          next if tool.formattable?
+          next unless catalog_supports?(tool.key, :format)
+
+          report.add(:opportunities, status: :info,
+                                     message: "#{tool.name} has no format command",
+                                     detail: 'Add a `format` command to enable `fmt` support')
+        end
+      end
+
+      # Returns true only if the catalog knows this tool AND the catalog entry
+      # includes the given capability (:files or :format command)
+      def catalog_supports?(key, capability)
+        entry = Setup::Catalog::TOOLS[key]
+        return false unless entry
+
+        case capability
+        when :files
+          entry.key?(:files)
+        when :format
+          entry.dig(:commands, :format) ? true : false
+        else
+          false
+        end
+      end
+    end
+  end
+end

data/lib/reviewer/doctor/report.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Reviewer
+  module Doctor
+    # Structured container for diagnostic findings organized by section
+    class Report
+      # A single diagnostic finding with status, message, and optional detail.
+      # @!attribute status [rw]
+      #   @return [Symbol] the severity (:ok, :warning, :error, or :info)
+      # @!attribute message [rw]
+      #   @return [String] the finding summary
+      # @!attribute detail [rw]
+      #   @return [String, nil] optional detail or guidance text
+      Finding = Struct.new(:status, :message, :detail, keyword_init: true)
+
+      # Ordered list of report sections
+      SECTIONS = %i[configuration tools opportunities environment].freeze
+
+      attr_reader :findings
+
+      def initialize
+        @findings = Hash.new { |hash, key| hash[key] = [] }
+      end
+
+      # Adds a finding to a section
+      # @param section [Symbol] one of SECTIONS
+      # @param status [Symbol] :ok, :warning, :error, or :info
+      # @param message [String] the finding summary
+      # @param detail [String, nil] optional detail text
+      def add(section, status:, message:, detail: nil)
+        findings[section] << Finding.new(status: status, message: message, detail: detail)
+      end
+
+      # Whether all findings are free of errors
+      def ok?
+        all_findings.none? { |finding| finding.status == :error }
+      end
+
+      # All error findings across sections
+      def errors
+        all_findings.select { |finding| finding.status == :error }
+      end
+
+      # All warning findings across sections
+      def warnings
+        all_findings.select { |finding| finding.status == :warning }
+      end
+
+      # Findings for a specific section
+      # @param name [Symbol] the section name
+      # @return [Array<Finding>] findings for that section
+      def section(name)
+        findings[name]
+      end
+
+      private
+
+      def all_findings
+        findings.values.flatten
+      end
+    end
+  end
+end

data/lib/reviewer/doctor/tool_inventory.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Reviewer
+  module Doctor
+    # Reports the status of each configured tool
+    class ToolInventory
+      attr_reader :report
+
+      # Creates a tool inventory check that reports batch/skip status for each tool
+      # @param report [Doctor::Report] the report to add findings to
+      # @param configuration [Configuration] the configuration to check
+      # @param tools [Tools] the tools collection to report on
+      #
+      # @return [ToolInventory]
+      def initialize(report, configuration:, tools:)
+        @report = report
+        @configuration = configuration
+        @tools = tools
+      end
+
+      # Reports batch/skip status and available commands for each configured tool
+      def check
+        return unless @configuration.file.exist?
+
+        @tools.all.each do |tool|
+          skipped = tool.skip_in_batch?
+
+          report.add(:tools,
+                     status: skipped ? :muted : :ok,
+                     message: "#{tool.name} (#{tool.key}) — #{command_summary(tool)}")
+        end
+      end
+
+      private
+
+      def command_summary(tool)
+        %i[review format install prepare].select { |cmd| tool.command?(cmd) }.join(', ')
+      end
+    end
+  end
+end

data/lib/reviewer/doctor.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'doctor/formatter'
+require_relative 'doctor/report'
+require_relative 'doctor/config_check'
+require_relative 'doctor/keyword_check'
+require_relative 'doctor/tool_inventory'
+require_relative 'doctor/opportunity_check'
+require_relative 'doctor/environment_check'
+
+module Reviewer
+  # Diagnostic module for checking configuration, tools, and environment health
+  module Doctor
+    # Runs all diagnostic checks and returns a structured report
+    # @param project_dir [Pathname] the project root to scan
+    #
+    # @return [Doctor::Report] the complete diagnostic report
+    def self.run(configuration:, tools:, project_dir: Pathname.pwd)
+      report = Report.new
+      ConfigCheck.new(report, configuration: configuration).check
+      KeywordCheck.new(report, configuration: configuration, tools: tools).check
+      ToolInventory.new(report, configuration: configuration, tools: tools).check
+      OpportunityCheck.new(report, project_dir, configuration: configuration, tools: tools).check
+      EnvironmentCheck.new(report).check
+      report
+    end
+  end
+end

data/lib/reviewer/history.rb

@@ -3,36 +3,60 @@
 require 'yaml/store'
 
 module Reviewer
-  # Provides an instance of a storage resource for persisting data across runs
+  # Provides an interface to a local storage resource for persisting data across runs. For example,
+  # it enables remembering when `prepare` commands were run for reviews so they can be run less
+  # frequently and thus improve performance.
+  #
+  # It also enables remembering seeds across runs. Eventually `rvw rerun` could reuse the seeds from
+  # the immediately preceding run to more easily facilitate fixing tests that are accidentally
+  # order-dependent. Or it could automatically record a list of seeds that led to failures.
+  #
+  # Long term, it could serve to record timing details across runs to provide insight to min, max,
+  # and means. Those times could then be used for reviewer to make more informed decisions about
+  # default behavior to ensure each run remains fast.
   class History
     attr_reader :file, :store
 
-    def initialize(file = Reviewer.configuration.history_file)
+    # Creates an instance of a YAML::Store-backed history file
+    # @param file [Pathname] the history file to store data
+    #
+    # @return [History]
+    def initialize(file:)
       @file = file
       @store = YAML::Store.new(file)
     end
 
+    # Saves a value to a given location in the history
+    # @param group [Symbol] the first-level key to use for saving the value--frequently a tool name
+    # @param attribute [Symbol] the second-level key to use for retrieving the value
+    # @param value [Primitive] any value that can be cleanly stored in YAML
+    #
+    # @return [Primitive] the value being stored
     def set(group, attribute, value)
-      store.transaction do |s|
-        s[group] = {} if s[group].nil?
-        s[group][attribute] = value
+      store.transaction do
+        store[group] ||= {}
+        store[group][attribute] = value
       end
     end
 
+    # Retrieves a stored value from the history file
+    # @param group [Symbol] the first-level key to use for retrieving the value
+    # @param attribute [Symbol] the second-level key to use for retrieving the value
+    #
+    # @return [Primitive] the value being stored
     def get(group, attribute)
-      store.transaction do |s|
-        s[group].nil? ? nil : s[group][attribute]
+      store.transaction(true) do
+        store[group]&.[](attribute)
       end
     end
 
-    def reset!
+    # Removes the existing history file.
+    #
+    # @return [void]
+    def clear
       return unless File.exist?(file)
 
       FileUtils.rm(file)
     end
-
-    def self.reset!
-      new.reset!
-    end
   end
 end

data/lib/reviewer/output/formatting.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Reviewer
+  class Output
+    # Shared display vocabulary included by all domain formatters.
+    # Provides common constants and helper methods for formatting output.
+    module Formatting
+      CHECKMARK = "\u2713"
+      XMARK = "\u2717"
+
+      private
+
+      # Formats a duration in seconds for display
+      # @param seconds [Float, nil] the duration to format
+      # @return [String] formatted duration (e.g., "1.23s")
+      def format_duration(seconds)
+        "#{seconds.to_f.round(2)}s"
+      end
+
+      # Returns the appropriate status mark
+      # @param success [Boolean] whether the operation succeeded
+      # @return [String] checkmark or x mark
+      def status_mark(success) = success ? CHECKMARK : XMARK
+
+      # Returns the appropriate style key for a status
+      # @param success [Boolean] whether the operation succeeded
+      # @return [Symbol] :success or :failure
+      def status_style(success) = success ? :success : :failure
+
+      # Pluralizes a word based on count
+      # @param count [Integer] the count
+      # @param singular [String] the singular form
+      # @param plural [String] the plural form (defaults to singular + "s")
+      # @return [String] formatted count with word (e.g., "1 issue" or "3 issues")
+      def pluralize(count, singular, plural = "#{singular}s")
+        count == 1 ? "1 #{singular}" : "#{count} #{plural}"
+      end
+    end
+  end
+end