rails-doctor 0.1.0

data/lib/rails_doctor/agent/handoff.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "shellwords"
+require "time"
+
+module RailsDoctor
+  module Agent
+    class Handoff
+      attr_reader :agent_name, :project, :config, :runner, :options
+
+      def initialize(agent_name:, project:, config:, runner:, options:)
+        @agent_name = agent_name
+        @project = project
+        @config = config
+        @runner = runner
+        @options = options
+      end
+
+      def run(scan_result)
+        agent_config = config.agent(agent_name)
+        raise Error, "Unknown agent #{agent_name.inspect}" unless agent_config
+
+        findings = filtered_findings(scan_result.findings)
+        brief = build_brief(scan_result, findings)
+        brief_path = write_brief(brief)
+
+        output = +"Wrote agent brief: #{brief_path}\n"
+        output << "Findings included: #{findings.size}\n"
+
+        if options[:apply]
+          ensure_clean_worktree!(agent_config)
+          command = "#{agent_config.fetch("command")} #{Shellwords.escape(brief_path)}"
+          command_result = runner.run(command, timeout_seconds: 900)
+          audit_path = write_audit(scan_result, findings, brief_path, command, command_result)
+          output << "Invoked #{agent_name}: exit #{command_result.exit_status}\n"
+          output << "Audit trail: #{audit_path}\n"
+          output << command_result.stdout unless command_result.stdout.to_s.empty?
+          output << command_result.stderr unless command_result.stderr.to_s.empty?
+        else
+          output << "No agent was invoked. Re-run with --apply to execute #{agent_name}.\n"
+        end
+
+        output
+      end
+
+      private
+
+      def filtered_findings(findings)
+        filtered = findings
+        if options[:severity]
+          threshold = SEVERITY_WEIGHTS.fetch(options[:severity], 0)
+          filtered = filtered.select { |finding| SEVERITY_WEIGHTS.fetch(finding.severity, 0) >= threshold }
+        end
+        filtered = filtered.select { |finding| Array(options[:changed_files]).include?(finding.file) } if options[:changed_only]
+        filtered.first(options.fetch(:max_findings, 10))
+      end
+
+      def build_brief(scan_result, findings)
+        lines = []
+        lines << "# Rails Doctor Agent Brief"
+        lines << ""
+        lines << "You are repairing findings from Rails Doctor. Make minimal, behavior-preserving changes. Do not commit automatically."
+        lines << ""
+        lines << "Project: #{scan_result.project_root}"
+        lines << "Profile: #{scan_result.profile}"
+        lines << "Overall score: #{scan_result.score&.overall}"
+        lines << "Changed-files score: #{scan_result.score&.changed_files}"
+        lines << coverage_brief(scan_result)
+        lines << ""
+        lines << "## Findings"
+        findings.each do |finding|
+          lines << ""
+          lines << "### #{finding.severity.upcase}: #{finding.message}"
+          lines << "- ID: #{finding.id}"
+          lines << "- Tool: #{finding.tool}"
+          lines << "- Category: #{finding.category}"
+          lines << "- Location: #{[finding.file, finding.line].compact.join(":")}" if finding.file
+          lines << "- Recommendation: #{finding.recommendation}"
+          lines << "- Agent instruction: #{finding.agent_instruction}"
+          lines << "- Suggested commands: #{finding.suggested_commands.join(", ")}" if finding.suggested_commands.any?
+        end
+        lines << ""
+        lines << "After changes, run Rails Doctor again and the relevant test command."
+        lines.join("\n")
+      end
+
+      def coverage_brief(scan_result)
+        coverage = scan_result.coverage
+        return "Coverage: not captured" unless coverage
+        return "Coverage: #{coverage.status} at #{coverage.report_path}" unless coverage.available
+
+        lines = []
+        lines << "Coverage: #{format_percent(coverage.line_percent)} lines"
+        low_files = low_coverage_files(coverage)
+        if low_files.any?
+          lines << ""
+          lines << "## Coverage"
+          low_files.first(10).each do |file|
+            lines << "- #{file.fetch(:file)}: #{format_percent(file.fetch(:line_percent))} lines (#{file.fetch(:covered_lines)}/#{file.fetch(:total_lines)})"
+          end
+        end
+        lines.join("\n")
+      end
+
+      def low_coverage_files(coverage)
+        low_files = coverage.top_files.select { |file| file[:below_threshold] }
+        (coverage.changed_files_below_threshold + low_files).uniq { |file| file.fetch(:file) }
+      end
+
+      def format_percent(value)
+        return "n/a" if value.nil?
+
+        format("%.2f%%", value)
+      end
+
+      def write_brief(content)
+        dir = project.join(".rails-doctor/agent-briefs")
+        FileUtils.mkdir_p(dir)
+        path = File.join(dir, "#{timestamp}-#{agent_name}.md")
+        File.write(path, content)
+        path
+      end
+
+      def write_audit(scan_result, findings, brief_path, command, command_result)
+        dir = project.join(".rails-doctor/agent-runs")
+        FileUtils.mkdir_p(dir)
+        path = File.join(dir, "#{timestamp}-#{agent_name}.json")
+        payload = {
+          generated_at: Time.now.iso8601,
+          agent: agent_name,
+          command: command,
+          exit_status: command_result.exit_status,
+          brief_path: brief_path,
+          finding_ids: findings.map(&:id),
+          score: scan_result.score&.to_h,
+          stdout: command_result.stdout,
+          stderr: command_result.stderr,
+          changed_files_after: project.changed_files
+        }
+        File.write(path, JSON.pretty_generate(payload))
+        path
+      end
+
+      def ensure_clean_worktree!(agent_config)
+        return if options[:allow_dirty]
+        return unless agent_config.fetch("apply_requires_clean_worktree", true)
+        return unless project.dirty_worktree?
+
+        raise Error, "Refusing to invoke #{agent_name} on a dirty worktree. Commit/stash changes or pass --allow-dirty."
+      end
+
+      def timestamp
+        Time.now.utc.strftime("%Y%m%d%H%M%S")
+      end
+    end
+  end
+end

