cleo_quality_review 0.1.0

data/lib/cleo_quality_review/options.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module CleoQualityReview
+  ##
+  # Parses command-line options for the quality review CLI
+  class Options
+    FORMATS = %w[human agent github pr_review].freeze
+    DEFAULT_FORMAT = "human"
+    DEFAULT_CHECKS = ["all"].freeze
+
+    ##
+    # Value object containing parsed command-line options
+    #
+    # @!attribute [r] format
+    #   @return [String] output format
+    # @!attribute [r] checks
+    #   @return [Array<String>] checks to run
+    # @!attribute [r] files
+    #   @return [Array<String>] explicit file paths
+    # @!attribute [r] exclude
+    #   @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, :log, :review_id, :review_file, keyword_init: true) do
+      ##
+      # @return [String] validated review_id
+      # @raise [OptionParser::MissingArgument] if review_id is blank
+      def validated_review_id
+        raise OptionParser::MissingArgument, "--review-id is required" if review_id.to_s.strip == ""
+
+        review_id
+      end
+
+      ##
+      # @return [Hash] run loading attributes
+      def run_loading_params
+        { format: format, log: log }
+      end
+    end
+
+    ##
+    # Parse command-line arguments
+    # @param [Array<String>] argv command-line arguments
+    # @return [ParseResult]
+    # @raise [OptionParser::ParseError] if arguments are invalid
+    def self.parse(argv)
+      new(argv).parse
+    end
+
+    ##
+    # @param [Array<String>] argv command-line arguments
+    def initialize(argv)
+      @argv = argv.dup
+      @format = DEFAULT_FORMAT
+      @checks = []
+      @files = []
+      @exclude = []
+      @changed = false
+      @log = false
+      @review_id = nil
+      @review_file = nil
+    end
+
+    ##
+    # Parse the arguments and return the result
+    # @return [ParseResult]
+    # @raise [OptionParser::InvalidArgument] if format is invalid
+    def parse
+      parser.parse!(argv)
+      validate_format!
+      files.concat(argv)
+
+      ParseResult.new(
+        format: format,
+        checks: checks.empty? ? DEFAULT_CHECKS.dup : checks,
+        files: files,
+        exclude: exclude,
+        changed: changed,
+        log: log,
+        review_id: review_id,
+        review_file: review_file,
+      )
+    end
+
+    private
+
+    attr_reader :argv, :format, :checks, :files, :exclude, :changed, :log, :review_id, :review_file
+
+    def parser
+      OptionParser.new do |opts|
+        opts.banner = "Usage: check_quality [options] [files...]"
+        register_options(opts)
+      end
+    end
+
+    def register_options(opts)
+      register_format_option(opts)
+      register_check_options(opts)
+      register_target_options(opts)
+      register_output_options(opts)
+      register_help_option(opts)
+    end
+
+    def register_format_option(opts)
+      opts.on("-f", "--format FORMAT", FORMATS, "Output format: #{FORMATS.join(', ')} (default: human)") do |value|
+        @format = value
+      end
+    end
+
+    def register_check_options(opts)
+      register_checks_option(opts)
+      register_only_option(opts)
+      register_exclude_option(opts)
+    end
+
+    def register_checks_option(opts)
+      opts.on("-c", "--checks CHECKS", Array, "Checks to run: all, reek, flog, fasterer, debride") { |values| checks.concat(values) }
+    end
+
+    def register_only_option(opts)
+      opts.on("--only CHECKS", Array, "Alias for --checks") { |values| checks.concat(values) }
+    end
+
+    def register_exclude_option(opts)
+      opts.on("-x", "--exclude CHECKS", Array, "Checks to exclude: reek, flog, fasterer, debride") { |values| exclude.concat(values) }
+    end
+
+    def register_target_options(opts)
+      opts.on("--files PATHS", Array, "Comma-separated files or directories to check") do |values|
+        files.concat(values)
+      end
+
+      opts.on("--changed", "Only check files changed from main branch") do
+        @changed = true
+      end
+    end
+
+    def register_output_options(opts)
+      register_log_option(opts)
+      register_review_id_option(opts)
+      register_review_file_option(opts)
+    end
+
+    def register_log_option(opts)
+      opts.on("--log", "Log LLM queries and responses to log/[provider].log") { @log = true }
+    end
+
+    def register_review_id_option(opts)
+      opts.on("--review-id REVIEW_ID", "Reuse an existing analysis artifact by review ID") { |value| @review_id = value }
+    end
+
+    def register_review_file_option(opts)
+      opts.on("--review-file PATH", "Rendered pr_review JSON to publish") { |value| @review_file = value }
+    end
+
+    def register_help_option(opts)
+      opts.on("-h", "--help", "Print help") do
+        puts opts
+        exit 0
+      end
+    end
+
+    def validate_format!
+      return if FORMATS.include?(format)
+
+      raise OptionParser::InvalidArgument, "format must be one of: #{FORMATS.join(', ')}"
+    end
+  end
+end

