cleo_quality_review 0.1.0

data/lib/cleo_quality_review/runner.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+require_relative "changes_diff"
+require_relative "checks"
+require_relative "command_runner"
+require_relative "run"
+require_relative "run_artifacts"
+require_relative "target_resolver"
+
+module CleoQualityReview
+  ##
+  # Orchestrates a complete quality review run
+  class Runner
+    ##
+    # Grouped values resolved at the start of an analysis run
+    AnalysisContext = Struct.new(:timestamp, :target, :changes, :review_id, :check_classes, keyword_init: true) do
+      ##
+      # @return [Hash] run construction attributes derived from this context
+      def run_attributes
+        {
+          timestamp: timestamp,
+          review_id: review_id,
+          checks: check_classes.map(&:check_name),
+          target_files: target.files,
+          ruby_files: target.ruby_files,
+        }
+      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)
+      @options = options
+      @command_runner = command_runner
+      @clock = clock
+      @check_registry = check_registry
+    end
+
+    ##
+    # Execute the quality review
+    # @return [Run] results of the quality review
+    def run
+      context = analysis_context
+      artifacts = prepare_artifacts(context)
+      return reusable_run(artifacts) if artifacts.complete?
+
+      execute_fresh_run(context, artifacts)
+    end
+
+    private
+
+    attr_reader :options, :command_runner, :clock, :check_registry
+
+    def epoch_milliseconds
+      (clock.now.to_r * 1_000).to_i
+    end
+
+    def analysis_context
+      timestamp = epoch_milliseconds
+      target = resolve_target
+      changes = changes_diff(target)
+      check_classes = resolve_checks
+
+      AnalysisContext.new(
+        timestamp: timestamp,
+        target: target,
+        changes: changes,
+        review_id: review_id_for(changes, check_classes),
+        check_classes: check_classes,
+      )
+    end
+
+    def resolve_target
+      files = options.files
+      changed = options.changed || files.empty?
+      TargetResolver.new(command_runner: command_runner).resolve(files, changed: changed)
+    end
+
+    def changes_diff(target)
+      ChangesDiff.new(target_files: target.files, command_runner: command_runner)
+    end
+
+    def prepare_artifacts(context)
+      RunArtifacts.new(
+        timestamp: context.timestamp,
+        review_id: context.review_id,
+        target_files: context.target.files,
+        changes_diff: context.changes.to_s,
+      ).prepare!
+    end
+
+    def reusable_run(artifacts)
+      artifacts.to_run(format: options.format, log: options.log)
+    end
+
+    def execute_fresh_run(context, artifacts)
+      check_outputs = run_checks(context.check_classes, context.target.ruby_files, context.timestamp)
+      write_check_outputs(artifacts, check_outputs)
+      run = build_run(context, artifacts, check_outputs)
+      persist_run(artifacts, run)
+      run
+    end
+
+    def resolve_checks
+      all_checks = check_registry.resolve(options.checks)
+      filter_excluded_checks(all_checks, options.exclude)
+    end
+
+    def filter_excluded_checks(checks, excluded)
+      return checks if excluded.empty?
+
+      excluded_names = excluded.map(&:downcase)
+      checks.reject { |check| excluded_names.include?(check.check_name.downcase) }
+    end
+
+    def run_checks(check_classes, ruby_files, timestamp)
+      check_classes.map do |check_class|
+        check_class.new(command_runner: command_runner, timestamp: timestamp).run(ruby_files)
+      end
+    end
+
+    def write_check_outputs(artifacts, check_outputs)
+      check_outputs.each do |output|
+        artifacts.write_check_output(output)
+      end
+    end
+
+    def build_run(context, artifacts, check_outputs)
+      Run.new(
+        **context.run_attributes,
+        format: options.format,
+        run_directory: artifacts.to_s,
+        results: check_outputs.flat_map(&:results),
+        artifacts: artifacts,
+        log: options.log,
+      )
+    end
+
+    def persist_run(artifacts, run)
+      artifacts.write_run(run)
+    end
+
+    def review_id_for(changes, check_classes)
+      Digest::SHA256.hexdigest(
+        JSON.generate(
+          diff: changes.to_s,
+          checks: check_classes.map(&:check_name).sort,
+        ),
+      )
+    end
+  end
+end

