cleo_quality_review 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f7c748370590a154e611c6302e8bbfd9e5c3f8dc1b756e938ccba09101b6ee5
-  data.tar.gz: 85e837b45af4b31c23e9f59d613653a481a5e172da0581df8edc96945c4f409c
+  metadata.gz: 9277c83af1fccd6045fde0ef6879b6fa7d9d2fc0d1848e1401d58f1889a6c458
+  data.tar.gz: c2d158fd19d8566edad3556ed46b020c34ec2a2c7ade2199d3b06b2c612b1e6c
 SHA512:
-  metadata.gz: 7f5f53a18a2cd9ef9e6e7c3456b416d4b2f0dcab0d36d3c4d75e70c1c97bb408659918c89d57ab284faf05e7111cd06f0fc39f34f1be0d08f611f48945fe9ace
-  data.tar.gz: dabda2763af548f1ef2be712d6b3a0ec8ca1ca03330a249ea91b35972176a3f37785677dd39334ff207aae8374d586358a0c1c3a1a402f0e9ac94ab1c4dadff5
+  metadata.gz: 6fbd671e9068c52268bf5f2d139817a330919c630ebe59773e785a2e25f5fa8039eb34280ad0b58cb31de984404ee8b59ab5deb4469d9246a60f59f088ccbb6d
+  data.tar.gz: 37731db93423a4da4948a00ab7550809d6f9a1dabc69cb313e2ba066e6239fe0160b3a12c560da66976ecf324d344eee5398cd95b0b1778b4ea07441d46620f1

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

@@ -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