data/lib/cleo_quality_review/prompt_builder.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative "target_resolver"
+
+module CleoQualityReview
+  ##
+  # Builds the complete LLM prompt from run data and artifacts
+  class PromptBuilder
+    ##
+    # @param [Run] run the quality review run
+    # @param [String] prompt base prompt template
+    # @param [RunArtifacts] artifacts run artifacts containing diffs and outputs
+    def initialize(run:, prompt:, artifacts:)
+      @run = run
+      @prompt = prompt
+      @artifacts = artifacts
+    end
+
+    ##
+    # Build the complete prompt with all sections
+    # @return [String]
+    def build
+      [
+        prompt,
+        metadata_section,
+        diff_section,
+        check_outputs_section,
+        target_files_section,
+      ].join("\n\n")
+    end
+
+    private
+
+    attr_reader :run, :prompt, :artifacts
+
+    def metadata_section
+      target_files = run.target_files
+      <<~MARKDOWN
+        ## Run metadata
+
+        Review ID: #{run.review_id}
+        Timestamp: #{run.timestamp}
+        Checks: #{run.checks.join(", ")}
+        Target files: #{target_files.empty? ? "(none)" : target_files.join(", ")}
+      MARKDOWN
+    end
+
+    def diff_section
+      fenced("Git diff against #{TargetResolver::BASE_REF}", "diff", artifacts.changes_diff)
+    end
+
+    def check_outputs_section
+      artifacts.raw_check_output_records.map do |record|
+        fenced("Raw #{raw_output_title(record)} output", language_for(record.path), record.raw_output)
+      end.join("\n\n")
+    end
+
+    def target_files_section
+      run.target_files.map do |path|
+        fenced("File: #{path}", language_for(path), file_content(path))
+      end.join("\n\n")
+    end
+
+    def file_content(path)
+      File.read(path, invalid: :replace, undef: :replace)
+    rescue Errno::ENOENT
+      "(file not found)"
+    end
+
+    def language_for(path)
+      case File.extname(path)
+      when ".json"
+        "json"
+      when ".rb"
+        "ruby"
+      else
+        "text"
+      end
+    end
+
+    def raw_output_title(record)
+      [record.tool_type, record.check_name].compact.join("/")
+    end
+
+    def fenced(title, language, content)
+      <<~MARKDOWN
+        ## #{title}
+
+        ```#{language}
+        #{content}
+        ```
+      MARKDOWN
+    end
+  end
+end

