cleo_quality_review 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f7c748370590a154e611c6302e8bbfd9e5c3f8dc1b756e938ccba09101b6ee5
-  data.tar.gz: 85e837b45af4b31c23e9f59d613653a481a5e172da0581df8edc96945c4f409c
+  metadata.gz: 85099120967159c27f15cfa154de5e081e125b08c6c2e3e910081d392caafa04
+  data.tar.gz: 7b7e772fa82cabf8ef0add3a6c39af9c16a0a02d95648f1060716b750eac9ac1
 SHA512:
-  metadata.gz: 7f5f53a18a2cd9ef9e6e7c3456b416d4b2f0dcab0d36d3c4d75e70c1c97bb408659918c89d57ab284faf05e7111cd06f0fc39f34f1be0d08f611f48945fe9ace
-  data.tar.gz: dabda2763af548f1ef2be712d6b3a0ec8ca1ca03330a249ea91b35972176a3f37785677dd39334ff207aae8374d586358a0c1c3a1a402f0e9ac94ab1c4dadff5
+  metadata.gz: '01243971003bf84478a7b7b73b2c12d6870bda49717e41b6d91333f83b3f0adce57dff6d646b0610734313f197375321bd8d788e744c7b04bae290dfd489ded1'
+  data.tar.gz: 7b839841dff2747bd7560b724fa06bbcb8e904b6577bfe25535e0351f2365d0a6b6787d2e116bee9528fdbba74e7047ee592241d22a34ed53b1e9089fbf0462d

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/cli.rb

@@ -5,7 +5,8 @@ require "optparse"
 require_relative "../cleo_quality_review"
 require_relative "command_runner"
 require_relative "formatter"
-require_relative "github_review_publisher"
+require_relative "sticky_comment_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)
@@ -86,7 +95,7 @@ module CleoQualityReview
     def run_publish_pr_review(arguments)
       options = Options.parse(arguments)
       run = RunArtifacts.load(review_id: options.validated_review_id).to_run(**options.run_loading_params)
-      output = GitHubReviewPublisher.new(run: run, rendered_review: rendered_pr_review(options, run)).publish
+      output = StickyCommentPublisher.new(run: run, rendered_review: rendered_pr_review(options, run)).publish
       print_output(output)
       0
     end

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,114 @@
+# 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
+
+    ##
+    # Perform an authenticated PATCH request
+    # @param [String] path API path beginning with "/"
+    # @param [Hash] body request body serialised as JSON
+    # @return [Response]
+    def patch(path, body)
+      request_json(:patch, 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,
+        patch: Net::HTTP::Patch,
+      }.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/incremental_base_resolver.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "github_client"
+require_relative "llm_errors"
+require_relative "sticky_comment_builder"
+
+module CleoQualityReview
+  ##
+  # Resolves the git base for an incremental review.
+  #
+  # On a pull request that cleo-quality-review has already reviewed, this
+  # returns the previously-reviewed commit recorded on the sticky pull request
+  # comment, provided it is still an ancestor of the current head, so only
+  # changes made since that review are analysed. It falls back to +nil+
+  # (meaning "review the full diff") outside a pull request context, when no
+  # sticky comment survives in history, or on any lookup error.
+  class IncrementalBaseResolver
+    MARKER_PREFIX = StickyCommentBuilder::MARKER_PREFIX
+    COMMIT_PATTERN = /#{Regexp.escape(MARKER_PREFIX)}\s*commit=(\S+)\s*-->/
+    DISABLED_VALUES = %w[0 false no off].freeze
+    ENABLED_ENV_KEY = "CLEO_QUALITY_REVIEW_INCREMENTAL"
+    COMMENTS_PER_PAGE = 100
+    MAX_COMMENT_PAGES = 20
+
+    ##
+    # @param [CommandRunner] command_runner for executing git commands
+    # @param [Hash{String => String}] env process environment
+    # @param [GitHubClient, nil] client GitHub API client (built from env when omitted)
+    def initialize(command_runner:, env: ENV, client: nil)
+      @command_runner = command_runner
+      @env = env
+      @client = client
+    end
+
+    ##
+    # Resolve the incremental base commit.
+    # @param [String] head git ref for the current head
+    # @return [String, nil] commit SHA to diff against, or nil to review the full diff
+    def resolve(head: "HEAD")
+      return nil unless incremental_lookup_available?
+
+      reviewed_commit(head)
+    rescue StandardError => error
+      warn("cleo-quality-review: incremental base lookup failed (#{error.message}); reviewing the full diff")
+      nil
+    end
+
+    private
+
+    attr_reader :command_runner, :env
+
+    ##
+    # @return [Boolean] whether an incremental lookup can run in this context
+    def incremental_lookup_available?
+      enabled? && !pull_request_number.nil? && !token.nil? && !repository.nil?
+    end
+
+    def reviewed_commit(head)
+      sha = sticky_comment_commit_sha
+      sha if sha && ancestor?(sha, head)
+    end
+
+    def sticky_comment_commit_sha
+      sticky_comment = comments.find { |comment| quality_review?(comment) }
+      sticky_comment && sticky_comment.fetch("body").to_s[COMMIT_PATTERN, 1]
+    end
+
+    ##
+    # Fetch every issue comment, following pagination so our sticky comment is
+    # not missed on pull requests with more than one page of comments.
+    # @return [Array<Hash>]
+    def comments
+      (1..MAX_COMMENT_PAGES).each_with_object([]) do |page, all|
+        page_comments = comments_page(page)
+        all.concat(page_comments)
+        break all if page_comments.length < COMMENTS_PER_PAGE
+      end
+    end
+
+    def comments_page(page)
+      response = client.get("/repos/#{repository}/issues/#{pull_request_number}/comments?per_page=#{COMMENTS_PER_PAGE}&page=#{page}")
+      raise Error, "GitHub comment lookup returned status #{response.status_code}" unless response.success?
+
+      parsed = JSON.parse(response.body)
+      parsed.is_a?(Array) ? parsed : []
+    end
+
+    ##
+    # Only trust a bot-authored comment that carries our marker.
+    # @param [Hash] comment
+    # @return [Boolean]
+    def quality_review?(comment)
+      bot_authored?(comment) && marked?(comment)
+    end
+
+    def bot_authored?(comment)
+      comment.dig("user", "type") == "Bot"
+    end
+
+    def marked?(comment)
+      comment.fetch("body") { "" }.to_s.include?(MARKER_PREFIX)
+    end
+
+    def ancestor?(sha, head)
+      command_runner.run("git", "merge-base", "--is-ancestor", sha, head).success?
+    end
+
+    def enabled?
+      !DISABLED_VALUES.include?(env.fetch(ENABLED_ENV_KEY) { "" }.to_s.strip.downcase)
+    end
+
+    def pull_request_number
+      return @pull_request_number if defined?(@pull_request_number)
+
+      @pull_request_number = event && (event["number"] || event.dig("pull_request", "number"))
+    end
+
+    def event
+      return @event if defined?(@event)
+
+      @event = load_event
+    end
+
+    def load_event
+      path = env["GITHUB_EVENT_PATH"]
+      return nil if path.to_s.empty? || !File.file?(path)
+
+      JSON.parse(File.read(path))
+    rescue JSON::ParserError
+      nil
+    end
+
+    def token
+      value = env["GITHUB_TOKEN"].to_s
+      value unless value.empty?
+    end
+
+    def repository
+      value = env["GITHUB_REPOSITORY"].to_s
+      value unless value.empty?
+    end
+
+    def api_url
+      env.fetch("GITHUB_API_URL") { GitHubClient::DEFAULT_API_URL }
+    end
+
+    def client
+      @client ||= GitHubClient.new(token: token, api_url: api_url)
+    end
+  end
+end