data/lib/cleo_quality_review/incremental_base_resolver.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "github_client"
+require_relative "llm_errors"
+
+module CleoQualityReview
+  ##
+  # Resolves the git base for an incremental review.
+  #
+  # On a pull request that cleo-quality-review has already reviewed, this
+  # returns the most recent previously-reviewed commit that 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 prior review survives in history, or on any
+  # lookup error.
+  class IncrementalBaseResolver
+    REVIEW_MARKER_PREFIX = "<!-- cleo-quality-review:"
+    DISABLED_VALUES = %w[0 false no off].freeze
+    ENABLED_ENV_KEY = "CLEO_QUALITY_REVIEW_INCREMENTAL"
+    REVIEWS_PER_PAGE = 100
+    MAX_REVIEW_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?
+
+      newest_reviewed_ancestor(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 newest_reviewed_ancestor(head)
+      reviewed_commit_ids.find { |sha| ancestor?(sha, head) }
+    end
+
+    def reviewed_commit_ids
+      reviews
+        .select { |review| quality_review?(review) }
+        .sort_by { |review| review["submitted_at"].to_s }
+        .reverse
+        .filter_map { |review| review["commit_id"] }
+        .reject { |sha| sha.to_s.strip.empty? }
+        .uniq
+    end
+
+    ##
+    # Fetch every submitted review, following pagination so the newest reviews
+    # are not missed on pull requests with more than one page of reviews.
+    # @return [Array<Hash>]
+    def reviews
+      (1..MAX_REVIEW_PAGES).each_with_object([]) do |page, all|
+        page_reviews = reviews_page(page)
+        all.concat(page_reviews)
+        break all if page_reviews.length < REVIEWS_PER_PAGE
+      end
+    end
+
+    def reviews_page(page)
+      response = client.get("/repos/#{repository}/pulls/#{pull_request_number}/reviews?per_page=#{REVIEWS_PER_PAGE}&page=#{page}")
+      raise Error, "GitHub review lookup returned status #{response.status_code}" unless response.success?
+
+      parsed = JSON.parse(response.body)
+      parsed.is_a?(Array) ? parsed : []
+    end
+
+    ##
+    # Only trust bot-authored reviews that carry our marker. A human contributor
+    # could otherwise forge the marker in their own review and steer the base
+    # past changes the tool never analysed.
+    # @param [Hash] review
+    # @return [Boolean]
+    def quality_review?(review)
+      bot_authored?(review) && marked?(review)
+    end
+
+    def bot_authored?(review)
+      review.dig("user", "type") == "Bot"
+    end
+
+    def marked?(review)
+      review.fetch("body") { "" }.to_s.include?(REVIEW_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

data/lib/cleo_quality_review/llm_providers/stub.rb

@@ -54,21 +54,25 @@ module CleoQualityReview
       ##
       # Stub LLM client, mirrors OpenAi::Client interface.
       class Client
-        attr_reader :received_prompts
+        attr_reader :received_prompts, :received_instructions
 
         ##
         # @param [Config] config stub configuration
         def initialize(config:)
           @config = config
           @received_prompts = []
+          @received_instructions = []
         end
 
         ##
         # Generate a review by returning the configured response.
-        # @param [String] prompt the prompt sent
+        # @param [String] prompt the format-specific prompt sent as input
+        # @param [String, nil] instructions shared configuration prompt applied
+        #   to every run
         # @return [String] the configured response
-        def generate_review(prompt)
+        def generate_review(prompt, instructions: nil)
           received_prompts << prompt
+          received_instructions << instructions
           response = config.response
 
           case response

data/lib/cleo_quality_review/options.rb

@@ -25,7 +25,9 @@ module CleoQualityReview
     #   @return [Array<String>] checks to exclude
     # @!attribute [r] changed
     #   @return [Boolean] whether to filter to changed files only
-    ParseResult = Struct.new(:format, :checks, :files, :exclude, :changed, :base, :log, :review_id, :review_file, keyword_init: true) do
+    # @!attribute [r] jobs
+    #   @return [Integer, nil] max checks to run in parallel, or nil to auto-size
+    ParseResult = Struct.new(:format, :checks, :files, :exclude, :changed, :base, :log, :review_id, :review_file, :jobs, keyword_init: true) do
       ##
       # @return [String] validated review_id
       # @raise [OptionParser::MissingArgument] if review_id is blank
@@ -64,6 +66,7 @@ module CleoQualityReview
       @log = false
       @review_id = nil
       @review_file = nil
+      @jobs = nil
     end
 
     ##
@@ -85,17 +88,19 @@ module CleoQualityReview
         log: log,
         review_id: review_id,
         review_file: review_file,
+        jobs: jobs,
       )
     end
 
     private
 
-    attr_reader :argv, :format, :checks, :files, :exclude, :changed, :base, :log, :review_id, :review_file
+    attr_reader :argv, :format, :checks, :files, :exclude, :changed, :base, :log, :review_id, :review_file, :jobs
 
     def parser
       OptionParser.new do |opts|
         opts.banner = "Usage: check_quality [options] [files...]"
         register_options(opts)
+        register_help_option(opts)
       end
     end
 
@@ -104,7 +109,13 @@ module CleoQualityReview
       register_check_options(opts)
       register_target_options(opts)
       register_output_options(opts)
-      register_help_option(opts)
+      register_jobs_option(opts)
+    end
+
+    def register_jobs_option(opts)
+      opts.on("-j", "--jobs N", Integer, "Max checks to run in parallel (default: CPU cores)") do |value|
+        @jobs = value
+      end
     end
 
     def register_format_option(opts)

data/lib/cleo_quality_review/run.rb

@@ -38,6 +38,14 @@ module CleoQualityReview
     :log,
     keyword_init: true,
   ) do
+    ##
+    # Whether the run has any files to review. Runs with no target files
+    # (e.g. a branch that only changes non-Ruby files) have nothing to analyse.
+    # @return [Boolean]
+    def reviewable?
+      !Array(target_files).empty?
+    end
+
     ##
     # Convert the run to a hash representation
     # @return [Hash{Symbol => Object}]

data/lib/cleo_quality_review/runner.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
 require "digest"
+require "forwardable"
 require "json"
 
 require_relative "changes_diff"
 require_relative "checks"
 require_relative "command_runner"
+require_relative "concurrent_executor"
 require_relative "git_diff_base"
 require_relative "run"
 require_relative "run_artifacts"
@@ -15,6 +17,8 @@ module CleoQualityReview
   ##
   # Orchestrates a complete quality review run
   class Runner
