cleo_quality_review 0.1.0

data/lib/cleo_quality_review/command_result.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module CleoQualityReview
+  ##
+  # Value object representing the result of a shell command execution
+  #
+  # @!attribute [r] stdout
+  #   @return [String] standard output from the command
+  # @!attribute [r] stderr
+  #   @return [String] standard error from the command
+  # @!attribute [r] status
+  #   @return [Process::Status] process exit status
+  CommandResult = Struct.new(:stdout, :stderr, :status, keyword_init: true) do
+    ##
+    # Check if the command succeeded
+    # @return [Boolean]
+    def success?
+      status.success?
+    end
+  end
+end

data/lib/cleo_quality_review/command_runner.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "open3"
+
+require_relative "command_result"
+
+module CleoQualityReview
+  ##
+  # Executes shell commands and captures output
+  class CommandRunner
+    ##
+    # Run a shell command and capture its output
+    # @param [Array<String>] command command and arguments to execute
+    # @param [Hash{String => String}] env environment variables
+    # @param [String, nil] stdin_data data to pipe to stdin
+    # @return [CommandResult]
+    def run(*command, env: {}, stdin_data: nil)
+      stdout, stderr, status = if stdin_data.nil?
+        Open3.capture3(env, *command)
+      else
+        Open3.capture3(env, *command, stdin_data: stdin_data)
+      end
+
+      CommandResult.new(stdout: stdout, stderr: stderr, status: status)
+    end
+  end
+end

data/lib/cleo_quality_review/configuration.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require "set"
+require "yaml"
+
+module CleoQualityReview
+  ##
+  # Configuration for file include/exclude patterns
+  class Configuration
+    DEFAULT_CONFIG_PATH = File.expand_path("../../config/default.yml", __dir__)
+    LOCAL_CONFIG_PATH = ".cleo_quality_review.yaml"
+    ALL_TOOLS = "AllTools"
+    INCLUDE = "Include"
+    EXCLUDE = "Exclude"
+    INHERIT_FROM = "inherit_from"
+    GEM_DEFAULT_ALIASES = ["default", "gem:default"].freeze
+    MATCH_FLAGS = File::FNM_PATHNAME | File::FNM_EXTGLOB
+
+    ##
+    # Load configuration from default and local config files
+    # @param [String] root root directory for local config lookup
+    # @return [Configuration]
+    def self.load(root: Dir.pwd)
+      Loader.new(root: root).load
+    end
+
+    ##
+    # @param [Hash] data parsed configuration data
+    def initialize(data)
+      @data = data
+    end
+
+    ##
+    # @return [Array<String>] glob patterns for files to include
+    def include_patterns
+      patterns_for(INCLUDE)
+    end
+
+    ##
+    # @return [Array<String>] glob patterns for files to exclude
+    def exclude_patterns
+      patterns_for(EXCLUDE)
+    end
+
+    ##
+    # Check if a file should be included based on configuration patterns
+    # @param [String] path file path to check
+    # @return [Boolean]
+    def target_file?(path)
+      normalized_path = normalize_path(path)
+
+      matches_any?(include_patterns, normalized_path) && !matches_any?(exclude_patterns, normalized_path)
+    end
+
+    private
+
+    attr_reader :data
+
+    def patterns_for(key)
+      Array(data.fetch(ALL_TOOLS) { {} }.fetch(key) { [] }).map(&:to_s)
+    end
+
+    def matches_any?(patterns, path)
+      patterns.any? { |pattern| matches?(pattern, path) }
+    end
+
+    def matches?(pattern, path)
+      normalized_pattern = normalize_pattern(pattern)
+
+      File.fnmatch?(normalized_pattern, path, MATCH_FLAGS)
+    end
+
+    def normalize_path(path)
+      path.to_s.delete_prefix("./").tr(File::ALT_SEPARATOR || File::SEPARATOR, File::SEPARATOR).tr("\\", "/")
+    end
+
+    def normalize_pattern(pattern)
+      pattern.to_s.delete_prefix("./").tr("\\", "/")
+    end
+
+    ##
+    # Loads and merges configuration files with inheritance support
+    class Loader
+      ##
+      # @param [String] root root directory for config file lookup
+      def initialize(root:)
+        @root = File.expand_path(root)
+      end
+
+      ##
+      # Load merged configuration
+      # @return [Configuration]
+      def load
+        data = load_file(DEFAULT_CONFIG_PATH)
+        local_config_path = File.join(root, LOCAL_CONFIG_PATH)
+        data = merge(data, load_file(local_config_path)) if File.file?(local_config_path)
+
+        Configuration.new(data)
+      end
+
+      private
+
+      attr_reader :root
+
+      def load_file(path, seen: Set.new)
+        expanded_path = expand_config_path(path, relative_to: root)
+        return {} if skip_file?(expanded_path, seen)
+
+        seen.add(expanded_path)
+        load_with_inheritance(expanded_path, seen)
+      end
+
+      def skip_file?(expanded_path, seen)
+        return true if seen.include?(expanded_path)
+
+        raise ArgumentError, "Config file not found: #{expanded_path}" unless File.file?(expanded_path)
+
+        false
+      end
+
+      def load_with_inheritance(expanded_path, seen)
+        config = read_yaml(expanded_path)
+        inherited_data = load_inherited(config, expanded_path, seen)
+        merge(inherited_data, config.except(INHERIT_FROM))
+      end
+
+      def load_inherited(config, expanded_path, seen)
+        inherit_from(config).reduce({}) do |merged, inherited_path|
+          merge(merged, load_file(resolve_inherited_path(inherited_path, expanded_path), seen: seen))
+        end
+      end
+
+      def read_yaml(path)
+        parsed = YAML.safe_load(File.read(path), aliases: true)
+        return {} if parsed.nil?
+        raise ArgumentError, "Config file must contain a YAML mapping: #{path}" unless parsed.is_a?(Hash)
+
+        stringify_keys(parsed)
+      end
+
+      def inherit_from(config)
+        Array(config.fetch(INHERIT_FROM) { [] })
+      end
+
+      def resolve_inherited_path(path, parent_path)
+        value = path.to_s
+        return DEFAULT_CONFIG_PATH if GEM_DEFAULT_ALIASES.include?(value)
+
+        expand_config_path(value, relative_to: File.dirname(parent_path))
+      end
+
+      def expand_config_path(path, relative_to:)
+        path_string = path.to_s
+        return File.expand_path(path_string) if path_string.start_with?("/", "~")
+
+        File.expand_path(path_string, relative_to)
+      end
+
+      def merge(base, override)
+        base.merge(override) do |_key, base_value, override_value|
+          merge_values(base_value, override_value)
+        end
+      end
+
+      def merge_values(base_value, override_value)
+        return merge(base_value, override_value) if both_hashes?(base_value, override_value)
+        return (base_value + override_value).uniq if both_arrays?(base_value, override_value)
+
+        override_value
+      end
+
+      def both_hashes?(a, b) = a.is_a?(Hash) && b.is_a?(Hash)
+
+      def both_arrays?(a, b) = a.is_a?(Array) && b.is_a?(Array)
+
+      def stringify_keys(value)
+        case value
+        when Hash then stringify_hash_keys(value)
+        when Array then stringify_array_values(value)
+        else value
+        end
+      end
+
+      def stringify_hash_keys(hash)
+        hash.to_h { |key, v| [key.to_s, stringify_keys(v)] }
+      end
+
+      def stringify_array_values(array)
+        array.map { |v| stringify_keys(v) }
+      end
+    end
+  end
+end