data/lib/cleo_quality_review/target_resolver.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require_relative "configuration"
+
+module CleoQualityReview
+  ##
+  # Resolves target files for quality review based on git changes and configuration
+  class TargetResolver
+    BASE_REF = "origin/main"
+
+    ##
+    # Value object containing resolved file lists
+    #
+    # @!attribute [r] files
+    #   @return [Array<String>] all target file paths
+    # @!attribute [r] ruby_files
+    #   @return [Array<String>] Ruby file paths
+    Target = Struct.new(:files, :ruby_files, keyword_init: true)
+
+    ##
+    # @param [CommandRunner] command_runner for executing git commands
+    # @param [Configuration] configuration file filtering configuration
+    def initialize(command_runner:, configuration: Configuration.load)
+      @command_runner = command_runner
+      @configuration = configuration
+    end
+
+    ##
+    # Resolve target files for quality review
+    # @param [Array<String>] files explicit file paths
+    # @param [Boolean] changed when true, filter to git-changed files only
+    # @return [Target]
+    def resolve(files, changed: false)
+      target_files = resolve_target_files(files, changed: changed)
+
+      Target.new(
+        files: target_files,
+        ruby_files: target_files,
+      )
+    end
+
+    private
+
+    attr_reader :command_runner, :configuration
+
+    def resolve_target_files(files, changed:)
+      candidates = resolve_candidates(files, changed: changed)
+      filter_to_configured(candidates)
+    end
+
+    def resolve_candidates(files, changed:)
+      return changed_files if files.empty?
+
+      resolve_explicit_paths(files, changed: changed)
+    end
+
+    def resolve_explicit_paths(files, changed:)
+      expanded = expand_target_paths(files)
+      changed ? filter_to_changed(expanded) : expanded
+    end
+
+    def filter_to_configured(candidates)
+      candidates.select { |path| File.file?(path) && configuration.target_file?(path) }
+    end
+
+    def filter_to_changed(paths)
+      git_changed = changed_files
+      paths.select { |path| git_changed.include?(path) }
+    end
+
+    def changed_files
+      (tracked_changed_files + untracked_files).uniq
+    end
+
+    def tracked_changed_files
+      result = command_runner.run(
+        "git",
+        "diff",
+        "--name-only",
+        "--diff-filter=ACMRT",
+        diff_base,
+      )
+
+      result.stdout.lines.map(&:strip)
+    end
+
+    def untracked_files
+      result = command_runner.run("git", "ls-files", "--others", "--exclude-standard")
+
+      result.stdout.lines.map(&:strip)
+    end
+
+    def diff_base
+      @diff_base ||= begin
+        result = command_runner.run("git", "merge-base", BASE_REF, "HEAD")
+        base = result.stdout.strip
+
+        result.success? && !base.empty? ? base : BASE_REF
+      end
+    end
+
+    def expand_target_paths(paths)
+      cleaned_paths = paths.map(&:to_s).map(&:strip).reject(&:empty?)
+      files, directories, missing = classify_paths(cleaned_paths)
+      raise ArgumentError, "Path not found: #{missing.join(', ')}" unless missing.empty?
+
+      (files + directories.flat_map { |path| directory_files(path) }).uniq
+    end
+
+    def classify_paths(paths)
+      paths.group_by { |path| path_type(path) }.values_at(:file, :directory, :missing).map { |v| v || [] }
+    end
+
+    def path_type(path)
+      return :file if File.file?(path)
+      return :directory if File.directory?(path)
+
+      :missing
+    end
+
+    def directory_files(path)
+      Dir.glob(File.join(path, "**", "*"), File::FNM_DOTMATCH).sort.select do |expanded_path|
+        File.file?(expanded_path)
+      end
+    end
+  end
+end