data/lib/cleo_quality_review/llm_client.rb

@@ -19,10 +19,12 @@ module CleoQualityReview
 
     ##
     # Generate a review from the given prompt
-    # @param [String] prompt
+    # @param [String] prompt the format-specific prompt sent as input
+    # @param [String, nil] instructions shared configuration prompt applied to
+    #   every run
     # @return [String] the generated review
-    def generate_review(prompt)
-      generate_with_logging(prompt)
+    def generate_review(prompt, instructions: nil)
+      generate_with_logging(prompt, instructions)
     rescue StandardError => e
       log_error(prompt, e)
       raise
@@ -32,8 +34,10 @@ module CleoQualityReview
 
     attr_reader :config, :logger
 
-    def generate_with_logging(prompt)
-      provider_client.generate_review(prompt).tap { |response| log_success(prompt, response) }
+    def generate_with_logging(prompt, instructions)
+      provider_client.generate_review(prompt, instructions: instructions).tap do |response|
+        log_success(prompt, response)
+      end
     end
 
     def log_success(prompt, response)

data/lib/cleo_quality_review/llm_providers/open_ai.rb

@@ -89,11 +89,13 @@ module CleoQualityReview
 
         ##
         # Generate a review using the OpenAI Responses API.
-        # @param [String] prompt the prompt to send
+        # @param [String] prompt the format-specific prompt to send as input
+        # @param [String, nil] instructions shared configuration prompt sent as
+        #   the system-level instructions applied to every run
         # @return [String] generated review text
         # @raise [ApiError] if the API request fails
-        def generate_review(prompt)
-          response = execute_request(prompt)
+        def generate_review(prompt, instructions: nil)
+          response = execute_request(request_body(prompt, instructions))
           parse_response(response)
         end
 
@@ -101,9 +103,9 @@ module CleoQualityReview
 
         attr_reader :config, :http_transport
 
-        def execute_request(prompt)
+        def execute_request(body)
           timeout_seconds = config.timeout_seconds
-          http_transport.post_json(build_request(prompt, timeout_seconds))
+          http_transport.post_json(build_request(body, timeout_seconds))
         rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout => e
           raise ApiError, timeout_error_message(timeout_seconds, e)
         end
@@ -116,15 +118,21 @@ module CleoQualityReview
           raise ApiError, "OpenAI Responses API returned invalid JSON: #{e.message}"
         end
 
-        def build_request(prompt, timeout_seconds)
+        def build_request(body, timeout_seconds)
           HttpRequest.new(
             uri: RESPONSES_API_URL,
             headers: headers,
-            body: { model: config.model, input: prompt },
+            body: body,
             timeout_seconds: timeout_seconds,
           )
         end
 
+        def request_body(prompt, instructions)
+          body = { model: config.model, input: prompt }
+          body[:instructions] = instructions unless instructions.to_s.strip.empty?
+          body
+        end
+
         def timeout_error_message(timeout_seconds, error)
           "OpenAI Responses API request timed out after #{timeout_seconds} seconds: #{error.class}: #{error.message}"
         end