data/lib/cleo_quality_review/prompt_loader.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module CleoQualityReview
+  ##
+  # Loads prompt templates from local or gem-bundled locations
+  class PromptLoader
+    GEM_PROMPTS_DIRECTORY = File.expand_path("../../prompts", __dir__)
+    LOCAL_PROMPTS_DIRECTORY = ".cleo_quality_review"
+
+    ##
+    # Load a prompt template for the given format
+    # @param [String] format output format name
+    # @return [String] prompt template content
+    # @raise [ArgumentError] if no prompt found for the format
+    def self.load(format: "human")
+      new(format: format).load
+    end
+
+    ##
+    # @param [String] format output format name
+    def initialize(format:)
+      @format = format
+    end
+
+    ##
+    # Load the prompt template
+    # @return [String] prompt content
+    # @raise [ArgumentError] if no prompt found
+    def load
+      prompt_paths.each do |path|
+        return File.read(path) if File.file?(path)
+      end
+
+      raise ArgumentError, "No prompt found for format #{format.inspect}"
+    end
+
+    private
+
+    attr_reader :format
+
+    def prompt_paths
+      [
+        File.join(LOCAL_PROMPTS_DIRECTORY, "prompts", "#{format}.md"),
+        File.join(LOCAL_PROMPTS_DIRECTORY, "#{format}.md"),
+        File.join(GEM_PROMPTS_DIRECTORY, "#{format}.md"),
+      ].compact
+    end
+  end
+end

data/lib/cleo_quality_review/result.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module CleoQualityReview
+  ##
+  # Value object representing a single finding from a quality check
+  #
+  # @!attribute [r] tool_name
+  #   @return [String] name of the tool that produced this result
+  # @!attribute [r] tool_type
+  #   @return [String] category for the tool that produced this result
+  # @!attribute [r] check
+  #   @return [String] specific check or rule that triggered
+  # @!attribute [r] timestamp
+  #   @return [Integer] epoch milliseconds when the check ran
+  # @!attribute [r] result
+  #   @return [String] description of the finding
+  # @!attribute [r] filepath
+  #   @return [String, nil] path to the file with the issue
+  # @!attribute [r] line
+  #   @return [Integer, nil] line number of the issue
+  Result = Struct.new(
+    :tool_name,
+    :tool_type,
+    :check,
+    :timestamp,
+    :result,
+    :filepath,
+    :line,
+    keyword_init: true,
+  ) do
+    def self.from_h(hash)
+      new(
+        tool_name: hash["tool_name"] || hash["tool"],
+        tool_type: hash["tool_type"],
+        check: hash["check"],
+        timestamp: hash["timestamp"],
+        result: hash["result"],
+        filepath: hash["filepath"],
+        line: hash["line"],
+      )
+    end
+
+    ##
+    # Convert the result to a hash, omitting nil values
+    # @return [Hash{Symbol => Object}]
+    def to_h
+      {
+        tool_name: tool_name,
+        tool_type: tool_type,
+        check: check,
+        timestamp: timestamp,
+        result: result,
+        filepath: filepath,
+        line: line,
+      }.compact
+    end
+  end
+end

data/lib/cleo_quality_review/run.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module CleoQualityReview
+  ##
+  # Value object representing a quality review run with its configuration and results
+  #
+  # @!attribute [r] timestamp
+  #   @return [Integer] epoch milliseconds when the run started
+  # @!attribute [r] review_id
+  #   @return [String] deterministic identifier for the reviewed diff
+  # @!attribute [r] format
+  #   @return [String] output format (human, agent, github)
+  # @!attribute [r] checks
+  #   @return [Array<String>] names of checks that were run
+  # @!attribute [r] target_files
+  #   @return [Array<String>] file paths that were analyzed
+  # @!attribute [r] ruby_files
+  #   @return [Array<String>] Ruby file paths that were analyzed
+  # @!attribute [r] run_directory
+  #   @return [String] path to the directory containing run artifacts
+  # @!attribute [r] results
+  #   @return [Array<Result>] findings from the quality checks
+  # @!attribute [r] artifacts
+  #   @return [RunArtifacts, nil] artifacts associated with this run
+  Run = Struct.new(
+    :timestamp,
+    :review_id,
+    :format,
+    :checks,
+    :target_files,
+    :ruby_files,
+    :run_directory,
+    :results,
+    :artifacts,
+    :log,
+    keyword_init: true,
+  ) do
+    ##
+    # Convert the run to a hash representation
+    # @return [Hash{Symbol => Object}]
+    def to_h
+      {
+        timestamp: timestamp,
+        review_id: review_id,
+        format: format,
+        checks: checks,
+        target_files: target_files,
+        ruby_files: ruby_files,
+        run_directory: run_directory,
+        changes_diff: artifacts&.changes_diff,
+        check_outputs: check_outputs,
+        findings: Array(results).map(&:to_h),
+      }
+    end
+
+    ##
+    # Build array of check output hashes for serialization
+    # @return [Array<Hash{Symbol => String}>]
+    def check_outputs
+      return [] unless artifacts
+
+      artifacts.raw_check_output_records.map(&:to_h)
+    end
+
+    ##
+    # Build manifest data for artifact persistence
+    # @return [Hash{Symbol => Object}]
+    def manifest_data
+      {
+        review_id: review_id,
+        timestamp: timestamp,
+        checks: checks,
+        target_files: target_files,
+        ruby_files: ruby_files,
+      }
+    end
+  end
+end

