cleo_quality_review 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ef174aa218590b9a2f32114c94e9ef21c73d6809e87524750d66adc70562f0b
-  data.tar.gz: d25eae8497f8b87506231b4586614729b58b93634c3ed37a935d5029abcd3056
+  metadata.gz: 9277c83af1fccd6045fde0ef6879b6fa7d9d2fc0d1848e1401d58f1889a6c458
+  data.tar.gz: c2d158fd19d8566edad3556ed46b020c34ec2a2c7ade2199d3b06b2c612b1e6c
 SHA512:
-  metadata.gz: a3c8d5bf0d7748a797b7c82c74ff5f1e914147b16b45b13e342e49268eb5e355dcb9885953725c16f118254ff48c728782289fcf291c49478ca0aca002f071bd
-  data.tar.gz: 436193715042ed3165c0ecf04026a70e0681a96bbd5bb6adc9c842662ae405e8b5409b408c5597c21884590374b1029ef94c3230bded8667117c978511d40ce9
+  metadata.gz: 6fbd671e9068c52268bf5f2d139817a330919c630ebe59773e785a2e25f5fa8039eb34280ad0b58cb31de984404ee8b59ab5deb4469d9246a60f59f088ccbb6d
+  data.tar.gz: 37731db93423a4da4948a00ab7550809d6f9a1dabc69cb313e2ba066e6239fe0160b3a12c560da66976ecf324d344eee5398cd95b0b1778b4ea07441d46620f1

data/cleo_quality_review.gemspec

@@ -24,7 +24,6 @@ Gem::Specification.new do |spec|
   spec.executables = ["check_quality"]
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "debride"
   spec.add_dependency "fasterer"
   spec.add_dependency "flog"
   spec.add_dependency "reek"

data/lib/cleo_quality_review/changes_diff.rb

@@ -21,9 +21,10 @@ module CleoQualityReview
     end
 
     ##
-    # @return [String] combined tracked and untracked diff content
+    # @return [String] combined tracked and untracked diff content, or an empty
+    #   string when there are no target files to review
     def to_s
-      @to_s ||= [tracked_changes_diff, untracked_changes_diff].reject(&:empty?).join("\n")
+      @to_s ||= capture_diff
     end
 
     ##
@@ -36,11 +37,18 @@ module CleoQualityReview
 
     attr_reader :command_runner, :target_files, :base_ref, :strict_base
 
-    def tracked_changes_diff
-      command = ["git", "diff", diff_base]
-      command.concat(["--", *target_files]) unless target_files.empty?
+    # When there are no target files there is nothing to review, so the diff is
+    # empty. We must not fall back to an unscoped +git diff+, which would capture
+    # the entire working tree (including untracked files such as installed gems
+    # under vendor/bundle) and overflow the LLM request.
+    def capture_diff
+      return "" if target_files.empty?
 
-      command_runner.run(*command).stdout
+      [tracked_changes_diff, untracked_changes_diff].reject(&:empty?).join("\n")
+    end
+
+    def tracked_changes_diff
+      command_runner.run("git", "diff", diff_base, "--", *target_files).stdout
     end
 
     def untracked_changes_diff
@@ -50,13 +58,8 @@ module CleoQualityReview
     end
 
     def untracked_target_files
-      command = ["git", "ls-files", "--others", "--exclude-standard"]
-      empty_targets = target_files.empty?
-      command.concat(["--", *target_files]) unless empty_targets
-
-      command_runner.run(*command).stdout.lines.map(&:strip).select do |path|
-        empty_targets || target_files.include?(path)
-      end
+      command_runner.run("git", "ls-files", "--others", "--exclude-standard", "--", *target_files)
+        .stdout.lines.map(&:strip).select { |path| target_files.include?(path) }
     end
 
     def diff_base

data/lib/cleo_quality_review/checks.rb

@@ -9,7 +9,6 @@ module CleoQualityReview
     require_relative "checks/reek"
     require_relative "checks/flog"
     require_relative "checks/fasterer"
-    require_relative "checks/debride"
 
     class << self
       ##

