cleo_quality_review 0.3.0 → 0.5.0

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "llm_errors"
+
+module CleoQualityReview
+  ##
+  # Builds the marker and body for the sticky pull request comment from
+  # rendered pr_review JSON
+  class StickyCommentBuilder
+    MARKER_PREFIX = "<!-- cleo-quality-review:"
+    MAX_BODY_LENGTH = 3_500
+    CLEAN_MESSAGE = "Cleo quality review found no high-confidence issues worth flagging on this change."
+
+    ##
+    # @param [String] rendered_review JSON produced by the pr_review formatter
+    def initialize(rendered_review:)
+      @rendered_review = rendered_review
+    end
+
+    ##
+    # @param [String] commit_sha head commit reviewed to embed in the marker
+    # @return [String] full comment body, including the hidden marker
+    def comment_body(commit_sha:)
+      [marker(commit_sha), truncate(display_body)].join("\n\n")
+    end
+
+    ##
+    # @return [Boolean] whether the rendered review has anything worth publishing
+    def empty?
+      body_text.empty?
+    end
+
+    private
+
+    attr_reader :rendered_review
+
+    def marker(commit_sha)
+      "#{MARKER_PREFIX} commit=#{commit_sha} -->"
+    end
+
+    def display_body
+      body_text.empty? ? CLEAN_MESSAGE : body_text
+    end
+
+    def body_text
+      parsed_review.fetch("body", "").to_s.strip
+    end
+
+    def parsed_review
+      @parsed_review ||= parse_rendered_review
+    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
+
+    def truncate(value)
+      return value if value.length <= MAX_BODY_LENGTH
+
+      "#{value[0, MAX_BODY_LENGTH - 20]}\n\n[truncated]"
+    end
+  end
+end

data/lib/cleo_quality_review/sticky_comment_publisher.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "github_client"
+require_relative "llm_errors"
+require_relative "sticky_comment_builder"
+
+module CleoQualityReview
+  ##
+  # Publishes quality review findings as a single sticky pull request
+  # comment, editing it in place on every run rather than posting a new one
+  class StickyCommentPublisher
+    COMMENTS_PER_PAGE = 100
+    MAX_COMMENT_PAGES = 20
+
+    ##
+    # @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
+    # @param [GitHubClient, nil] client GitHub API client (built from env when omitted)
+    def initialize(run:, rendered_review:, env: ENV, client: nil)
+      @run = run
+      @env = env
+      @client = client
+      @builder = StickyCommentBuilder.new(rendered_review: rendered_review)
+    end
+
+    ##
+    # Publish the sticky comment, or skip when there is no PR context/findings
+    # @return [String] status message
+    def publish
+      skip_reason = publication_skip_reason
+      return skip_reason if skip_reason
+
+      existing_comment_id ? update_comment : create_comment
+    end
+
+    private
+
+    attr_reader :env, :run, :builder
+
+    def publication_skip_reason
+      return "No pull_request event found; skipping sticky comment publication." unless pull_request_context?
+      return "No sticky comment to publish for review ID #{run.review_id}." if builder.empty? && existing_comment_id.nil?
+
+      nil
+    end
+
+    def create_comment
+      response = client.post(comments_path, { body: comment_body })
+      raise Error, "GitHub sticky comment creation failed with status #{response.status_code}: #{response.body}" unless response.success?
+
+      "Created sticky comment for review ID #{run.review_id}."
+    end
+
+    def update_comment
+      response = client.patch(comment_path(existing_comment_id), { body: comment_body })
+      raise Error, "GitHub sticky comment update failed with status #{response.status_code}: #{response.body}" unless response.success?
+
+      "Updated sticky comment for review ID #{run.review_id}."
+    end
+
+    def comment_body
+      builder.comment_body(commit_sha: head_sha)
+    end
+
+    def existing_comment_id
+      return @existing_comment_id if defined?(@existing_comment_id)
+
+      @existing_comment_id = find_existing_comment_id
+    end
+
+    def find_existing_comment_id
+      marked = comments.find { |comment| bot_authored?(comment) && marked?(comment) }
+      marked && marked.fetch("id")
+    end
+
+    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("#{comments_path}?per_page=#{COMMENTS_PER_PAGE}&page=#{page}")
+      raise Error, "GitHub comment lookup failed with status #{response.status_code}: #{response.body}" unless response.success?
+
+      parsed = JSON.parse(response.body)
+      parsed.is_a?(Array) ? parsed : []
+    end
+
+    def bot_authored?(comment)
+      comment.dig("user", "type") == "Bot"
+    end
+
+    def marked?(comment)
+      comment.fetch("body") { "" }.to_s.include?(StickyCommentBuilder::MARKER_PREFIX)
+    end
+
+    def client
+      @client ||= GitHubClient.new(token: token, api_url: api_url)
+    end
+
+    def pull_request_context?
+      event.fetch("pull_request", nil).is_a?(Hash)
+    end
+
+    def comments_path
+      "/repos/#{repository}/issues/#{pull_request_number}/comments"
+    end
+
+    def comment_path(comment_id)
+      "/repos/#{repository}/issues/comments/#{comment_id}"
+    end
+
+    def pull_request_number
+      event["number"] || event.fetch("pull_request").fetch("number")
+    end
+
+    def head_sha
+      event.fetch("pull_request").fetch("head").fetch("sha")
+    end
+
+    def repository
+      env.fetch("GITHUB_REPOSITORY")
+    end
+
+    def api_url
+      env.fetch("GITHUB_API_URL", "https://api.github.com")
+    end
+
+    def event
+      @event ||= JSON.parse(File.read(env.fetch("GITHUB_EVENT_PATH")))
+    end
+
+    def token
+      env.fetch("GITHUB_TOKEN")
+    end
+  end
+end