data/lib/cleo_quality_review/run_artifacts/raw_check_outputs.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module CleoQualityReview
+  class RunArtifacts
+    ##
+    # Handles persisted raw output files for quality checks.
+    class RawCheckOutputs
+      ##
+      # Raw output content and metadata for one quality check.
+      Record = Struct.new(:check_name, :tool_name, :tool_type, :extension, :path, :raw_output, keyword_init: true) do
+        def self.from_path(filepath:, check_name:, tool_type:)
+          new(
+            check_name: check_name,
+            tool_name: check_name,
+            tool_type: tool_type,
+            extension: File.extname(filepath).delete_prefix("."),
+            path: filepath,
+            raw_output: File.read(filepath, invalid: :replace, undef: :replace),
+          )
+        end
+
+        def to_pair
+          [check_name, raw_output]
+        end
+
+        def to_record_pair
+          [check_name, self]
+        end
+
+        def to_h
+          {
+            check_name: check_name,
+            tool_name: tool_name,
+            tool_type: tool_type,
+            extension: extension,
+            path: path,
+            raw_output: raw_output,
+          }.compact
+        end
+      end
+
+      def initialize(path:)
+        @path = path
+      end
+
+      def write(check_output)
+        check_name, tool_type, extension, output = check_output.to_h.values_at(
+          :check_name, :tool_type, :extension, :raw_output
+        )
+        check_path = check_output_path(check_name: check_name, tool_type: tool_type)
+        FileUtils.mkdir_p(check_path)
+        File.write(File.join(check_path, "raw_output.#{extension}"), output)
+      end
+
+      def to_h
+        records.to_h(&:to_pair)
+      end
+
+      def records
+        records_by_check_name = legacy_records.to_h(&:to_record_pair)
+        records_by_check_name.merge!(typed_records.to_h(&:to_record_pair))
+        records_by_check_name.values
+      end
+
+      private
+
+      attr_reader :path
+
+      def check_output_path(check_name:, tool_type:)
+        normalized_tool_type = tool_type.to_s.strip
+        return File.join(path, check_name) if normalized_tool_type.empty?
+
+        File.join(path, normalized_tool_type, check_name)
+      end
+
+      def typed_records
+        Dir.glob(File.join(path, "*", "*", "raw_output.*")).sort.map do |filepath|
+          check_dir = File.dirname(filepath)
+          check_name = File.basename(check_dir)
+          tool_type = File.basename(File.dirname(check_dir))
+
+          Record.from_path(filepath: filepath, check_name: check_name, tool_type: tool_type)
+        end
+      end
+
+      def legacy_records
+        Dir.glob(File.join(path, "*", "raw_output.*")).sort.map do |filepath|
+          check_name = File.basename(File.dirname(filepath))
+
+          Record.from_path(filepath: filepath, check_name: check_name, tool_type: nil)
+        end
+      end
+    end
+  end
+end