+    extend Forwardable
+
     ##
     # Grouped values resolved at the start of an analysis run
     AnalysisContext = Struct.new(:timestamp, :base_ref, :target, :changes, :review_id, :check_classes, keyword_init: true) do
@@ -32,16 +36,28 @@ module CleoQualityReview
       end
     end
 
+    ##
+    # Runtime collaborators for a quality review run
+    Dependencies = Struct.new(:command_runner, :clock, :check_registry, :base_resolver, :executor, keyword_init: true) do
+      def self.for(options, overrides)
+        new(
+          **{
+            command_runner: CommandRunner.new,
+            clock: Time,
+            check_registry: Checks,
+            base_resolver: nil,
+            executor: ConcurrentExecutor.new(max_workers: options.jobs),
+          }.merge(overrides),
+        )
+      end
+    end
+
     ##
     # @param [Options::ParseResult] options parsed command-line options
-    # @param [CommandRunner] command_runner for executing shell commands
-    # @param [#now] clock time source for timestamps
-    # @param [CheckRegistry] check_registry registry for resolving check names
-    def initialize(options:, command_runner: CommandRunner.new, clock: Time, check_registry: Checks)
+    # @param [Hash] dependencies optional runtime collaborators for tests or alternate runners
+    def initialize(options:, **dependencies)
       @options = options
-      @command_runner = command_runner
-      @clock = clock
-      @check_registry = check_registry
+      @dependencies = Dependencies.for(options, dependencies)
     end
 
     ##
@@ -57,7 +73,9 @@ module CleoQualityReview
 
     private
 
-    attr_reader :options, :command_runner, :clock, :check_registry
+    attr_reader :options, :dependencies
+    def_delegators :dependencies, :command_runner, :clock, :check_registry, :base_resolver, :executor
+    private :command_runner, :clock, :check_registry, :base_resolver, :executor
 
     def epoch_milliseconds
       (clock.now.to_r * 1_000).to_i
@@ -127,7 +145,9 @@ module CleoQualityReview
     end
 
     def run_checks(check_classes, ruby_files, timestamp)
-      check_classes.map do |check_class|
+      return [] if ruby_files.empty?
+
+      executor.map(check_classes) do |check_class|
         check_class.new(command_runner: command_runner, timestamp: timestamp).run(ruby_files)
       end
     end
@@ -170,6 +190,10 @@ module CleoQualityReview
     end
 
     def base_ref
+      @base_ref ||= base_resolver&.resolve || default_base_ref
+    end
+
+    def default_base_ref
       options.base || GitDiffBase::DEFAULT_BASE_REF
     end
   end

data/lib/cleo_quality_review/version.rb

@@ -3,5 +3,5 @@
 module CleoQualityReview
   ##
   # Gem version
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/prompts/agent.md

@@ -1,12 +1,8 @@
 You are reviewing Ruby code quality findings for consumption by AI coding assistants.
 
-Analyze the raw tool outputs and git diff provided. Prioritize actionable issues affecting maintainability, readability, performance, and complexity. Filter out low-signal findings.
-
-## Tool Thresholds
-
-- **Flog**: Ignore scores below 40.0
-- **Reek**: Focus on FeatureEnvy, TooManyStatements, DuplicateMethodCall, NestedIterators, LongParameterList
-- **Fasterer**: Include all performance suggestions
+Apply the shared review rules from the configuration prompt provided alongside this one.
+That prompt defines the inputs, tool thresholds, prioritisation, and noise-reduction rules.
+This prompt defines only the output format.
 
 ## Output Format
 