data/lib/cleo_quality_review/cli.rb

@@ -6,6 +6,7 @@ require_relative "../cleo_quality_review"
 require_relative "command_runner"
 require_relative "formatter"
 require_relative "github_review_publisher"
+require_relative "incremental_base_resolver"
 require_relative "options"
 require_relative "runner"
 require_relative "run_artifacts"
@@ -58,7 +59,7 @@ module CleoQualityReview
 
     def run_one_shot(arguments)
       options = Options.parse(arguments)
-      run = Runner.new(options: options, command_runner: command_runner).run
+      run = build_runner(options).run
       output = Formatter.new(run: run, command_runner: command_runner).format
       print_output(output)
       0
@@ -70,11 +71,19 @@ module CleoQualityReview
 
     def run_analyze(arguments)
       options = Options.parse(arguments)
-      run = Runner.new(options: options, command_runner: command_runner).run
+      run = build_runner(options).run
       stdout.puts(run.review_id)
       0
     end
 
+    def build_runner(options)
+      Runner.new(
+        options: options,
+        command_runner: command_runner,
+        base_resolver: IncrementalBaseResolver.new(command_runner: command_runner),
+      )
+    end
+
     def run_render(arguments)
       options = Options.parse(arguments)
       run = RunArtifacts.load(review_id: options.validated_review_id).to_run(**options.run_loading_params)

data/lib/cleo_quality_review/concurrent_executor.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require_relative "configuration"
+
+module CleoQualityReview
+  ##
+  # Runs independent, blocking work items across a bounded pool of threads.
+  #
+  # The pool is sized to the available processor count by default, so it
+  # naturally expands or contracts with the host. When there are more work
+  # items than workers, the surplus waits on an internal queue and is picked
+  # up as workers free up. Results are returned in the same order as the
+  # input items.
+  #
+  # Suited to I/O-bound work such as shelling out to external tools: while a
+  # worker thread blocks on a subprocess, Ruby releases the GIL so other
+  # workers make real progress.
+  class ConcurrentExecutor
+    ##
+    # @param [Integer, nil] max_workers explicit worker cap, or nil to use configuration
+    def initialize(max_workers: nil)
+      @max_workers = if max_workers
+                       Configuration.max_concurrency_limit(max_workers)
+                     else
+                       Configuration.max_concurrency
+                     end
+    end
+
+    ##
+    # Map over +items+ concurrently, preserving input order.
+    # @param [Array] items work items to process
+    # @yield [item] the work performed for each item
+    # @return [Array] results aligned with +items+
+    def map(items, &block)
+      return [] if items.empty?
+      return items.map(&block) if serial?(items.size)
+
+      process(items, &block)
+    end
+
+    private
+
+    attr_reader :max_workers
+
+    ##
+    # Whether +item_count+ items should run serially rather than in a pool.
+    # @param [Integer] item_count number of work items
+    # @return [Boolean]
+    def serial?(item_count)
+      max_workers <= 1 || item_count == 1
+    end
+
+    ##
+    # Distribute +items+ across a bounded pool of worker threads.
+    # @param [Array] items work items to process
+    # @yield [item] the work performed for each item
+    # @return [Array] results aligned with +items+
+    def process(items, &block)
+      results = Array.new(items.size)
+      queue = work_queue(items)
+      run_workers(worker_count(results.size), queue, results, &block)
+      results
+    end
+
+    ##
+    # Number of workers to spawn: one per item, capped at +max_workers+.
+    # @param [Integer] item_count number of work items
+    # @return [Integer]
+    def worker_count(item_count)
+      [max_workers, item_count].min
+    end
+
+    ##
+    # Spawn +count+ worker threads that drain +queue+ into +results+, and join them.
+    # @param [Integer] count number of worker threads
+    # @param [Thread::Queue] queue source of +[index, item]+ pairs
+    # @param [Array] results destination, written by index
+    # @yield [item] the work performed for each item
+    # @return [void]
+    def run_workers(count, queue, results, &block)
+      workers = Array.new(count) { spawn_worker(queue, results, &block) }
+      workers.each(&:join)
+    end
+
+    ##
+    # Spawn one worker thread that drains +queue+ into +results+ by index.
+    # @param [Thread::Queue] queue source of +[index, item]+ pairs
+    # @param [Array] results destination, written by index
+    # @yield [item] the work performed for each item
+    # @return [Thread]
+    def spawn_worker(queue, results)
+      Thread.new do
+        Thread.current.report_on_exception = false
+        drain(queue) { |index, item| results[index] = yield(item) }
+      end
+    end
+
+    ##
+    # Build a queue of +[index, item]+ pairs for the workers to consume.
+    # @param [Array] items work items to process
+    # @return [Thread::Queue]
+    def work_queue(items)
+      queue = Thread::Queue.new
+      items.size.times { |index| queue << [index, items[index]] }
+      queue
+    end
+
+    ##
+    # Pop work off +queue+ until it is empty, yielding each pair.
+    # @param [Thread::Queue] queue source of +[index, item]+ pairs
+    # @yield [index, item] the indexed work item to process
+    # @return [void]
+    def drain(queue)
+      loop do
+        work = begin
+          queue.pop(true)
+        rescue ThreadError
+          break
+        end
+
+        yield(work)
+      end
+    end
+  end
+end