data/lib/cleo_quality_review/run_artifacts.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+require_relative "result"
+require_relative "run"
+require_relative "run_artifacts/raw_check_outputs"
+
+module CleoQualityReview
+  ##
+  # Manages artifacts produced during a quality review run
+  class RunArtifacts
+    ROOT = "tmp/quality_checks"
+    RawCheckOutput = RawCheckOutputs::Record
+
+    ##
+    # @param [String] review_id deterministic identifier for the reviewed diff
+    # @param [Integer] timestamp epoch milliseconds for the run
+    # @param [Array<String>] target_files file paths being analyzed
+    # @param [String] changes_diff captured git diff content
+    def initialize(review_id:, changes_diff: nil, **_run_metadata)
+      @review_id = review_id.to_s
+      @changes_diff_content = changes_diff
+      @path = File.join(ROOT, @review_id)
+    end
+
+    ##
+    # Load artifacts by review ID
+    # @param [String] review_id deterministic identifier for the reviewed diff
+    # @return [RunArtifacts]
+    def self.load(review_id:)
+      new(review_id: review_id)
+    end
+
+    ##
+    # Prepare the artifact directory and capture initial data
+    # @return [self]
+    def prepare!
+      FileUtils.mkdir_p(@path)
+      write_changes_diff
+      self
+    end
+
+    ##
+    # @return [Boolean] whether this artifact directory contains a complete analysis
+    def complete?
+      File.file?(artifact_path("complete.json"))
+    end
+
+    ##
+    # Write raw check output to a file
+    # @param [Checks::CheckOutput] check_output output record from a quality check
+    # @return [void]
+    def write_check_output(check_output)
+      raw_check_output_store.write(check_output)
+    end
+
+    ##
+    # Persist run metadata for later render/publish commands
+    # @param [Run] run completed run
+    # @return [void]
+    def write_run(run)
+      File.write(artifact_path("results.json"), JSON.pretty_generate(Array(run.results).map(&:to_h)))
+      File.write(artifact_path("manifest.json"), JSON.pretty_generate(run.manifest_data))
+      File.write(artifact_path("complete.json"), JSON.pretty_generate({ review_id: @review_id, completed: true }))
+    end
+
+    ##
+    # Reconstruct a run from persisted artifacts
+    # @param [String] format output format to render
+    # @param [Boolean] log whether LLM logging should be enabled
+    # @return [Run]
+    def to_run(format:, log: false)
+      raise ArgumentError, "No completed quality review artifacts found for review ID #{@review_id}" unless complete?
+
+      manifest = read_manifest
+      target_files = manifest.fetch("target_files", [])
+      Run.new(
+        timestamp: manifest.fetch("timestamp"),
+        review_id: manifest.fetch("review_id"),
+        format: format,
+        checks: manifest.fetch("checks", []),
+        target_files: target_files,
+        ruby_files: manifest.fetch("ruby_files", target_files),
+        run_directory: @path,
+        results: read_results,
+        artifacts: self,
+        log: log,
+      )
+    end
+
+    ##
+    # Read the captured git diff for changes
+    # @return [String]
+    def changes_diff
+      File.read(artifact_path("changes.diff"))
+    end
+
+    ##
+    # Read all raw check outputs from the artifact directory
+    # @return [Hash{String => String}] check name to output content mapping
+    def raw_check_outputs
+      raw_check_output_store.to_h
+    end
+
+    ##
+    # Read all raw check outputs with metadata from the artifact directory
+    # @return [Array<RawCheckOutputs::Record>]
+    def raw_check_output_records
+      raw_check_output_store.records
+    end
+
+    ##
+    # @return [String] path to the artifacts directory
+    def to_s
+      @path
+    end
+
+    private
+
+    def artifact_path(filename)
+      File.join(@path, filename)
+    end
+
+    def write_changes_diff
+      File.write(artifact_path("changes.diff"), @changes_diff_content.to_s)
+    end
+
+    def read_manifest
+      JSON.parse(File.read(artifact_path("manifest.json")))
+    rescue Errno::ENOENT
+      raise ArgumentError, "Missing manifest for review ID #{@review_id}"
+    end
+
+    def read_results
+      JSON.parse(File.read(artifact_path("results.json"))).map { |hash| Result.from_h(hash) }
+    rescue Errno::ENOENT
+      []
+    end
+
+    def raw_check_output_store
+      @raw_check_output_store ||= RawCheckOutputs.new(path: @path)
+    end
+  end
+end