reviewer 0.1.5 → 1.0.0

data/lib/reviewer/setup/gemfile_lock.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Reviewer
+  module Setup
+    # Parses a Gemfile.lock to extract gem names from the specs section
+    class GemfileLock
+      # Spec lines are indented with 4 spaces: "    gem-name (version)"
+      SPEC_LINE = /\A {4}(\S+)\s/
+
+      attr_reader :path
+
+      # Creates a parser for extracting gem names from a Gemfile.lock
+      # @param path [Pathname] the path to the Gemfile.lock file
+      #
+      # @return [GemfileLock]
+      def initialize(path)
+        @path = path
+      end
+
+      # Returns the set of gem names found in the specs section
+      #
+      # @return [Set<String>] gem names
+      def gem_names
+        return Set.new unless path.exist?
+
+        parse_specs
+      end
+
+      private
+
+      def parse_specs
+        in_specs = false
+        gems = Set.new
+
+        path.each_line do |line|
+          in_specs, gem_name = process_line(line, in_specs)
+          gems.add(gem_name) if gem_name
+        end
+
+        gems
+      end
+
+      def process_line(line, in_specs)
+        return [true, nil] if line.strip == 'specs:'
+        return [in_specs, nil] unless in_specs
+
+        match = line.match(SPEC_LINE)
+        return [true, match[1]] if match
+
+        still_in_specs = line.start_with?('      ') || line.strip.empty?
+        [still_in_specs, nil]
+      end
+    end
+  end
+end

data/lib/reviewer/setup/generator.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+require_relative 'tool_block'
+
+module Reviewer
+  module Setup
+    # Produces .reviewer.yml YAML content from a list of detected tool keys.
+    # Orchestrates which tools to include; delegates per-tool rendering to ToolBlock.
+    class Generator
+      attr_reader :tool_keys, :project_dir
+
+      # Creates a generator for producing .reviewer.yml configuration
+      # @param tool_keys [Array<Symbol>] catalog tool keys to include in config
+      # @param project_dir [Pathname] the project root (used for package manager detection)
+      #
+      # @return [Generator]
+      def initialize(tool_keys, project_dir: Pathname.pwd)
+        @tool_keys = tool_keys
+        @project_dir = Pathname(project_dir)
+      end
+
+      # Generates YAML configuration string for the detected tools
+      #
+      # @return [String] valid YAML for .reviewer.yml
+      def generate
+        return "--- {}\n" if tool_keys.empty?
+
+        blocks = tool_keys.filter_map do |key|
+          definition = Catalog.config_for(key)
+          next unless definition
+
+          ToolBlock.new(key, definition, js_runner: js_runner).to_s
+        end
+
+        "---\n#{blocks.join("\n")}"
+      end
+
+      private
+
+      # Detects the JS package manager based on lockfile presence
+      def js_runner
+        @js_runner ||= if project_dir.join('yarn.lock').exist?
+                         'yarn'
+                       elsif project_dir.join('pnpm-lock.yaml').exist?
+                         'pnpm exec'
+                       else
+                         'npx'
+                       end
+      end
+    end
+  end
+end