data/lib/cleo_quality_review/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module CleoQualityReview
+  ##
+  # Gem version
+  VERSION = "0.1.0"
+end

data/lib/cleo_quality_review.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+##
+# Quality review tool for Ruby code analysis
+module CleoQualityReview
+  class Error < StandardError;end
+
+  require_relative "cleo_quality_review/version"
+  require_relative "cleo_quality_review/checks"
+  require_relative "cleo_quality_review/llm_providers"
+
+  ##
+  # Register all supported tools for analysing code here
+  Checks.register("Reek", Checks::Reek, tool_type: :smell_detection)
+  Checks.register("Flog", Checks::Flog, tool_type: :complexity)
+  Checks.register("Fasterer", Checks::Fasterer, tool_type: :performance)
+  Checks.register("Debride", Checks::Debride, tool_type: :dead_code)
+
+  ##
+  # Register all supported LLM APIs for formatting output here
+  LlmProviders.register("openai", LlmProviders::OpenAi::Provider)
+  LlmProviders.register("stub", LlmProviders::Stub::Provider)
+end

data/prompts/agent.md

@@ -0,0 +1,53 @@
+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
+- **Debride**: Treat as lower-confidence static dead-code detection. Include only findings that are clearly actionable and avoid recommending deletion without checking dynamic call paths.
+
+## Output Format
+
+Output valid JSON matching this exact schema:
+
+```json
+{
+  "run": {
+    "timestamp": <integer from metadata>,
+    "checks": [<check names from metadata>],
+    "target_files": [<file paths from metadata>],
+    "findings": [
+      {
+        "tool_name": "<reek|flog|fasterer|debride>",
+        "tool_type": "<smell_detection|complexity|performance|dead_code>",
+        "check": "<specific check type>",
+        "filepath": "<relative file path>",
+        "line": <line number or null>,
+        "result": "<concise description of the issue>"
+      }
+    ]
+  },
+  "check_outputs": [
+    {
+      "check_name": "<check name>",
+      "tool_name": "<reek|flog|fasterer|debride>",
+      "tool_type": "<smell_detection|complexity|performance|dead_code>",
+      "extension": "<json|txt>",
+      "path": "<raw output artifact path>",
+      "raw_output": "<raw tool output>"
+    }
+  ],
+  "instructions": "Prioritized code quality findings for automated remediation."
+}
+```
+
+## Guidelines
+
+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

data/prompts/github.md

@@ -0,0 +1,29 @@
+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.
+
+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
+
+Debride:
+  Severity: Low
+  Notes: Lower-confidence static dead-code signal. Only report when the finding is specific, actionable, and unlikely to be a dynamic Rails call.
+
+
+You MUST NOT return so many items that the feedback is noisy and confusing. Limit yourself to maximum 10 comments.
+
+You MUST return your feedback in the Github Workflow Annotations format, as described on their website. (You can use this link as a source if you need to: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands).
+
+You SHOULD group feedback from the various tools in the Github workflow logs using the `::group::{title}` ...`::endgroup::` notation.

data/prompts/human.md

@@ -0,0 +1,23 @@
+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, Debride, 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 relatinon 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.
+
+Debride findings are lower-confidence static dead-code candidates. Do not recommend deleting code unless the finding is clearly supported by the changed code and dynamic call paths have been considered.
+
+The output will be printed in a unix terminal, and so colour-coded feedback is preferrable.
+
+1. Highest-impact issues first, with file and line references as clickable links when available.
+2. Suggested changes that are specific enough for an engineer or coding agent to implement.
+3. A short note if the automated checks found no meaningful issues.
+
+Finish your feedback with a short note (one or two sentences) that begin with: `Summary:`, and then summarise the report findings.

