cleo_quality_review 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 63b36db131462e8bedbfe7e7f1d42084a4f600464a6a6b881231a9254d0f4e5b
+  data.tar.gz: 5722693b1abeaee01930f71c0e3d5d57333677c2d62bd3f4eaffc613094e3e7b
+SHA512:
+  metadata.gz: 31cf5bfcac10c05eb3f1297b132e60b1b730c951c382351879750f51362419df464c103f368e3571dfc6545070f37281827e477cf80af07420d08c8a3a7e4e37
+  data.tar.gz: 956cba96beddc95e78ec88b27d0c7e2b25f0b94dd997f8a5ee8b137ab2a34ee7be42e75fb18300fdd5abfc5260978b428d280e6359f730c0cad8b406c58f40cc

data/cleo_quality_review.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "lib/cleo_quality_review/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "cleo_quality_review"
+  spec.version = CleoQualityReview::VERSION
+  spec.authors = ["Gavin Morrice"]
+  spec.email = ["gavin@gavinmorrice.com"]
+
+  spec.summary = "Local Cleo code quality checks"
+  spec.description = "Runs local quality checks and summarizes their output for humans, agents, or GitHub."
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files =
+    Dir.glob("{#{File.basename(__FILE__)},config/**/*,exe/**/*,lib/**/*,prompts/**/*}", File::FNM_DOTMATCH).select do |path|
+      File.file?(path) && !File.symlink?(path)
+    end
+
+  spec.bindir = "exe"
+  spec.executables = ["check_quality"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "debride"
+  spec.add_dependency "fasterer"
+  spec.add_dependency "flog"
+  spec.add_dependency "reek"
+end

data/config/default.yml

@@ -0,0 +1,7 @@
+AllTools:
+  Include:
+    - "**/*.rb"
+  Exclude:
+    - "tmp/**/*"
+    - "vendor/**/*"
+    - "node_modules/**/*"

data/exe/check_quality

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+$LOAD_PATH << File.expand_path('../lib', __dir__)
+
+require "cleo_quality_review/cli"
+
+##
+# Load development environment variables
+# This should not be used when packaging in production
+if ENV.fetch('CLEO_QUALITY_REVIEW_DEV', 'false') == 'true'
+  begin
+    require 'dotenv'
+    local_dotenv = File.expand_path("../.env.development.local", __dir__)
+    Dotenv.load(local_dotenv)
+  rescue LoadError
+    puts "No local .env.development found. Skip."
+  end
+end
+
+exit CleoQualityReview::CLI.new(ARGV).run

data/lib/cleo_quality_review/changes_diff.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "digest"
+
+require_relative "target_resolver"
+
+module CleoQualityReview
+  ##
+  # Captures the git diff used for a quality review run
+  class ChangesDiff
+    ##
+    # @param [Array<String>] target_files files included in the review
+    # @param [CommandRunner] command_runner for executing git commands
+    def initialize(target_files:, command_runner:)
+      @target_files = target_files
+      @command_runner = command_runner
+    end
+
+    ##
+    # @return [String] combined tracked and untracked diff content
+    def to_s
+      @to_s ||= [tracked_changes_diff, untracked_changes_diff].reject(&:empty?).join("\n")
+    end
+
+    ##
+    # @return [String] deterministic review identifier for this diff
+    def review_id
+      Digest::SHA256.hexdigest(to_s)
+    end
+
+    private
+
+    attr_reader :command_runner, :target_files
+
+    def tracked_changes_diff
+      command = ["git", "diff", diff_base]
+      command.concat(["--", *target_files]) unless target_files.empty?
+
+      command_runner.run(*command).stdout
+    end
+
+    def untracked_changes_diff
+      untracked_target_files.map do |filepath|
+        command_runner.run("git", "diff", "--no-index", "--", "/dev/null", filepath).stdout
+      end.reject(&:empty?).join("\n")
+    end
+
+    def untracked_target_files
+      command = ["git", "ls-files", "--others", "--exclude-standard"]
+      empty_targets = target_files.empty?
+      command.concat(["--", *target_files]) unless empty_targets
+
+      command_runner.run(*command).stdout.lines.map(&:strip).select do |path|
+        empty_targets || target_files.include?(path)
+      end
+    end
+
+    def diff_base
+      @diff_base ||= begin
+        result = command_runner.run("git", "merge-base", TargetResolver::BASE_REF, "HEAD")
+        base = result.stdout.strip
+
+        result.success? && !base.empty? ? base : TargetResolver::BASE_REF
+      end
+    end
+  end
+end

data/lib/cleo_quality_review/checks/debride.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "quality_check"
+
+module CleoQualityReview
+  module Checks
+    ##
+    # Quality check implementation for Debride unused-code analyzer
+    class Debride < QualityCheck
+      self.check_name = "dead_code"
+      self.tool_name = "debride"
+      self.output_extension = "json"
+
+      private
+
+      def command(files)
+        [ruby_executable, gem_executable("debride", "debride"), "--json", "--rails", *files]
+      end
+
+      def parse(stdout, stderr)
+        findings = missing_methods(stdout).flat_map do |class_name, methods|
+          results_for_class(class_name, methods)
+        end
+        return findings unless findings.empty? && stderr.to_s.strip != ""
+
+        [result(check: "Execution error", message: stderr, filepath: nil)]
+      end
+
+      def missing_methods(stdout)
+        parsed = JSON.parse(stdout.to_s)
+        missing = parsed.fetch("missing", {})
+        return {} unless missing.is_a?(Hash)
+
+        missing
+      rescue JSON::ParserError
+        {}
+      end
+
+      def results_for_class(class_name, methods)
+        Array(methods).map { |entry| method_to_result(class_name, entry) }
+      end
+
+      def method_to_result(class_name, entry)
+        method_name, location = Array(entry)
+        filepath, line = parse_location(location)
+
+        result(
+          check: "PotentialDeadMethod",
+          message: "#{class_name}##{method_name} might not be called",
+          filepath: filepath,
+          line: line,
+        )
+      end
+
+      def parse_location(location)
+        match = location.to_s.match(/\A(?<filepath>.*):(?<line>\d+)(?:-\d+)?\z/)
+        return [nil, nil] unless match
+
+        match.values_at(:filepath, :line)
+      end
+    end
+  end
+end

data/lib/cleo_quality_review/checks/fasterer.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "quality_check"
+
+module CleoQualityReview
+  module Checks
+    ##
+    # Quality check implementation for Fasterer performance analyzer
+    class Fasterer < QualityCheck
+      self.check_name = "fasterer"
+      self.tool_name = "fasterer"
+
+      private
+
+      def command(files)
+        [ruby_executable, gem_executable("fasterer", "fasterer"), *files]
+      end
+
+      def parse(stdout, stderr)
+        findings = stdout.to_s.lines.filter_map { |line| parse_line(line) }
+        return findings unless findings.empty? && stderr.to_s.strip != ""
+
+        [result(check: "Execution error", message: stderr, filepath: nil)]
+      end
+
+      def parse_line(line)
+        match = line.to_s.gsub(/\e\[[\d;]*m/, "").match(/^(?<filepath>.+?):(?<line>\d+):?\s+(?<message>.+)$/)
+        return unless match
+
+        filepath, line_number, message = match.values_at(:filepath, :line, :message)
+        result(check: "Performance", message: message, filepath: filepath, line: line_number)
+      end
+    end
+  end
+end

data/lib/cleo_quality_review/checks/flog.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "quality_check"
+
+module CleoQualityReview
+  module Checks
+    ##
+    # Quality check implementation for Flog complexity analyzer
+    class Flog < QualityCheck
+      self.check_name = "flog"
+      self.tool_name = "flog"
+
+      private
+
+      def command(files)
+        [ruby_executable, gem_executable("flog", "flog"), "--all", "--methods", *files]
+      end
+
+      def parse(stdout, stderr)
+        findings = stdout.to_s.lines.filter_map { |line| parse_line(line) }
+        return findings unless findings.empty? && stderr.to_s.strip != ""
+
+        [result(check: "Execution error", message: stderr, filepath: nil)]
+      end
+
+      def parse_line(line)
+        match = line.match(/^\s*(?<score>\d+(?:\.\d+)?):\s+(?<subject>.+?)\s+(?<filepath>[^:\s]+):(?<line>\d+)/)
+        return unless match
+
+        score, subject, filepath, line_number = match.values_at(:score, :subject, :filepath, :line)
+        result(check: "Complexity", message: "#{score}: #{subject}", filepath: filepath, line: line_number)
+      end
+    end
+  end
+end

data/lib/cleo_quality_review/checks/quality_check.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+require_relative "../result"
+
+module CleoQualityReview
+  module Checks
+    ##
+    # Base class for quality check implementations
+    class QualityCheck
+      class << self
+        ##
+        # @!attribute [rw] check_name
+        #   @return [String] identifier for this check
+        attr_accessor :check_name
+
+        # @!attribute [rw] tool_name
+        #   @return [String] tool name for result attribution
+        attr_accessor :tool_name
+
+        # @!attribute [rw] tool_type
+        #   @return [String] category for this tool's findings
+        attr_accessor :tool_type
+
+        # @!attribute [rw] output_extension
+        #   @return [String] file extension for raw output
+        attr_accessor :output_extension
+
+        ##
+        # Set default output extension for subclasses
+        # @param [Class] subclass the inheriting class
+        # @return [void]
+        def inherited(subclass)
+          super
+          subclass.output_extension = "txt"
+        end
+
+        def output_metadata
+          {
+            check_name: check_name,
+            tool_name: tool_name,
+            tool_type: tool_type,
+            extension: output_extension,
+          }
+        end
+      end
+
+      ##
+      # @param [CommandRunner] command_runner for executing shell commands
+      # @param [Integer] timestamp epoch milliseconds for the run
+      def initialize(command_runner:, timestamp:)
+        @command_runner = command_runner
+        @timestamp = timestamp
+      end
+
+      ##
+      # Run the quality check on the given files
+      # @param [Array<String>] files file paths to analyze
+      # @return [CheckOutput]
+      def run(files)
+        return empty_output if files.empty?
+
+        command_result = command_runner.run(*command(files))
+        build_output(
+          raw_output: raw_output(command_result),
+          results: parse(command_result.stdout, parseable_stderr(command_result)),
+        )
+      end
+
+      private
+
+      attr_reader :command_runner, :timestamp
+
+      def check_metadata
+        @check_metadata ||= self.class.output_metadata
+      end
+
+      def empty_output
+        build_output(raw_output: "", results: [])
+      end
+
+      def build_output(raw_output:, results:)
+        CheckOutput.new(
+          **check_metadata,
+          raw_output: raw_output,
+          results: results,
+        )
+      end
+
+      def ruby_executable
+        RbConfig.ruby
+      end
+
+      def gem_executable(gem_name, executable_name)
+        Gem.bin_path(gem_name, executable_name)
+      end
+
+      def raw_output(command_result)
+        stdout = command_result.stdout
+        return stdout if command_result.success?
+
+        stderr = command_result.stderr
+        return stdout if stderr.empty?
+
+        [stdout, stderr].reject(&:empty?).join("\n")
+      end
+
+      def parseable_stderr(command_result)
+        command_result.success? ? "" : command_result.stderr
+      end
+
+      def result(attributes)
+        check, message, filepath, line = attributes.values_at(:check, :message, :filepath, :line)
+        CleoQualityReview::Result.new(
+          **check_metadata.slice(:tool_name, :tool_type),
+          check: check,
+          timestamp: timestamp,
+          result: message,
+          filepath: filepath,
+          line: line&.to_i,
+        )
+      end
+    end
+
+    ##
+    # Value object containing check output and parsed results
+    #
+    # @!attribute [r] check_name
+    #   @return [String] identifier for the check
+    # @!attribute [r] tool_name
+    #   @return [String] name of the concrete tool
+    # @!attribute [r] tool_type
+    #   @return [String] category for this tool's findings
+    # @!attribute [r] extension
+    #   @return [String] file extension for the raw output
+    # @!attribute [r] raw_output
+    #   @return [String] raw tool output
+    # @!attribute [r] results
+    #   @return [Array<Result>] parsed findings
+    CheckOutput = Struct.new(:check_name, :tool_name, :tool_type, :extension, :raw_output, :results, keyword_init: true)
+  end
+end

data/lib/cleo_quality_review/checks/reek.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "quality_check"
+
+module CleoQualityReview
+  module Checks
+    ##
+    # Quality check implementation for Reek code smell detector
+    class Reek < QualityCheck
+      self.check_name = "reek"
+      self.tool_name = "reek"
+      self.output_extension = "json"
+
+      private
+
+      def command(files)
+        [ruby_executable, gem_executable("reek", "reek"), "--format", "json", *files]
+      end
+
+      def parse(stdout, stderr)
+        smells = parse_json(stdout)
+        return stderr_result(stderr) if smells.empty? && stderr.to_s.strip != ""
+
+        smells.map { |smell| smell_to_result(smell) }
+      end
+
+      def smell_to_result(smell)
+        result(
+          check: smell.fetch("smell_type", "Reek"),
+          message: smell_message(smell),
+          filepath: smell.fetch("source", nil),
+          line: Array(smell["lines"]).first,
+        )
+      end
+
+      def parse_json(stdout)
+        JSON.parse(stdout.to_s)
+      rescue JSON::ParserError
+        []
+      end
+
+      def smell_message(smell)
+        [smell["context"], smell["message"]].compact.join(": ")
+      end
+
+      def stderr_result(stderr)
+        [result(check: "Execution error", message: stderr, filepath: nil)]
+      end
+    end
+  end
+end

data/lib/cleo_quality_review/checks/registry.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module CleoQualityReview
+  module Checks
+    ##
+    # Registry for available quality check implementations
+    class Registry
+      class UnknownCheckError < CleoQualityReview::Error
+        def initialize(name)
+          super("Unknown check name: #{name}")
+        end
+      end
+
+      require 'delegate'
+      class CheckName < DelegateClass(String)
+        def initialize(name)
+          super(name.to_s.downcase)
+        end
+
+      end
+
+      Registration = Data.define(:check_name, :klass, :tool_type)
+      class << self
+        ##
+        # Register a quality check implementation
+        # @param [String] name check identifier
+        # @param [Class] klass class name under CleoQualityReview
+        # @param [Symbol, String] tool_type category of tool findings
+        # @return [void]
+        def register(name, klass, tool_type:)
+          name = CheckName.new(name).to_s
+          registration = Registration.new(check_name: name.to_s, klass: klass, tool_type: tool_type.to_s)
+          registrations[name] = registration
+          nil
+        end
+
+        ##
+        # Resolve check names to check classes
+        # @param [Array<String>] names check names to resolve
+        # @return [Array<Class>] resolved check classes
+        # @raise [ArgumentError] if an unknown check name is provided
+        def resolve(names)
+          names_to_resolve(names).map { |name| resolve_name(name) }
+        end
+
+        def registered?(tool_name)
+          registrations.key?(CheckName.new(tool_name))
+        end
+
+        private
+
+        def registrations
+          @registrations ||= {}
+        end
+
+        def names_to_resolve(names)
+          names = ['all'] if names.empty?
+
+          names.include?('all') ? registrations.keys : names.map(&:to_s)
+        end
+
+        def resolve_name(name)
+          name = CheckName.new(name).to_s
+          registration = registrations[name]
+          raise UnknownCheckError.new(name) unless registration
+
+          registration.klass
+        end
+      end
+    end
+  end
+end

data/lib/cleo_quality_review/checks.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module CleoQualityReview
+  ##
+  # Namespace for bundled quality check implementations.
+  module Checks
+    require_relative "checks/registry"
+    require_relative "checks/quality_check"
+    require_relative "checks/reek"
+    require_relative "checks/flog"
+    require_relative "checks/fasterer"
+    require_relative "checks/debride"
+
+    class << self
+      ##
+      # Register a new check for use
+      # @param [String] tool_name
+      # @param [Class] tool_class
+      # @param [String, Symbol] tool_type
+      # @return [nil]
+      def register(tool_name, tool_class, tool_type: )
+        Registry.register(tool_name.to_s, tool_class, tool_type: tool_type.to_s)
+      end
+
+      def resolve(tool_names)
+        Registry.resolve(Array(tool_names))
+      end
+      ##
+      # Has a tool with the given name been registered?
+      #
+      # @param [String] tool_name
+      # @return [Boolean]
+      def registered?(tool_name)
+        Registry.registered?(tool_name)
+      end
+    end
+  end
+end

data/lib/cleo_quality_review/cli.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+require_relative "../cleo_quality_review"
+require_relative "command_runner"
+require_relative "formatter"
+require_relative "github_review_publisher"
+require_relative "options"
+require_relative "runner"
+require_relative "run_artifacts"
+
+module CleoQualityReview
+  ##
+  # Command-line interface entry point
+  class CLI
+    SUBCOMMANDS = {
+      "analyze" => :run_analyze,
+      "render" => :run_render,
+      "publish-pr-review" => :run_publish_pr_review,
+    }.freeze
+
+    ##
+    # @param [Array<String>] argv command-line arguments
+    # @param [IO] stdout standard output stream
+    # @param [IO] stderr standard error stream
+    def initialize(argv, stdout: $stdout, stderr: $stderr)
+      @argv = argv
+      @stdout = stdout
+      @stderr = stderr
+    end
+
+    ##
+    # Execute the CLI
+    # @return [Integer] exit code (0 for success, 1 for error)
+    def run
+      dispatch_command
+    rescue Error, OptionParser::ParseError, ArgumentError => error
+      stderr.puts("check_quality: #{error.message}")
+      1
+    end
+
+    private
+
+    def dispatch_command
+      @command_runner = CommandRunner.new
+      command = argv.first
+      subcommand = SUBCOMMANDS[command]
+
+      if subcommand
+        run_subcommand(subcommand, argv.drop(1))
+      else
+        run_one_shot(argv)
+      end
+    end
+
+    attr_reader :argv, :stdout, :stderr, :command_runner
+
+    def run_one_shot(arguments)
+      options = Options.parse(arguments)
+      run = Runner.new(options: options, command_runner: command_runner).run
+      output = Formatter.new(run: run, command_runner: command_runner).format
+      print_output(output)
+      0
+    end
+
+    def run_subcommand(subcommand, arguments)
+      send(subcommand, arguments)
+    end
+
+    def run_analyze(arguments)
+      options = Options.parse(arguments)
+      run = Runner.new(options: options, command_runner: command_runner).run
+      stdout.puts(run.review_id)
+      0
+    end
+
+    def run_render(arguments)
+      options = Options.parse(arguments)
+      run = RunArtifacts.load(review_id: options.validated_review_id).to_run(**options.run_loading_params)
+      output = Formatter.new(run: run, command_runner: command_runner).format
+      print_output(output)
+      0
+    end
+
+    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
+      print_output(output)
+      0
+    end
+
+    def print_output(output)
+      stdout.puts(output) unless output.empty?
+    end
+
+    def rendered_pr_review(options, run)
+      path = options.review_file || File.join(run.run_directory, "pr_review.json")
+      raise OptionParser::MissingArgument, "--review-file is required or #{path} must exist" unless File.file?(path)
+
+      File.read(path)
+    end
+  end
+end