cleo_quality_review 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9277c83af1fccd6045fde0ef6879b6fa7d9d2fc0d1848e1401d58f1889a6c458
-  data.tar.gz: c2d158fd19d8566edad3556ed46b020c34ec2a2c7ade2199d3b06b2c612b1e6c
+  metadata.gz: 85099120967159c27f15cfa154de5e081e125b08c6c2e3e910081d392caafa04
+  data.tar.gz: 7b7e772fa82cabf8ef0add3a6c39af9c16a0a02d95648f1060716b750eac9ac1
 SHA512:
-  metadata.gz: 6fbd671e9068c52268bf5f2d139817a330919c630ebe59773e785a2e25f5fa8039eb34280ad0b58cb31de984404ee8b59ab5deb4469d9246a60f59f088ccbb6d
-  data.tar.gz: 37731db93423a4da4948a00ab7550809d6f9a1dabc69cb313e2ba066e6239fe0160b3a12c560da66976ecf324d344eee5398cd95b0b1778b4ea07441d46620f1
+  metadata.gz: '01243971003bf84478a7b7b73b2c12d6870bda49717e41b6d91333f83b3f0adce57dff6d646b0610734313f197375321bd8d788e744c7b04bae290dfd489ded1'
+  data.tar.gz: 7b839841dff2747bd7560b724fa06bbcb8e904b6577bfe25535e0351f2365d0a6b6787d2e116bee9528fdbba74e7047ee592241d22a34ed53b1e9089fbf0462d

data/lib/cleo_quality_review/cli.rb

@@ -5,7 +5,7 @@ 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"
@@ -95,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/github_client.rb

@@ -51,6 +51,15 @@ module CleoQualityReview
       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
@@ -74,6 +83,7 @@ module CleoQualityReview
       {
         get: Net::HTTP::Get,
         post: Net::HTTP::Post,
+        patch: Net::HTTP::Patch,
       }.fetch(method) { raise ArgumentError, "Unsupported HTTP method #{method.inspect}" }
     end
 

data/lib/cleo_quality_review/incremental_base_resolver.rb

@@ -4,23 +4,25 @@ 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 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.
+  # 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
-    REVIEW_MARKER_PREFIX = "<!-- cleo-quality-review:"
+    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"
-    REVIEWS_PER_PAGE = 100
-    MAX_REVIEW_PAGES = 20
+    COMMENTS_PER_PAGE = 100
+    MAX_COMMENT_PAGES = 20
 
     ##
     # @param [CommandRunner] command_runner for executing git commands
@@ -39,7 +41,7 @@ module CleoQualityReview
     def resolve(head: "HEAD")
       return nil unless incremental_lookup_available?
 
-      newest_reviewed_ancestor(head)
+      reviewed_commit(head)
     rescue StandardError => error
       warn("cleo-quality-review: incremental base lookup failed (#{error.message}); reviewing the full diff")
       nil
@@ -55,56 +57,50 @@ module CleoQualityReview
       enabled? && !pull_request_number.nil? && !token.nil? && !repository.nil?
     end
 
-    def newest_reviewed_ancestor(head)
-      reviewed_commit_ids.find { |sha| ancestor?(sha, head) }
+    def reviewed_commit(head)
+      sha = sticky_comment_commit_sha
+      sha if 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
+    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 submitted review, following pagination so the newest reviews
-    # are not missed on pull requests with more than one page of reviews.
+    # 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 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
+    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 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?
+    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 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
+    # Only trust a bot-authored comment that carries our marker.
+    # @param [Hash] comment
     # @return [Boolean]
-    def quality_review?(review)
-      bot_authored?(review) && marked?(review)
+    def quality_review?(comment)
+      bot_authored?(comment) && marked?(comment)
     end
 
-    def bot_authored?(review)
-      review.dig("user", "type") == "Bot"
+    def bot_authored?(comment)
+      comment.dig("user", "type") == "Bot"
     end
 
-    def marked?(review)
-      review.fetch("body") { "" }.to_s.include?(REVIEW_MARKER_PREFIX)
+    def marked?(comment)
+      comment.fetch("body") { "" }.to_s.include?(MARKER_PREFIX)
     end
 
     def ancestor?(sha, head)

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.4.0"
+  VERSION = "0.5.0"
 end