data/lib/cleo_quality_review/configuration.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
+require "etc"
 require "set"
 require "yaml"
 
 module CleoQualityReview
   ##
-  # Configuration for file include/exclude patterns
+  # Configuration for file include/exclude patterns and runtime defaults
   class Configuration
     DEFAULT_CONFIG_PATH = File.expand_path("../../config/default.yml", __dir__)
     LOCAL_CONFIG_PATH = ".cleo_quality_review.yaml"
@@ -24,6 +25,36 @@ module CleoQualityReview
       Loader.new(root: root).load
     end
 
+    ##
+    # Resolve the configured worker count for concurrent checks.
+    # @return [Integer] resolved worker count (at least 1)
+    def self.max_concurrency
+      max_concurrency_limit(env_max_concurrency || default_max_concurrency)
+    end
+
+    ##
+    # Clamp a worker count to a usable lower bound.
+    # @param [Integer] value worker count to clamp
+    # @return [Integer] clamped worker count
+    def self.max_concurrency_limit(value)
+      [value.to_i, 1].max
+    end
+
+    ##
+    # Read the max worker count from the environment, if configured.
+    # @return [Integer, nil] the configured count, or nil when unset/blank
+    # @raise [ArgumentError] if the environment value is not an integer
+    def self.env_max_concurrency
+      value = ENV["CLEO_QUALITY_REVIEW_MAX_CONCURRENCY"]
+      value && !value.strip.empty? ? Integer(value) : nil
+    end
+
+    ##
+    # @return [Integer] host processor count used as the default worker cap
+    def self.default_max_concurrency
+      Etc.nprocessors
+    end
+
     ##
     # @param [Hash] data parsed configuration data
     def initialize(data)

data/lib/cleo_quality_review/formatter.rb

@@ -10,6 +10,10 @@ module CleoQualityReview
   ##
   # Formats quality review results using an LLM with format-specific prompts
   class Formatter
+    ##
+    # Format name of the shared configuration prompt applied to every run
+    CONFIGURATION_FORMAT = "configuration"
+
     ##
     # @param [Run] run the quality review run to format
     # @param [CommandRunner] command_runner for executing shell commands
@@ -23,10 +27,14 @@ module CleoQualityReview
     end
 
     ##
-    # Format the run by generating an LLM review
-    # @return [String] formatted review text
+    # Format the run by generating an LLM review. Returns an empty string
+    # without contacting the LLM when there are no files to review.
+    # @return [String] formatted review text, or an empty string when there is
+    #   nothing to review
     def format
-      llm_client.generate_review(prompt)
+      return "" unless run.reviewable?
+
+      llm_client.generate_review(prompt, instructions: configuration_prompt)
     end
 
     private
