reviewer 0.1.5 → 1.0.0

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

@@ -17,11 +17,11 @@ module Reviewer
   class History
     attr_reader :file, :store
 
-    # Creates an instance of a YAML::Store-backed history file.
-    # @param file = Reviewer.configuration.history_file [Pathname] the history file to store data
+    # Creates an instance of a YAML::Store-backed history file
+    # @param file [Pathname] the history file to store data
     #
-    # @return [History] an instance of history
-    def initialize(file = Reviewer.configuration.history_file)
+    # @return [History]
+    def initialize(file:)
       @file = file
       @store = YAML::Store.new(file)
     end
@@ -33,9 +33,9 @@ module Reviewer
     #
     # @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
 
@@ -45,25 +45,18 @@ module Reviewer
     #
     # @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
 
     # Removes the existing history file.
     #
     # @return [void]
-    def reset!
+    def clear
       return unless File.exist?(file)
 
       FileUtils.rm(file)
     end
-
-    # Convenience class method for removing the history file.
-    #
-    # @return [void]
-    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

data/lib/reviewer/output/printer.rb

@@ -4,37 +4,98 @@ require 'io/console' # For determining console width/height
 
 module Reviewer
   class Output
-    # Wrapper to encapsulate some lower-level details of printing to $stdout
+    # ANSI terminal escape sequences for styled console output.
+    # Extracted from Printer so style definitions are separated from printing mechanics.
+    module AnsiStyles
+      ESC = "\e["
+      RESET = "#{ESC}0m".freeze
+
+      # Weight codes
+      WEIGHTS = { default: 0, bold: 1, light: 2, italic: 3 }.freeze
+
+      # Color codes
+      COLORS = {
+        black: 30, red: 31, green: 32, yellow: 33,
+        blue: 34, magenta: 35, cyan: 36, gray: 37, default: 39
+      }.freeze
+
+      # Style definitions: [weight, color]
+      STYLE_DEFS = {
+        success_bold: %i[bold green],
+        success: %i[default green],
+        success_light: %i[light green],
+        error: %i[bold red],
+        failure: %i[default red],
+        warning: %i[bold yellow],
+        warning_light: %i[light yellow],
+        source: %i[italic default],
+        bold: %i[default default],
+        default: %i[default default],
+        muted: %i[light gray]
+      }.freeze
+
+      # Pre-computed ANSI escape strings for each style
+      STYLES = STYLE_DEFS.transform_values do |weight_key, color_key|
+        "#{ESC}#{WEIGHTS.fetch(weight_key)};#{COLORS.fetch(color_key)}m"
+      end.freeze
+    end
+
+    # Wrapper to encapsulate some lower-level details of printing to $stdout.
+    # Handles ANSI styling via the pre-computed AnsiStyles::STYLES constant.
     class Printer
+      include AnsiStyles
+
       attr_reader :stream
 
-      # Creates an instance of Output to print Reviewer activity and results to the console
+      # Creates a printer for styled console output
+      # @param stream [IO] the output stream to write to
+      #
+      # @return [Printer]
       def initialize(stream = $stdout)
-        @stream = stream.tap do |str|
-          # If the IO channel supports flushing the output immediately, then ensure it's enabled
-          str.sync = str.respond_to?(:sync=)
-        end
+        @stream = stream
+        @stream.sync = true if @stream.respond_to?(:sync=)
       end
 
+      # Prints styled content without a newline
+      # @param style [Symbol] the style key for color and weight
+      # @param content [String] the text to print
+      #
+      # @return [void]
       def print(style, content)
         text(style, content)
       end
 
+      # Prints styled content followed by a newline
+      # @param style [Symbol] the style key for color and weight
+      # @param content [String] the text to print
+      #
+      # @return [void]
       def puts(style, content)
         text(style, content)
         stream.puts
       end
 
-      def tty?
-        stream.tty?
+      # Writes content directly to the stream without styling.
+      # Skips if content is nil or blank.
+      #
+      # @param content [String, nil] the raw text to write
+      # @return [void]
+      def write_raw(content)
+        return if content.to_s.strip.empty?
+
+        stream << content
       end
+
+      # Whether the output stream is a TTY (interactive terminal)
+      # @return [Boolean] true if the stream supports ANSI styling
+      def tty? = stream.tty?
       alias style_enabled? tty?
 
       private
 
       def text(style, content)
         if style_enabled?
-          stream.print Token.new(style, content).to_s
+          stream.print "#{STYLES.fetch(style)}#{content}#{RESET}"
         else
           stream.print content
         end