data/prompts/pr_review.md

@@ -1,54 +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.
 
 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
+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.
 
-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. 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.
+## Summary Selection
+
+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": ""
 }
 ```

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cleo_quality_review
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Gavin Morrice
@@ -76,12 +76,9 @@ files:
 - 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
@@ -100,6 +97,8 @@ files:
 - lib/cleo_quality_review/run_artifacts.rb
 - lib/cleo_quality_review/run_artifacts/raw_check_outputs.rb
 - lib/cleo_quality_review/runner.rb
+- lib/cleo_quality_review/sticky_comment_builder.rb
+- lib/cleo_quality_review/sticky_comment_publisher.rb
 - lib/cleo_quality_review/target_resolver.rb
 - lib/cleo_quality_review/version.rb
 - prompts/agent.md
@@ -125,7 +124,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.17
 specification_version: 4
 summary: Local Cleo code quality checks
 test_files: []

data/lib/cleo_quality_review/diff_map.rb

@@ -1,95 +0,0 @@
-# frozen_string_literal: true
-
-require "set"
-
-module CleoQualityReview
-  ##
-  # Maps a unified git diff to right-side line numbers that GitHub can comment on
-  class DiffMap
-    HUNK_HEADER = /^@@ -\d+(?:,\d+)? \+(?<line>\d+)(?:,\d+)? @@/.freeze
-
-    ##
-    # Stateful parser for file and right-side hunk line transitions
-    class DiffParser
-      def initialize(commentable_lines)
-        @commentable_lines = commentable_lines
-        @path = nil
-        @new_line = nil
-      end
-
-      def parse(diff)
-        diff.each_line { |line| parse_line(line) }
-      end
-
-      private
-
-      attr_reader :commentable_lines, :new_line, :path
-
-      def parse_line(line)
-        if line.start_with?("+++ ")
-          start_file(line)
-        elsif (line_number = hunk_start_line(line))
-          @new_line = line_number
-        elsif in_hunk?
-          parse_hunk_line(line)
-        end
-      end
-
-      def start_file(line)
-        @path = normalize_path(line.delete_prefix("+++ ").strip)
-        @new_line = nil
-      end
-
-      def hunk_start_line(line)
-        match = line.match(HUNK_HEADER)
-        match[:line].to_i if match
-      end
-
-      def in_hunk?
-        path && new_line
-      end
-
-      def parse_hunk_line(line)
-        case line[0]
-        when "+", " "
-          commentable_lines[path] << new_line
-          @new_line += 1
-        when "-"
-          new_line
-        else
-          @new_line = nil
-        end
-      end
-
-      def normalize_path(path)
-        return nil if path == "/dev/null"
-
-        path.delete_prefix("b/")
-      end
-    end
-
-    ##
-    # @param [String] diff unified git diff content
-    def initialize(diff)
-      @diff = diff.to_s
-      @commentable_lines = Hash.new { |hash, key| hash[key] = Set.new }
-      parse
-    end
-
-    ##
-    # @param [String] filepath repository-relative file path
-    # @param [Integer] line right-side line number
-    # @return [Boolean]
-    def commentable?(filepath, line)
-      commentable_lines[filepath.to_s].include?(line.to_i)
-    end
-
-    private
-
-    attr_reader :commentable_lines, :diff
-
-    def parse
-      DiffParser.new(commentable_lines).parse(diff)
-    end
-  end
-end

data/lib/cleo_quality_review/github_review_builder.rb

@@ -1,148 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-
-require_relative "diff_map"
-require_relative "llm_errors"
-
-module CleoQualityReview
-  ##
-  # Builds a GitHub pull request review payload from rendered pr_review JSON
-  class GitHubReviewBuilder
-    MAX_INLINE_COMMENTS = 20
-    MAX_BODY_LENGTH = 3_500
-
-    ##
-    # Normalized rendered comment that can be mapped onto a PR diff line
-    InlineComment = Struct.new(:path, :line, :body, keyword_init: true) do
-      def valid?
-        path != "" && line.positive? && body != ""
-      end
-
-      def commentable_on?(diff_map)
-        valid? && diff_map.commentable?(path, line)
-      end
-
-      def to_review_payload(diff_map:, truncator:)
-        return unless commentable_on?(diff_map)
-
-        { path: path, line: line, side: "RIGHT", body: truncator.call(body) }
-      end
-    end
-
-    ##
-    # @param [Run] run completed quality review run
-    # @param [String] rendered_review JSON produced by the pr_review formatter
-    def initialize(run:, rendered_review:)
-      @run = run
-      @rendered_review = rendered_review
-      @diff_map = DiffMap.new(run.artifacts.changes_diff)
-    end
-
-    ##
-    # @param [String, nil] commit_id pull request head SHA
-    # @return [Hash] GitHub pull request review payload
-    def payload(commit_id: nil)
-      comments = inline_comments
-      payload = {
-        event: "COMMENT",
-        body: review_body(comments),
-      }
-      payload[:commit_id] = commit_id if commit_id.to_s.strip != ""
-      payload[:comments] = comments unless comments.empty?
-      payload
-    end
-
-    ##
-    # @return [String] hidden marker used to avoid duplicate reviews
-    def marker
-      "<!-- cleo-quality-review:#{run.review_id} -->"
-    end
-
-    ##
-    # @return [Boolean] whether the rendered review contains anything useful to publish
-    def empty?
-      rendered_comments.empty?
-    end
-
-    private
-
-    attr_reader :diff_map, :rendered_review, :run
-
-    def inline_comments
-      rendered_comments.first(MAX_INLINE_COMMENTS).filter_map do |comment|
-        inline_comment_payload(normalized_comment(comment))
-      end
-    end
-
-    def normalized_comment(comment)
-      InlineComment.new(
-        path: comment["path"].to_s,
-        line: comment["line"].to_i,
-        body: comment["body"].to_s.strip,
-      )
-    end
-
-    def inline_comment_payload(comment)
-      comment.to_review_payload(diff_map: diff_map, truncator: method(:truncate))
-    end
-
-    def rendered_comments
-      comments = parsed_review.fetch("comments", [])
-      raise Error, "pr_review JSON field \"comments\" must be an array" unless comments.is_a?(Array)
-
-      comments
-    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 review_body(comments)
-      [
-        marker,
-        body_text,
-        inline_summary(comments),
-      ].compact.join("\n\n")
-    end
-
-    def body_text
-      parsed_review.fetch("body", "").to_s.strip
-    end
-
-    def inline_summary(comments)
-      published_count = comments.length
-      requested_count = rendered_comments.length
-      omitted_comments_message(published_count, requested_count)
-    end
-
-    def omitted_comments_message(published, requested)
-      return "No rendered comments mapped to commentable PR diff lines." if published.zero? && requested.positive?
-      return if published == requested
-
-      omitted = requested - published
-      "#{omitted} rendered comment#{'s' unless omitted == 1} were omitted because they did not map to commentable PR diff lines."
-    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/github_review_publisher.rb

@@ -1,105 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-
-require_relative "github_client"
-require_relative "github_review_builder"
-require_relative "llm_errors"
-
-module CleoQualityReview
-  ##
-  # Publishes quality review findings as a GitHub pull request review
-  class GitHubReviewPublisher
-    ##
-    # @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
-      @rendered_review = rendered_review
-      @env = env
-      @client = client
-    end
-
-    ##
-    # Publish the review, 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
-
-      post_review
-    end
-
-    private
-
-    def publication_skip_reason
-      review_id = run.review_id
-      return "No PR review comments to publish." if builder.empty?
-      return "No pull_request event found; skipping PR review publication." unless pull_request_context?
-      return "PR review already published for review ID #{review_id}; skipping." if already_published?
-
-      nil
-    end
-
-    def post_review
-      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
-
-    attr_reader :env, :rendered_review, :run
-
-    def already_published?
-      response = client.get(reviews_path)
-      body = response.body
-      raise Error, "GitHub PR review lookup failed with status #{response.status_code}: #{body}" unless response.success?
-
-      JSON.parse(body).any? do |review|
-        review.fetch("body", "").include?(builder.marker)
-      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
-
-    def pull_request_context?
-      event.fetch("pull_request", nil).is_a?(Hash)
-    end
-
-    def reviews_path
-      "/repos/#{repository}/pulls/#{pull_request_number}/reviews"
-    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