data/lib/cleo_quality_review/diff_map.rb

@@ -0,0 +1,95 @@
+# 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/formatter.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "llm_client"
+require_relative "llm_config"
+require_relative "prompt_builder"
+require_relative "prompt_loader"
+require_relative "run_artifacts"
+
+module CleoQualityReview
+  ##
+  # Formats quality review results using an LLM with format-specific prompts
+  class Formatter
+    ##
+    # @param [Run] run the quality review run to format
+    # @param [CommandRunner] command_runner for executing shell commands
+    # @param [LlmConfig] llm_config LLM provider configuration
+    # @param [LlmClient, nil] llm_client optional pre-configured client
+    def initialize(run:, command_runner:, llm_config: LlmConfig.new, llm_client: nil)
+      @run = run
+      @command_runner = command_runner
+      @llm_config = llm_config
+      @llm_client = llm_client
+    end
+
+    ##
+    # Format the run by generating an LLM review
+    # @return [String] formatted review text
+    def format
+      llm_client.generate_review(prompt)
+    end
+
+    private
+
+    attr_reader :run, :command_runner, :llm_config
+
+    ##
+    # @return [String]
+    def prompt
+      PromptBuilder.new(
+        run: run,
+        prompt: PromptLoader.load(format: run.format),
+        artifacts: artifacts,
+      ).build
+    end
+
+    ##
+    # @return [RunArtifacts]
+    def artifacts
+      @artifacts ||= run.artifacts || RunArtifacts.load(review_id: run.review_id || run.timestamp)
+    end
+
+    ##
+    # @return [LlmClient]
+    def llm_client
+      @llm_client ||= LlmClient.new(config: llm_config, log: run.log)
+    end
+  end
+end

data/lib/cleo_quality_review/github_review_builder.rb

@@ -0,0 +1,140 @@
+# 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 ||= begin
+        parsed = JSON.parse(rendered_review.to_s)
+        raise Error, "pr_review JSON must be an object" unless parsed.is_a?(Hash)
+
+        parsed
+      end
+    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

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+require_relative "github_review_builder"
+require_relative "llm_errors"
+
+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)
+      @run = run
+      @rendered_review = rendered_review
+      @env = env
+    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 = request_json(:post, reviews_uri, 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)
+      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 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_uri
+      URI("#{api_url}/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
+
+    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