@@ -43,6 +51,13 @@ module CleoQualityReview
       ).build
     end
 
+    ##
+    # Shared review rules applied to every run regardless of output format.
+    # @return [String]
+    def configuration_prompt
+      PromptLoader.load(format: CONFIGURATION_FORMAT)
+    end
+
     ##
     # @return [RunArtifacts]
     def artifacts

data/lib/cleo_quality_review/github_client.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module CleoQualityReview
+  ##
+  # Thin authenticated HTTP client for the GitHub REST API
+  class GitHubClient
+    API_VERSION = "2022-11-28"
+    DEFAULT_API_URL = "https://api.github.com"
+
+    ##
+    # Wrapped HTTP response
+    #
+    # @!attribute [r] status_code
+    #   @return [Integer] HTTP status code
+    # @!attribute [r] body
+    #   @return [String] raw response body
+    Response = Struct.new(:status_code, :body, keyword_init: true) do
+      ##
+      # @return [Boolean] whether the response status is in the 2xx range
+      def success?
+        (200..299).cover?(status_code.to_i)
+      end
+    end
+
+    ##
+    # @param [String] token GitHub API token
+    # @param [String] api_url base GitHub API URL
+    def initialize(token:, api_url: DEFAULT_API_URL)
+      @token = token
+      @api_url = api_url.to_s.strip.empty? ? DEFAULT_API_URL : api_url
+    end
+
+    ##
+    # Perform an authenticated GET request
+    # @param [String] path API path beginning with "/"
+    # @return [Response]
+    def get(path)
+      request_json(:get, uri_for(path))
+    end
+
+    ##
+    # Perform an authenticated POST request
+    # @param [String] path API path beginning with "/"
+    # @param [Hash] body request body serialised as JSON
+    # @return [Response]
+    def post(path, body)
+      request_json(:post, uri_for(path), body)
+    end
+
+    private
+
+    attr_reader :token, :api_url
+
+    def uri_for(path)
+      URI("#{api_url}#{path}")
+    end
+
+    def request_json(method, uri, body = nil)
+      wrap_response(perform_request(uri, build_request(method, uri, body)))
+    end
+
+    def build_request(method, uri, body)
+      request = request_class(method).new(uri)
+      apply_headers(request)
+      request.body = JSON.generate(body) if body
+      request
+    end
+
+    def request_class(method)
+      {
+        get: Net::HTTP::Get,
+        post: Net::HTTP::Post,
+      }.fetch(method) { raise ArgumentError, "Unsupported HTTP method #{method.inspect}" }
+    end
+
+    def apply_headers(request)
+      github_headers.each { |key, value| request[key] = value }
+    end
+
+    def github_headers
+      {
+        "Accept" => "application/vnd.github+json",
+        "Authorization" => "Bearer #{token}",
+        "Content-Type" => "application/json",
+        "User-Agent" => "cleo-quality-review",
+        "X-GitHub-Api-Version" => API_VERSION,
+      }
+    end
+
+    def perform_request(uri, request)
+      Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
+        http.request(request)
+      end
+    end
+
+    def wrap_response(response)
+      Response.new(status_code: response.code.to_i, body: response.body.to_s)
+    end
+  end
+end

data/lib/cleo_quality_review/github_review_builder.rb

@@ -95,12 +95,20 @@ module CleoQualityReview
     end
 
     def parsed_review
-      @parsed_review ||= begin
-        parsed = JSON.parse(rendered_review.to_s)
-        raise Error, "pr_review JSON must be an object" unless parsed.is_a?(Hash)
+      @parsed_review ||= parse_rendered_review
+    end
 
-        parsed
-      end
+    # A blank rendered review (e.g. the render step produced no output because
+    # there were no reviewable changes) means there is nothing to publish, so
+    # treat it as an empty review rather than failing to parse it as JSON.
+    def parse_rendered_review
+      content = rendered_review.to_s.strip
+      return {} if content.empty?
+
+      parsed = JSON.parse(content)
+      raise Error, "pr_review JSON must be an object" unless parsed.is_a?(Hash)
+
+      parsed
     rescue JSON::ParserError => e
       raise Error, "pr_review output was not valid JSON: #{e.message}"
     end