data/lib/cleo_quality_review/version.rb

@@ -3,5 +3,5 @@
 module CleoQualityReview
   ##
   # Gem version
-  VERSION = "0.3.0"
+  VERSION = "0.5.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,61 +1,62 @@
-You are the pipeline interface between code quality tools and GitHub pull request review comments.
+You are the pipeline interface between code quality tools and a single, standing summary comment on a GitHub pull request.
 
-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.
+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.
 
-You MUST NOT comment on the code diff itself unless the comment is directly supported by a tool finding.
+This comment is edited in place on every push rather than replaced or added to, and the same PR also receives GitHub Actions annotations pointing at the exact file and line of each finding.
+Do not attempt to recreate that per-line detail here.
+Write a short, consolidated narrative of the main themes across findings, then point the reader at the annotations for specifics.
 
-## Tool Thresholds
+## Summary Selection
 
-- **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.
-
-## 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.
+1. Cover at most the five most important themes.
+   Group related findings from the same tool or the same underlying cause into one theme rather than listing them separately.
+2. Mention the tool and check name for each theme, but do not centre the narrative on tool names.
+3. Do not quote line numbers or file paths; the annotations already carry that detail.
 
 ## Output Format
 
-Output ONLY valid JSON. Do not wrap it in markdown fences. Do not include explanatory text before or after the JSON.
+Output ONLY valid JSON.
+Do not wrap it in markdown fences.
+Do not include explanatory text before or after the JSON.
 
 The JSON MUST match this schema:
 
 ```json
 {
-  "body": "<short markdown summary for the PR review body>",
-  "comments": [
-    {
-      "path": "<repository-relative file path>",
-      "line": <right-side line number from the diff>,
-      "body": "<markdown review comment>"
-    }
-  ]
+  "body": "<short markdown narrative summary for the sticky PR comment>"
 }
 ```
 
+## Comment format
 
-## Comment format:
+Prioritise readability and actionability.
+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. 
+Write one short paragraph per theme.
+Separate each theme's paragraph from the next with a blank line - never merge multiple themes into a single paragraph.
+End each theme's paragraph with its own `(Ref: ...)` tag naming the tool and check.
 
 Example format:
 ```
-This code appears to have X issue. That may be likely to cause Y problem. Consider an alternative soltion, such as Z.
+This change introduces a fairly complex method that will be expensive to maintain as it grows further.
+Consider breaking it into smaller, named steps.
+
+_(Ref: Flog)_
+
+There's a repeated pattern here that could be extracted into a shared helper, which would also make the duplication easier to spot next time it happens.
 
-_(Ref: Reek TooManyStatements, DuplicateMethodCall; Fasterer HashKeysEach)_
+_(Ref: Reek DuplicateMethodCall)_
 ```
 
-## Empty output:
+## Empty output
 
-If there are no high-confidence inline comments, return:
+If there are no high-confidence findings worth reporting, return:
 
 ```json
 {
-  "body": "Cleo quality review did not find any high-confidence issues worth inline PR comments.",
-  "comments": []
+  "body": ""
 }
 ```