data/lib/rails_doctor/checks/rails_checks.rb

@@ -0,0 +1,371 @@
+# frozen_string_literal: true
+
+module RailsDoctor
+  module Checks
+    class RailsChecks
+      NAME = "rails_checks"
+
+      attr_reader :project, :config, :runner, :profile, :changed_files
+
+      def initialize(project:, config:, runner:, profile:, changed_files: [])
+        @project = project
+        @config = config
+        @runner = runner
+        @profile = profile
+        @changed_files = changed_files
+      end
+
+      def name
+        NAME
+      end
+
+      def available?
+        project.rails_app?
+      end
+
+      def unavailable_reason
+        "This does not look like a Rails app."
+      end
+
+      def install_guidance
+        "Run Rails Doctor from the root of a Rails 7.1+ application."
+      end
+
+      def run
+        findings = []
+        findings.concat(missing_foreign_key_indexes)
+        findings.concat(missing_unique_indexes)
+        findings.concat(route_action_view_findings)
+        findings.concat(large_artifact_findings)
+        findings.concat(todo_density_findings)
+        findings.concat(missing_test_counterparts)
+        findings.concat(coverage_gap_findings)
+
+        {
+          tool_run: ToolRun.new(
+            name: name,
+            available: true,
+            skipped: false,
+            exit_status: 0,
+            metadata: { checks: %w[indexes uniqueness routes views size todos tests coverage-gaps] }
+          ),
+          findings: findings
+        }
+      end
+
+      private
+
+      def schema
+        @schema ||= begin
+          path = project.join("db/schema.rb")
+          File.exist?(path) ? File.read(path) : ""
+        end
+      end
+
+      def parsed_schema
+        @parsed_schema ||= begin
+          tables = Hash.new { |hash, key| hash[key] = { columns: [], indexes: [] } }
+
+          schema.scan(/create_table\s+"([^"]+)".*?do \|t\|(.*?)^\s*end/m).each do |table, block|
+            block.scan(/t\.(?:bigint|integer|string|uuid)\s+"([^"]+)"/).each do |column|
+              tables[table][:columns] << column.first
+            end
+          end
+
+          schema.scan(/add_index\s+"([^"]+)",\s+\[([^\]]+)\](.*)$/).each do |table, columns, options|
+            tables[table][:indexes] << {
+              columns: columns.scan(/"([^"]+)"/).flatten,
+              unique: options.include?("unique: true")
+            }
+          end
+
+          tables
+        end
+      end
+
+      def missing_foreign_key_indexes
+        parsed_schema.flat_map do |table, data|
+          data[:columns].grep(/_id\z/).each_with_object([]) do |column, findings|
+            next if indexed?(table, [column])
+
+            findings << Finding.new(
+              severity: "high",
+              category: "database-integrity",
+              tool: name,
+              file: "db/schema.rb",
+              confidence: "high",
+              message: "#{table}.#{column} has no index",
+              recommendation: "Add an index for the foreign key column to avoid slow association lookups.",
+              agent_instruction: "Create a migration that adds an index on #{table}.#{column}. For PostgreSQL production apps, prefer a concurrent index path compatible with strong_migrations.",
+              suggested_commands: ["bin/rails generate migration AddIndexTo#{camelize(table)}#{camelize(column)}"]
+            )
+          end
+        end
+      end
+
+      def missing_unique_indexes
+        project.files("app/models/**/*.rb").flat_map do |path|
+          relative = project.relative(path)
+          table = table_for_model_path(path)
+          next [] unless table
+
+          File.read(path).scan(/validates\s+:([a-zA-Z_]\w*).*?uniqueness:\s*(?:true|\{)/m).each_with_object([]) do |column_match, findings|
+            column = column_match.first
+            next if unique_indexed?(table, [column])
+
+            findings << Finding.new(
+              severity: "high",
+              category: "database-integrity",
+              tool: name,
+              file: relative,
+              confidence: "medium",
+              message: "#{table}.#{column} has a Rails uniqueness validation without a unique database index",
+              recommendation: "Back uniqueness validations with a unique index to prevent race-condition duplicates.",
+              agent_instruction: "Add a unique index migration for #{table}.#{column}, handle existing duplicate data if necessary, and rerun tests.",
+              suggested_commands: ["bin/rails generate migration AddUniqueIndexTo#{camelize(table)}#{camelize(column)}"]
+            )
+          end
+        end
+      end
+
+      def route_action_view_findings
+        route_map = routes
+        findings = []
+
+        route_map.each do |controller, actions|
+          controller_file = project.join("app/controllers/#{controller}_controller.rb")
+          unless File.exist?(controller_file)
+            findings << Finding.new(
+              severity: "high",
+              category: "routing",
+              tool: name,
+              file: "config/routes.rb",
+              confidence: "high",
+              message: "Routes reference missing #{controller}_controller.rb",
+              recommendation: "Create the controller or remove/rename the route.",
+              agent_instruction: "Align routes with real controller names. Prefer removing stale routes over creating empty controllers."
+            )
+            next
+          end
+
+          controller_source = File.read(controller_file)
+          defined_actions = controller_source.scan(/^\s*def\s+([a-zA-Z_]\w*[!?=]?)/).flatten
+          actions.each do |action|
+            unless defined_actions.include?(action)
+              findings << Finding.new(
+                severity: "high",
+                category: "routing",
+                tool: name,
+                file: project.relative(controller_file),
+                confidence: "high",
+                message: "Route points to missing #{controller}##{action}",
+                recommendation: "Implement the action or update/remove the route.",
+                agent_instruction: "Do not add an empty action. Determine the intended route behavior, then implement or remove the stale route."
+              )
+              next
+            end
+
+            next if explicit_response?(controller_source, action)
+            next if template_exists?(controller, action)
+
+            findings << Finding.new(
+              severity: "medium",
+              category: "routing",
+              tool: name,
+              file: project.relative(controller_file),
+              confidence: "medium",
+              message: "#{controller}##{action} has no matching template or explicit response",
+              recommendation: "Add a template or explicit render/redirect/head response.",
+              agent_instruction: "Inspect the action intent. Add the missing view or explicit response and cover the route with a request/controller test."
+            )
+          end
+
+          (defined_actions - actions).each do |action|
+            next if %w[initialize].include?(action)
+
+            findings << Finding.new(
+              severity: "low",
+              category: "dead-code",
+              tool: name,
+              file: project.relative(controller_file),
+              confidence: "low",
+              message: "#{controller}##{action} is not referenced by simple route analysis",
+              recommendation: "Review whether this action is reached by custom routing or can be removed.",
+              agent_instruction: "Do not remove this action automatically. First search routes, tests, links, and callers for dynamic usage."
+            )
+          end
+        end
+
+        findings
+      end
+
+      def large_artifact_findings
+        thresholds = config.threshold("large_file_lines") || {}
+        patterns = {
+          "model" => "app/models/**/*.rb",
+          "controller" => "app/controllers/**/*_controller.rb",
+          "job" => "app/jobs/**/*.rb",
+          "mailer" => "app/mailers/**/*.rb",
+          "view" => "app/views/**/*"
+        }
+
+        patterns.flat_map do |kind, pattern|
+          threshold = thresholds.fetch(kind, 200).to_i
+          project.files(pattern).each_with_object([]) do |path, findings|
+            next if File.directory?(path)
+
+            lines = File.readlines(path).size
+            next if lines <= threshold
+
+            findings << Finding.new(
+              severity: "medium",
+              category: "maintainability-hotspot",
+              tool: name,
+              file: project.relative(path),
+              confidence: "medium",
+              message: "#{kind} file has #{lines} lines, above the #{threshold}-line threshold",
+              recommendation: "Treat this as a refactor hotspot, especially if the file is frequently changed.",
+              agent_instruction: "Avoid expanding this file further. If changing it, prefer extracting one cohesive behavior with tests.",
+              metadata: { lines: lines, threshold: threshold, artifact_type: kind }
+            )
+          end
+        end
+      end
+
+      def todo_density_findings
+        threshold = config.threshold("todo_density_per_100_lines").to_f
+        files = project.files("{app,lib,config}/**/*.{rb,erb,haml,slim}")
+
+        files.each_with_object([]) do |path, findings|
+          lines = File.readlines(path)
+          todo_count = lines.count { |line| line.match?(/\b(TODO|FIXME|HACK)\b/i) }
+          next if todo_count.zero?
+
+          density = todo_count / [lines.size, 1].max.to_f * 100
+          next if density < threshold && !project.changed_files.include?(project.relative(path))
+
+          findings << Finding.new(
+            severity: density >= threshold ? "medium" : "low",
+            category: "technical-debt",
+            tool: name,
+            file: project.relative(path),
+            confidence: "medium",
+            message: "#{todo_count} TODO/FIXME/HACK marker#{todo_count == 1 ? "" : "s"} in #{lines.size} lines",
+            recommendation: "Convert stale markers into tracked work or resolve them while the context is fresh.",
+            agent_instruction: "Do not delete markers without addressing or preserving the underlying work item. Prefer resolving changed-file markers."
+          )
+        end
+      end
+
+      def missing_test_counterparts
+        changed = changed_files
+        return [] if changed.empty?
+
+        changed.grep(%r{\Aapp/(models|controllers|jobs|mailers)/.+\.rb\z}).each_with_object([]) do |file, findings|
+          expected = expected_test_paths(file)
+          next if expected.any? { |path| File.exist?(project.join(path)) }
+
+          findings << Finding.new(
+            severity: "medium",
+            category: "test-coverage",
+            tool: name,
+            file: file,
+            confidence: "medium",
+            message: "Changed app file has no obvious test/spec counterpart",
+            recommendation: "Add or update a nearby test for this changed Rails artifact.",
+            agent_instruction: "Create the missing test/spec counterpart or update an existing integration/request test that covers this behavior.",
+            metadata: { expected_paths: expected }
+          )
+        end
+      end
+
+      def coverage_gap_findings
+        findings = []
+        unless project.gem_declared?("brakeman")
+          findings << coverage_gap("security", "Brakeman is unavailable, so Rails security coverage is incomplete.", "brakeman")
+        end
+        unless project.gem_declared?("reek")
+          findings << coverage_gap("code-smell", "Reek is unavailable, so code smell coverage is incomplete.", "reek")
+        end
+        unless project.gem_declared?("strong_migrations")
+          findings << coverage_gap("migration-safety", "Strong Migrations is unavailable, so migration safety coverage is incomplete.", "strong_migrations")
+        end
+        findings
+      end
+
+      def coverage_gap(_category, message, missing_tool)
+        Finding.new(
+          severity: "info",
+          category: "coverage-gap",
+          tool: name,
+          confidence: "high",
+          message: message,
+          recommendation: "Run rails-doctor init to add #{missing_tool} coverage.",
+          agent_instruction: "Do not modify application code for this finding. Install/configure #{missing_tool} if the project wants this coverage."
+        )
+      end
+
+      def indexed?(table, columns)
+        parsed_schema.fetch(table, { indexes: [] })[:indexes].any? { |index| index[:columns] == columns }
+      end
+
+      def unique_indexed?(table, columns)
+        parsed_schema.fetch(table, { indexes: [] })[:indexes].any? { |index| index[:columns] == columns && index[:unique] }
+      end
+
+      def table_for_model_path(path)
+        basename = File.basename(path, ".rb")
+        pluralize(basename)
+      end
+
+      def routes
+        path = project.join("config/routes.rb")
+        return {} unless File.exist?(path)
+
+        source = File.read(path)
+        route_map = Hash.new { |hash, key| hash[key] = [] }
+
+        source.scan(/to:\s*["']([a-zA-Z0-9_\/]+)#([a-zA-Z_]\w*)["']/).each do |controller, action|
+          route_map[controller] << action
+        end
+
+        source.scan(/resources\s+:([a-zA-Z_]\w*)/).each do |resource|
+          controller = resource.first
+          route_map[controller].concat(%w[index show new create edit update destroy])
+        end
+
+        route_map.transform_values { |actions| actions.uniq.sort }
+      end
+
+      def explicit_response?(source, action)
+        body = source[/^\s*def\s+#{Regexp.escape(action)}\b(.*?)^\s*end/m, 1].to_s
+        body.match?(/\b(render|redirect_to|head|respond_to|send_data|send_file)\b/)
+      end
+
+      def template_exists?(controller, action)
+        Dir.glob(project.join("app/views/#{controller}/#{action}.*")).any?
+      end
+
+      def expected_test_paths(file)
+        suffix = file.delete_prefix("app/").sub(/\.rb\z/, "")
+        [
+          "test/#{suffix}_test.rb",
+          "spec/#{suffix}_spec.rb",
+          "spec/requests/#{File.basename(file, ".rb")}_spec.rb",
+          "test/integration/#{File.basename(file, ".rb")}_test.rb"
+        ]
+      end
+
+      def camelize(value)
+        value.split("_").map(&:capitalize).join
+      end
+
+      def pluralize(value)
+        return value.sub(/y\z/, "ies") if value.end_with?("y")
+        return value if value.end_with?("s")
+
+        "#{value}s"
+      end
+    end
+  end
+end