data/prompts/pr_review.md

@@ -0,0 +1,62 @@
+You are the pipeline interface between code quality tools and GitHub pull request review comments.
+
+You will collate data from code quality tools including Reek, Flog, Fasterer, and Debride. The raw output is noisy, so your job is to identify only the most useful comments for the engineer whose PR triggered this flow.
+
+You MUST NOT comment on the code diff itself unless the comment is directly supported by a tool finding.
+
+## Tool Thresholds
+
+- **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.
+- **Debride**: Lower-confidence static dead-code signal. Include only when the candidate method is clearly made obsolete by this PR, and do not suggest deletion without noting possible dynamic Rails calls.
+
+## 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.
+
+## Output Format
+
+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>"
+    }
+  ]
+}
+```
+
+
+## Comment format:
+
+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. 
+
+Example format:
+```
+This code appears to have X issue. That may be likely to cause Y problem. Consider an alternative soltion, such as Z.
+
+_(Ref: Reek TooManyStatements, DuplicateMethodCall; Fasterer HashKeysEach)_
+```
+
+## Empty output:
+
+If there are no high-confidence inline comments, return:
+
+```json
+{
+  "body": "Cleo quality review did not find any high-confidence issues worth inline PR comments.",
+  "comments": []
+}
+```

metadata

@@ -0,0 +1,141 @@
+--- !ruby/object:Gem::Specification
+name: cleo_quality_review
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Gavin Morrice
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: debride
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: fasterer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: flog
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: reek
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Runs local quality checks and summarizes their output for humans, agents,
+  or GitHub.
+email:
+- gavin@gavinmorrice.com
+executables:
+- check_quality
+extensions: []
+extra_rdoc_files: []
+files:
+- cleo_quality_review.gemspec
+- config/default.yml
+- exe/check_quality
+- lib/cleo_quality_review.rb
+- lib/cleo_quality_review/changes_diff.rb
+- lib/cleo_quality_review/checks.rb
+- lib/cleo_quality_review/checks/debride.rb
+- lib/cleo_quality_review/checks/fasterer.rb
+- lib/cleo_quality_review/checks/flog.rb
+- lib/cleo_quality_review/checks/quality_check.rb
+- lib/cleo_quality_review/checks/reek.rb
+- lib/cleo_quality_review/checks/registry.rb
+- lib/cleo_quality_review/cli.rb
+- lib/cleo_quality_review/command_result.rb
+- lib/cleo_quality_review/command_runner.rb
+- lib/cleo_quality_review/configuration.rb
+- lib/cleo_quality_review/diff_map.rb
+- lib/cleo_quality_review/formatter.rb
+- lib/cleo_quality_review/github_review_builder.rb
+- lib/cleo_quality_review/github_review_publisher.rb
+- lib/cleo_quality_review/llm_client.rb
+- lib/cleo_quality_review/llm_config.rb
+- lib/cleo_quality_review/llm_errors.rb
+- lib/cleo_quality_review/llm_logger.rb
+- lib/cleo_quality_review/llm_providers.rb
+- lib/cleo_quality_review/llm_providers/open_ai.rb
+- lib/cleo_quality_review/llm_providers/open_ai_config.rb
+- lib/cleo_quality_review/llm_providers/registry.rb
+- lib/cleo_quality_review/llm_providers/stub.rb
+- lib/cleo_quality_review/options.rb
+- lib/cleo_quality_review/prompt_builder.rb
+- lib/cleo_quality_review/prompt_loader.rb
+- lib/cleo_quality_review/result.rb
+- lib/cleo_quality_review/run.rb
+- 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/target_resolver.rb
+- lib/cleo_quality_review/version.rb
+- prompts/agent.md
+- prompts/github.md
+- prompts/human.md
+- prompts/pr_review.md
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Local Cleo code quality checks
+test_files: []