@@ -43,10 +39,8 @@ Output valid JSON matching this exact schema:
 }
 ```
 
-## Guidelines
+## Output rules
 
-1. Include only findings that exceed thresholds and are actionable
-2. Order findings by priority: high-complexity methods first, then code smells, then performance
-3. Write concise `result` descriptions an agent can act on
-4. Include the raw check outputs in `check_outputs` for reference
-5. Output ONLY valid JSON - no markdown fences, no explanatory text
+1. Write concise `result` descriptions an agent can act on.
+2. Include the raw check outputs in `check_outputs` for reference.
+3. Output ONLY valid JSON - no markdown fences, no explanatory text.

data/prompts/configuration.md

@@ -0,0 +1,47 @@
+You are reviewing Ruby code quality findings produced by static analysis tools.
+
+These are the standard rules that apply to every review, regardless of the output format.
+The output format is defined separately in the format-specific prompt that accompanies these rules.
+
+## Inputs
+
+You are given the raw output from a series of code quality tools (including, but not limited to, Reek, Flog, Fasterer, Flay, and Brakeman), together with the git diff for the change under review.
+The combined tool output is noisy.
+Your job is to decide what genuinely matters and to discard the rest.
+The diff is provided so you can map tool findings to the lines that changed.
+
+## Excluded files
+
+Do not review test files: ignore every tool finding that points to one, and never post a comment on a test file.
+Test files are those inside a `test/` or `spec/` directory, for example `test/models/user_test.rb`.
+A file that merely has `test` in its name but lives in application code, such as an A/B-test model under `app/`, is not a test file.
+Tests in this codebase are intentionally verbose and self-contained, so the smells these tools report on them are expected rather than defects.
+
+## Tool thresholds and severity
+
+- **Flog**: Ignore scores below 40.0. Treat high-complexity methods as the most important findings because they are the most expensive to maintain.
+- **Reek**: Prefer actionable smells such as FeatureEnvy, DuplicateMethodCall, NestedIterators, and LongParameterList.
+- **Fasterer**: Low severity. Include a performance suggestion only when it clearly applies to code changed by this review and the fix is straightforward.
+
+## Rule-specific guidance
+
+These notes refine how individual rules should be treated.
+Where a note here conflicts with the general guidance above, the note takes precedence for that rule.
+
+### Reek: TooManyStatements
+
+- Deprioritise this smell in application code.
+  Only surface it when the method is a particularly egregious example, such as a long method that clearly juggles several unrelated responsibilities, and omit it otherwise.
+
+## Prioritisation
+
+1. Prioritise issues that affect maintainability, correctness, readability, performance, and long-term ownership.
+2. Order findings by impact: high-complexity methods first, then code smells, then performance suggestions.
+3. Filter out low-signal findings.
+
+## Noise reduction
+
+- Do not comment on the code diff itself unless the comment is directly supported by a tool finding.
+- Do not repeat tool output mechanically. When several findings are of the same kind, highlight a couple of representative examples and then make one general recommendation.
+- If a finding is low value, stale, ambiguous, or a likely false positive, omit it or note it briefly.
+- Keep every finding concise and actionable, specific enough for an engineer or coding agent to act on.

data/prompts/github.md

@@ -1,22 +1,12 @@
 You are the pipeline interface between a series of code reviews for a git diff, and the GitHub Actions automation pipeline.
 
-You will collate data about code from multiple code sources (including, but not limited to Flog, Flay, Reek, Fasterer, Brakeman, etc.), and produce useful, meaningful output for the engineer whose PR has triggered this flow.
+Apply the shared review rules from the configuration prompt provided alongside this one.
+That prompt defines the inputs, tool thresholds, prioritisation, and noise-reduction rules.
+This prompt defines only the output format.
 
-The output from all of these reports together is very noisy, and so your role is to determine what is the most important things to report back on the PR, and what items can be disregarded.
-
-For weighting, consider the following values as guides:
-
-Flog:
-  Threshold: 40.0
-  ThresholdType: GreaterThanOrEqual
-  Severity: Medium to High
-
-Reek:
-  Severity: Low to Medium
-
-Fasterer:
-  Severity: Low
+You produce useful, meaningful output for the engineer whose PR triggered this flow.
 
+## Output Format
 
 You MUST NOT return so many items that the feedback is noisy and confusing. Limit yourself to maximum 10 comments.
 

data/prompts/human.md

@@ -1,17 +1,10 @@
 You are reviewing a local code change for code quality.
 
-The files provided include git diffs for local code changes, as well as generated output files from various code quality assessment tools including (but not limited to) Reek, Flog, Fasterer, etc.
-
-Your task is to parse the static output files generated by these tools, and provide feedback to the human user. The diff provided is to allow you to map tool output to changes in the code. 
-
-YOU MUST NOT comment on the code diff itself, unless the comment is in relation to an issue reported by a tool.
-
-Prioritize issues that are likely to matter to maintainability, correctness, readability, or long-term ownership. 
-
-Avoid repeating tool output mechanically. If multiple issues of the same sort are reported, it's fine to highlight a couple of examples and then make a general comment for improvement.
-
-If a tool finding is low value or likely a false positive, say so briefly or omit it.
+Apply the shared review rules from the configuration prompt provided alongside this one.
+That prompt defines the inputs, tool thresholds, prioritisation, and noise-reduction rules.
+This prompt defines only the output format.
 
+## Output Format
 
 The output will be printed in a Unix terminal, and so colour-coded feedback is preferable.
 

data/prompts/pr_review.md

@@ -1,22 +1,15 @@
 You are the pipeline interface between code quality tools and GitHub pull request review comments.
 
-You will collate data from code quality tools including Reek, Flog, and Fasterer. The raw output is noisy, so your job is to identify only the most useful comments for the engineer whose PR triggered this flow.
-
-You MUST NOT comment on the code diff itself unless the comment is directly supported by a tool finding.
-
-## Tool Thresholds
-
-- **Flog**: Ignore scores below 40.0. Prioritize high-complexity methods because they are the most expensive to maintain.
-- **Reek**: Prefer actionable smells such as FeatureEnvy, TooManyStatements, DuplicateMethodCall, NestedIterators, and LongParameterList.
-- **Fasterer**: Low severity. Include only when the finding is clearly on code changed by this PR and the fix is straightforward.
+Apply the shared review rules from the configuration prompt provided alongside this one.
+That prompt defines the inputs, tool thresholds, prioritisation, and noise-reduction rules.
+This prompt defines only the output format.
 
 ## Comment Selection
 
 1. Limit yourself to ten comments at most.
 2. Prefer findings that map directly to a changed or commentable right-side line in the git diff.
-3. Omit low-value, duplicated, stale, or ambiguous findings.
-4. If a tool finding points to a file or line that is not visible in the provided diff, omit the inline comment.
-5. Keep comments concise and actionable. Mention the tool and check name.
+3. If a tool finding points to a file or line that is not visible in the provided diff, omit the inline comment.
+4. Mention the tool and check name in each comment.
 
 ## Output Format
 
@@ -40,7 +33,7 @@ The JSON MUST match this schema:
 
 ## Comment format:
 
-The comments should prioritise readability and actionabilty. Assume the reader is a junior developer, or someone who is not familiar with the language and framework. Be helpful, without being overly verbose. 
+The comments should prioritise readability and actionabilty. Assume the reader is a junior developer, or someone who is not familiar with the language and framework. Be helpful, without being overly verbose.
 
 Example format:
 ```

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cleo_quality_review
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Gavin Morrice
@@ -74,12 +74,15 @@ files:
 - lib/cleo_quality_review/cli.rb
 - lib/cleo_quality_review/command_result.rb
 - lib/cleo_quality_review/command_runner.rb
+- lib/cleo_quality_review/concurrent_executor.rb
 - lib/cleo_quality_review/configuration.rb
 - lib/cleo_quality_review/diff_map.rb
 - lib/cleo_quality_review/formatter.rb
 - lib/cleo_quality_review/git_diff_base.rb
+- lib/cleo_quality_review/github_client.rb
 - lib/cleo_quality_review/github_review_builder.rb
 - lib/cleo_quality_review/github_review_publisher.rb
+- lib/cleo_quality_review/incremental_base_resolver.rb
 - lib/cleo_quality_review/llm_client.rb
 - lib/cleo_quality_review/llm_config.rb
 - lib/cleo_quality_review/llm_errors.rb
@@ -100,6 +103,7 @@ files:
 - lib/cleo_quality_review/target_resolver.rb
 - lib/cleo_quality_review/version.rb
 - prompts/agent.md
+- prompts/configuration.md
 - prompts/github.md
 - prompts/human.md
 - prompts/pr_review.md