data/lib/cleo_quality_review/github_review_publisher.rb

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 
 require "json"
-require "net/http"
-require "uri"
 
+require_relative "github_client"
 require_relative "github_review_builder"
 require_relative "llm_errors"
 
@@ -11,16 +10,16 @@ module CleoQualityReview
   ##
   # Publishes quality review findings as a GitHub pull request review
   class GitHubReviewPublisher
-    API_VERSION = "2022-11-28"
-
     ##
     # @param [Run] run completed quality review run
     # @param [String] rendered_review JSON produced by the pr_review formatter
     # @param [Hash{String => String}] env process environment
-    def initialize(run:, rendered_review:, env: ENV)
+    # @param [GitHubClient, nil] client GitHub API client (built from env when omitted)
+    def initialize(run:, rendered_review:, env: ENV, client: nil)
       @run = run
       @rendered_review = rendered_review
       @env = env
+      @client = client
     end
 
     ##
@@ -45,22 +44,16 @@ module CleoQualityReview
     end
 
     def post_review
-      response = request_json(:post, reviews_uri, builder.payload(commit_id: head_sha))
+      response = client.post(reviews_path, builder.payload(commit_id: head_sha))
       raise Error, "GitHub PR review publication failed with status #{response.status_code}: #{response.body}" unless response.success?
 
       "Published PR review for review ID #{run.review_id}."
     end
 
-    GitHubResponse = Struct.new(:status_code, :body, keyword_init: true) do
-      def success?
-        (200..299).cover?(status_code.to_i)
-      end
-    end
-
     attr_reader :env, :rendered_review, :run
 
     def already_published?
-      response = request_json(:get, reviews_uri)
+      response = client.get(reviews_path)
       body = response.body
       raise Error, "GitHub PR review lookup failed with status #{response.status_code}: #{body}" unless response.success?
 
@@ -69,6 +62,10 @@ module CleoQualityReview
       end
     end
 
+    def client
+      @client ||= GitHubClient.new(token: token, api_url: api_url)
+    end
+
     def builder
       @builder ||= GitHubReviewBuilder.new(run: run, rendered_review: rendered_review)
     end
@@ -77,8 +74,8 @@ module CleoQualityReview
       event.fetch("pull_request", nil).is_a?(Hash)
     end
 
-    def reviews_uri
-      URI("#{api_url}/repos/#{repository}/pulls/#{pull_request_number}/reviews")
+    def reviews_path
+      "/repos/#{repository}/pulls/#{pull_request_number}/reviews"
     end
 
     def pull_request_number
@@ -104,47 +101,5 @@ module CleoQualityReview
     def token
       env.fetch("GITHUB_TOKEN")
     end
-
-    def request_json(method, uri, body = nil)
-      wrap_response(perform_request(uri, build_request(method, uri, body)))
-    end
-
-    def build_request(method, uri, body)
-      request = request_class(method).new(uri)
-      apply_headers(request)
-      request.body = JSON.generate(body) if body
-      request
-    end
-
-    def request_class(method)
-      {
-        get: Net::HTTP::Get,
-        post: Net::HTTP::Post,
-      }.fetch(method) { raise ArgumentError, "Unsupported HTTP method #{method.inspect}" }
-    end
-
-    def apply_headers(request)
-      github_headers.each { |key, value| request[key] = value }
-    end
-
-    def github_headers
-      {
-        "Accept" => "application/vnd.github+json",
-        "Authorization" => "Bearer #{token}",
-        "Content-Type" => "application/json",
-        "User-Agent" => "cleo-quality-review",
-        "X-GitHub-Api-Version" => API_VERSION,
-      }
-    end
-
-    def perform_request(uri, request)
-      Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
-        http.request(request)
-      end
-    end
-
-    def wrap_response(response)
-      GitHubResponse.new(status_code: response.code.to_i, body: response.body.to_s)
-    end
   end
 end