data/lib/reviewer/setup/tool_block.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Reviewer
+  module Setup
+    # Renders the YAML configuration block for a single tool definition.
+    # Owns the definition data so rendering methods reference self's state
+    # rather than reaching into parameters.
+    class ToolBlock
+      YAML_BARE_WORDS = %w[true false yes no on off null ~].freeze
+
+      # Creates a renderer for a single tool's YAML configuration block
+      # @param key [Symbol] the tool key (e.g., :rubocop)
+      # @param definition [Hash] the catalog definition for this tool
+      # @param js_runner [String] the JS package runner to substitute for npx
+      #
+      # @return [ToolBlock]
+      def initialize(key, definition, js_runner:)
+        @key = key
+        @definition = definition
+        @js_runner = js_runner
+      end
+
+      # Renders the full YAML block for this tool
+      #
+      # @return [String] the YAML text for this tool's configuration
+      def to_s
+        lines = header_lines
+        lines.concat(commands_block)
+        lines.concat(files_block) if @definition[:files]
+        lines << ''
+        lines.join("\n")
+      end
+
+      private
+
+      def header_lines
+        lines = []
+        lines << "# #{@definition[:description]}"
+        lines << "#{@key}:"
+        lines << "  name: #{quote(@definition[:name])}"
+        lines << "  description: #{quote(@definition[:description])}"
+        lines << tags_line if @definition[:tags]&.any?
+        lines
+      end
+
+      def tags_line
+        "  tags: [#{@definition[:tags].join(', ')}]"
+      end
+
+      def commands_block
+        commands = @definition[:commands]
+        lines = ['  commands:']
+        %i[install prepare review format].each do |type|
+          next unless commands[type]
+
+          lines << "    #{type}: #{quote(apply_js_runner(commands[type].to_s))}"
+        end
+        lines
+      end
+
+      def files_block
+        lines = ['  files:']
+        lines.concat(files_command_lines)
+        lines.concat(files_targeting_lines)
+        lines
+      end
+
+      def files_command_lines
+        %i[review format].filter_map do |type|
+          "    #{type}: #{quote(apply_js_runner(tool_files[type].to_s))}" if tool_files[type]
+        end
+      end
+
+      def files_targeting_lines
+        [
+          (file_setting_line(:flag) if tool_files.key?(:flag)),
+          (file_setting_line(:separator) if tool_files.key?(:separator)),
+          (file_setting_line(:pattern) if tool_files[:pattern]),
+          ("    map_to_tests: #{tool_files[:map_to_tests]}" if tool_files[:map_to_tests])
+        ].compact
+      end
+
+      def file_setting_line(key)
+        "    #{key}: #{quote(tool_files[key])}"
+      end
+
+      def tool_files
+        @definition[:files]
+      end
+
+      def apply_js_runner(command)
+        return command unless command.start_with?('npx ')
+
+        command.sub('npx ', "#{@js_runner} ")
+      end
+
+      def quote(value)
+        str = value.to_s
+        return "''" if str.empty?
+
+        needs_quoting?(str) ? "'#{str.gsub("'", "''")}'" : str
+      end
+
+      def needs_quoting?(str)
+        str.match?(/[:#\[\]{}&*!|>'"@`,]/) ||
+          str.strip != str ||
+          str.empty? ||
+          YAML_BARE_WORDS.include?(str.downcase)
+      end
+    end
+  end
+end

data/lib/reviewer/setup.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative 'setup/catalog'
+require_relative 'setup/detector'
+require_relative 'setup/formatter'
+require_relative 'setup/gemfile_lock'
+require_relative 'setup/generator'
+
+module Reviewer
+  # Handles first-run setup: detecting tools and generating .reviewer.yml
+  module Setup
+    # URL to the configuration documentation for setup output messages
+    CONFIG_URL = 'https://github.com/garrettdimon/reviewer#configuration'
+
+    # Runs the full setup flow: detect tools, generate config, display results
+    # @param project_dir [Pathname, String] the project root to scan (defaults to pwd)
+    # @param output [Output] the console output handler
+    #
+    # @return [void]
+    def self.run(configuration:, project_dir: Pathname.pwd, output: Output.new)
+      config_file = configuration.file
+      formatter = Formatter.new(output)
+
+      if config_file.exist?
+        formatter.setup_already_exists(config_file)
+        return
+      end
+
+      results = Detector.new(project_dir).detect
+
+      if results.empty?
+        formatter.setup_no_tools_detected
+        return
+      end
+
+      yaml = Generator.new(results.map(&:key), project_dir: project_dir).generate
+      config_file.write(yaml)
+      formatter.setup_success(results)
+    end
+  end
+end

data/lib/reviewer/shell/result.rb

@@ -18,7 +18,16 @@ module Reviewer
         executable_not_found: "can't find executable"
       }.freeze
 
-      attr_accessor :stdout, :stderr, :status, :exit_status
+      # @!attribute stdout
+      #   @return [String, nil] standard output from the command
+      # @!attribute stderr
+      #   @return [String, nil] standard error from the command
+      # @!attribute status
+      #   @return [Process::Status, nil] the process status object
+      # @!attribute exit_status
+      #   @return [Integer, nil] the exit status code from the command
+      attr_reader :stdout, :stderr, :status
+      attr_accessor :exit_status
 
       # An instance of a result from running a local command. Captures the values for `$stdout`,
       #   `$stderr`, and the exit status of the command to provide a reliable way of interpreting
@@ -39,24 +48,18 @@ module Reviewer
         @exit_status = status&.exitstatus
       end
 
-      def exists?
-        [stdout, stderr, exit_status].compact.any?
-      end
+      def exists? = [stdout, stderr, exit_status].compact.any?
 
       # Determines if re-running a command is entirely futile. Primarily to help when a command
       # fails within a batch and needs to be re-run to show the output
       #
       # @return [Boolean] true if the exit status code is greater than or equal to 126
-      def rerunnable?
-        exit_status < EXIT_STATUS_CODES[:cannot_execute]
-      end
+      def rerunnable? = exit_status < EXIT_STATUS_CODES[:cannot_execute]
 
       # Determines whether a command simply cannot be executed.
       #
       # @return [Boolean] true if the exit sttaus code equals 126
-      def cannot_execute?
-        exit_status == EXIT_STATUS_CODES[:cannot_execute]
-      end
+      def cannot_execute? = exit_status == EXIT_STATUS_CODES[:cannot_execute]
 
       # Determines whether the command failed because the executable cannot be found. Since this is
       # an error that can be corrected fairly predictably and easily, it provides the ability to
@@ -73,11 +76,7 @@ module Reviewer
       #
       # @return [String] stdout if present, otherwise stderr
       def to_s
-        result_string = ''
-        result_string += stderr
-        result_string += stdout
-
-        result_string.strip
+        [stderr, stdout].compact.join("\n").strip
       end
     end
   end

data/lib/reviewer/shell/timer.rb

@@ -6,67 +6,72 @@ module Reviewer
   class Shell
     # Provides a structured interface for measuring realtime main while running comamnds
     class Timer
-      attr_accessor :prep, :main
+      # @!attribute prep
+      #   @return [Float, nil] the preparation time in seconds
+      # @!attribute main
+      #   @return [Float, nil] the main execution time in seconds
+      attr_reader :prep, :main
 
-      # A 'Smart' timer that understands preparation time and main time and can easily do the math
-      #   to help determine what percentage of time was prep. The times can be passed in directly or
-      #   recorded using the `record_prep` and `record_main` methods
-      # @param prep: nil [Float] the amount of time in seconds the preparation command ran
-      # @param main: nil [Float] the amount of time in seconds the primary command ran
+      # A timer that tracks preparation and main execution times separately.
+      # Times can be passed directly or recorded using `record_prep` and `record_main`.
+      # @param prep [Float, nil] the preparation time in seconds
+      # @param main [Float, nil] the main execution time in seconds
       #
-      # @return [self]
+      # @return [Timer]
       def initialize(prep: nil, main: nil)
         @prep = prep
         @main = main
       end
 
       # Records the execution time for the block and assigns it to the `prep` time
-      # @param &block [Block] the commands to be timed
+      # @param block [Block] the commands to be timed
       #
       # @return [Float] the execution time for the preparation
-      def record_prep(&block)
-        @prep = record(&block)
-      end
+      def record_prep(&) = @prep = record(&)
 
       # Records the execution time for the block and assigns it to the `main` time
-      # @param &block [Block] the commands to be timed
+      # @param block [Block] the commands to be timed
       #
       # @return [Float] the execution time for the main command
-      def record_main(&block)
-        @main = record(&block)
-      end
+      def record_main(&) = @main = record(&)
 
-      def prep_seconds
-        prep.round(2)
-      end
+      # The preparation time rounded to two decimal places
+      #
+      # @return [Float] prep time in seconds
+      def prep_seconds = prep.round(2)
 
-      def main_seconds
-        main.round(2)
-      end
+      # The main execution time rounded to two decimal places
+      #
+      # @return [Float] main time in seconds
+      def main_seconds = main.round(2)
 
-      def total_seconds
-        total.round(2)
-      end
+      # The total execution time (prep + main) rounded to two decimal places
+      #
+      # @return [Float] total time in seconds
+      def total_seconds = total.round(2)
+
+      # The total time (prep + main) without rounding
+      #
+      # @return [Float] total time in seconds
+      def total = [prep, main].compact.sum
+
+      # Whether both prep and main times have been recorded
+      #
+      # @return [Boolean] true if both phases were timed
+      def prepped? = [prep, main].all?
 
+      # The percentage of total time spent on preparation
+      #
+      # @return [Integer, nil] percentage (0-100) or nil if not prepped
       def prep_percent
         return nil unless prepped?
 
         (prep / total.to_f * 100).round
       end
 
-      def total
-        [prep, main].compact.sum
-      end
-
-      def prepped?
-        !(prep.nil? || main.nil?)
-      end
-
       private
 
-      def record(&block)
-        Benchmark.realtime(&block)
-      end
+      def record(&) = Benchmark.realtime(&)
     end
   end
 end

data/lib/reviewer/shell.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'open3'
+require 'pty'
 
 require_relative 'shell/result'
 require_relative 'shell/timer'
@@ -15,40 +16,68 @@ module Reviewer
     def_delegators :@result, :exit_status
 
     # Initializes a Reviewer shell for running and benchmarking commands, and capturing output
+    # @param stream [IO] the output stream for direct (passthrough) output
     #
     # @return [Shell] a shell instance for running and benchmarking commands
-    def initialize
+    def initialize(stream: $stdout)
+      @stream = stream
       @timer = Timer.new
       @result = Result.new
+      @captured_results = nil
     end
 
-    # Run a command without capturing the output. This ensures the results are displayed realtime
-    # if the command was run directly in the shell. So it keeps any color or other formatting that
-    # would be stripped out by capturing $stdout as a basic string.
+    # Run a command via PTY, streaming output in real-time while capturing it for later use
+    # (e.g. failed file extraction). PTY allocates a pseudo-terminal so the child process
+    # preserves ANSI colors and interactive behavior.
     # @param command [String] the command to run
     #
-    # @return [Integer] exit status vaue of 0 when successful or 1 when unsuccessful
+    # @return [Result] the captured result including stdout and exit status
     def direct(command)
       command = String(command)
+      buffer = +''
 
-      result.exit_status = system(command) ? 0 : 1
-    end
+      reader, _writer, pid = PTY.spawn(command)
+      begin
+        reader.each_line do |line|
+          @stream.print line
+          buffer << line
+        end
+      rescue Errno::EIO
+        # Expected when child process exits before all output is read
+      end
 
-    def capture_prep(command)
-      timer.record_prep { capture_results(command) }
+      _, status = Process.waitpid2(pid)
+      @result = Result.new(buffer, nil, status)
+    rescue Errno::ENOENT
+      @result = Result.new(buffer, nil, nil)
+      @result.exit_status = Result::EXIT_STATUS_CODES[:executable_not_found]
     end
 
-    def capture_main(command)
-      timer.record_main { capture_results(command) }
-    end
+    # Captures and times the preparation command execution
+    # @param command [String, Command] the command to run
+    #
+    # @return [Result] the captured result including stdout, stderr, and exit status
+    def capture_prep(command) = timer.record_prep { capture_results(command) }
+
+    # Captures and times the main command execution
+    # @param command [String, Command] the command to run
+    #
+    # @return [Result] the captured result including stdout, stderr, and exit status
+    def capture_main(command) = timer.record_main { capture_results(command) }
 
     private
 
+    # Open3.capture3 returns stdout, stderr, and status separately. Keeping them
+    # separate matters for FailedFiles, which merges the streams intentionally
+    # when scanning for file paths after a failure.
     def capture_results(command)
       command = String(command)
 
       @captured_results = Open3.capture3(command)
       @result = Result.new(*@captured_results)
+    rescue Errno::ENOENT
+      @result = Result.new(nil, nil, nil)
+      @result.exit_status = Result::EXIT_STATUS_CODES[:executable_not_found]
     end
   end
 end

data/lib/reviewer/tool/conversions.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Reviewer
+  class Tool
+    # Conversion functions for coercing values to Tool instances
+    module Conversions
+      # Coerces a value into a Tool instance
+      # @param value [Tool] the value to convert
+      # @return [Tool] the resulting Tool instance
+      # @raise [TypeError] if the value is not a Tool
+      def Tool(value) # rubocop:disable Naming/MethodName
+        case value
+        in Tool then value
+        else raise TypeError, "Cannot convert #{value.class} to Tool"
+        end
+      end
+      module_function :Tool
+    end
+  end
+end

data/lib/reviewer/tool/file_resolver.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Reviewer
+  class Tool
+    # Resolves which files a tool should process by mapping and filtering.
+    class FileResolver
+      # Creates a FileResolver for a tool's settings
+      # @param settings [Tool::Settings] the tool's settings containing file configuration
+      #
+      # @return [FileResolver] a resolver instance for the tool
+      def initialize(settings)
+        @settings = settings
+      end
+
+      # Resolves input files by mapping source files to test files (if configured) and
+      # filtering by the tool's file pattern
+      # @param files [Array<String>] the input files to resolve
+      #
+      # @return [Array<String>] files after mapping and filtering
+      def resolve(files)
+        return files unless pattern
+
+        filter(map(files))
+      end
+
+      # Determines if the tool should be skipped because files were requested but none match
+      # @param files [Array<String>] the requested files
+      #
+      # @return [Boolean] true if files were requested but none remain after resolution
+      def skip?(files)
+        files.any? && resolve(files).empty?
+      end
+
+      private
+
+      attr_reader :settings
+
+      def map(files)
+        mapper = settings.map_to_tests
+        return files unless mapper
+
+        TestFileMapper.new(mapper).map(files)
+      end
+
+      def filter(files)
+        files.select { |file| File.fnmatch(pattern, File.basename(file)) }
+      end
+
+      def pattern
+        settings.files_pattern
+      end
+    end
+  end
+end