rails-doctor 0.1.0

data/examples/report.md

@@ -0,0 +1,261 @@
+# Rails Doctor Report
+
+- Profile: `deep`
+- Overall score: `0/100`
+- Changed-files score: `100/100`
+- Confidence: `100%`
+- Coverage: `48.00% lines`
+- Findings: `24`
+- Duration: `600ms`
+
+## Coverage
+
+- Line coverage: `48.00%`
+- Line threshold: `90.00%`
+- Covered lines: `12/25`
+- Branch coverage: `50.00%`
+
+Low-coverage files:
+- `app/controllers/posts_controller.rb`: 22.22% lines (2/9)
+- `app/models/post.rb`: 44.44% lines (4/9)
+
+## Severity Breakdown
+
+- `medium`: 10
+- `critical`: 1
+- `high`: 10
+- `low`: 3
+
+## Skipped Tools
+
+No tools were skipped.
+
+## Top Findings
+
+### CRITICAL: SQL Injection: Possible SQL injection
+
+- Tool: `brakeman`
+- Category: `security`
+- Location: `app/models/post.rb:8`
+- Confidence: `high`
+
+Review Brakeman guidance: https://brakemanscanner.org/docs/warning_types/sql_injection/
+
+**Agent instruction:** Fix this security finding with the smallest behavior-preserving change. Prefer framework-safe APIs and add regression tests.
+
+### HIGH: rack: Example vulnerability
+
+- Tool: `bundler_audit`
+- Category: `dependency-security`
+- Location: `Gemfile.lock`
+- Confidence: `high`
+
+Update rack to a patched version and rerun Bundler Audit.
+
+**Agent instruction:** Update the vulnerable gem conservatively, refresh the lockfile, and run the test suite.
+
+### HIGH: Prosopite: N+1 queries detected for Post => [:user]
+
+- Tool: `test_runner`
+- Category: `runtime-n-plus-one`
+- Confidence: `medium`
+
+Fix the N+1 query by eager loading or adjusting the query path exercised by tests.
+
+**Agent instruction:** Use includes/preload/eager_load or query restructuring. Verify with the same test command.
+
+### HIGH: posts.user_id has no index
+
+- Tool: `rails_checks`
+- Category: `database-integrity`
+- Location: `db/schema.rb`
+- Confidence: `high`
+
+Add an index for the foreign key column to avoid slow association lookups.
+
+**Agent instruction:** Create a migration that adds an index on posts.user_id. For PostgreSQL production apps, prefer a concurrent index path compatible with strong_migrations.
+
+### HIGH: users.email has a Rails uniqueness validation without a unique database index
+
+- Tool: `rails_checks`
+- Category: `database-integrity`
+- Location: `app/models/user.rb`
+- Confidence: `medium`
+
+Back uniqueness validations with a unique index to prevent race-condition duplicates.
+
+**Agent instruction:** Add a unique index migration for users.email, handle existing duplicate data if necessary, and rerun tests.
+
+### HIGH: Routes reference missing ghosts_controller.rb
+
+- Tool: `rails_checks`
+- Category: `routing`
+- Location: `config/routes.rb`
+- Confidence: `high`
+
+Create the controller or remove/rename the route.
+
+**Agent instruction:** Align routes with real controller names. Prefer removing stale routes over creating empty controllers.
+
+### HIGH: Route points to missing posts#create
+
+- Tool: `rails_checks`
+- Category: `routing`
+- Location: `app/controllers/posts_controller.rb`
+- Confidence: `high`
+
+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.
+
+### HIGH: Route points to missing posts#destroy
+
+- Tool: `rails_checks`
+- Category: `routing`
+- Location: `app/controllers/posts_controller.rb`
+- Confidence: `high`
+
+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.
+
+### HIGH: Route points to missing posts#edit
+
+- Tool: `rails_checks`
+- Category: `routing`
+- Location: `app/controllers/posts_controller.rb`
+- Confidence: `high`
+
+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.
+
+### HIGH: Route points to missing posts#new
+
+- Tool: `rails_checks`
+- Category: `routing`
+- Location: `app/controllers/posts_controller.rb`
+- Confidence: `high`
+
+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.
+
+### HIGH: Route points to missing posts#update
+
+- Tool: `rails_checks`
+- Category: `routing`
+- Location: `app/controllers/posts_controller.rb`
+- Confidence: `high`
+
+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.
+
+### MEDIUM: DEPRECATION WARNING: old API is deprecated
+
+- Tool: `test_runner`
+- Category: `deprecation`
+- Confidence: `medium`
+
+Resolve deprecation warnings before framework or gem upgrades make them failures.
+
+**Agent instruction:** Update the deprecated API usage and add a regression test when behavior could change.
+
+### MEDIUM: Line coverage 48.00% is below the 90.00% threshold
+
+- Tool: `test_coverage`
+- Category: `test-coverage`
+- Confidence: `high`
+
+Add tests for uncovered application code, starting with the lowest-coverage files.
+
+**Agent instruction:** Prioritize behavior tests for uncovered app/lib code. Use the coverage metadata to start with files below the configured threshold.
+
+### MEDIUM: app/controllers/posts_controller.rb line coverage 22.22% is below the 80.00% per-file threshold
+
+- Tool: `test_coverage`
+- Category: `test-coverage`
+- Location: `app/controllers/posts_controller.rb`
+- Confidence: `high`
+
+Add focused tests that exercise the uncovered behavior in this file.
+
+**Agent instruction:** Add or update tests for this file before expanding the implementation. Prefer behavior-level tests that cover the missing branches or lines.
+
+### MEDIUM: app/models/post.rb line coverage 44.44% is below the 80.00% per-file threshold
+
+- Tool: `test_coverage`
+- Category: `test-coverage`
+- Location: `app/models/post.rb`
+- Confidence: `high`
+
+Add focused tests that exercise the uncovered behavior in this file.
+
+**Agent instruction:** Add or update tests for this file before expanding the implementation. Prefer behavior-level tests that cover the missing branches or lines.
+
+### MEDIUM: High complexity score 32.5 for Post#publish!
+
+- Tool: `flog`
+- Category: `complexity`
+- Location: `app/models/post.rb:4`
+- Confidence: `medium`
+
+Extract simpler methods or objects around the complex branch.
+
+**Agent instruction:** Reduce complexity with behavior-preserving extraction. Do not combine this with unrelated cleanup.
+
+### MEDIUM: Similar code group 1 across app/models/post.rb:4, app/models/user.rb:2
+
+- Tool: `flay`
+- Category: `duplication`
+- Location: `app/models/post.rb:4`
+- Confidence: `medium`
+
+Review whether this duplication is intentional. Extract shared behavior only if the abstraction is clear.
+
+**Agent instruction:** Do not blindly abstract. Compare the duplicated code paths, preserve semantics, and add tests if extracting shared code.
+
+### MEDIUM: 1 TODO/FIXME/HACK marker in 10 lines
+
+- Tool: `rails_checks`
+- Category: `technical-debt`
+- Location: `app/models/post.rb`
+- Confidence: `medium`
+
+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.
+
+### MEDIUM: posts#show has no matching template or explicit response
+
+- Tool: `rails_checks`
+- Category: `routing`
+- Location: `app/controllers/posts_controller.rb`
+- Confidence: `medium`
+
+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.
+
+### MEDIUM: TooManyStatements: has the smell of too many statements
+
+- Tool: `reek`
+- Category: `code-smell`
+- Location: `app/models/post.rb:4`
+- Confidence: `high`
+
+Refactor the local smell without broad behavior changes.
+
+**Agent instruction:** Refactor only the affected method/class. Preserve public behavior and add or run tests around the changed code.
+
+
+## Hotspots
+
+- `app/controllers/posts_controller.rb`: score 42, 8 findings, churn 0, changed=false
+- `app/models/post.rb`: score 33, 7 findings, churn 0, changed=false
+- `Gemfile.lock`: score 8, 2 findings, churn 0, changed=false
+- `db/schema.rb`: score 7, 1 findings, churn 0, changed=false
+- `app/models/user.rb`: score 7, 1 findings, churn 0, changed=false
+- `config/routes.rb`: score 7, 1 findings, churn 0, changed=false
+- `config/initializers/strong_migrations.rb`: score 1, 1 findings, churn 0, changed=false

data/examples/report.txt

@@ -0,0 +1,45 @@
+Rails Doctor
+============
+Profile: deep
+Score: 0/100 overall, 100/100 changed files
+Confidence: 100%
+Coverage: 48.00% lines (threshold 90.00%)
+Findings: critical=1, high=10, medium=10, low=3, info=0
+Duration: 600ms
+
+Low coverage files
+- app/controllers/posts_controller.rb: 22.22% lines
+- app/models/post.rb: 44.44% lines
+
+Top fixes
+- [critical] SQL Injection: Possible SQL injection
+  app/models/post.rb:8
+  Review Brakeman guidance: https://brakemanscanner.org/docs/warning_types/sql_injection/
+- [high] rack: Example vulnerability
+  Gemfile.lock
+  Update rack to a patched version and rerun Bundler Audit.
+- [high] Prosopite: N+1 queries detected for Post => [:user]
+  2
+  Fix the N+1 query by eager loading or adjusting the query path exercised by tests.
+- [high] posts.user_id has no index
+  db/schema.rb
+  Add an index for the foreign key column to avoid slow association lookups.
+- [high] users.email has a Rails uniqueness validation without a unique database index
+  app/models/user.rb
+  Back uniqueness validations with a unique index to prevent race-condition duplicates.
+- [high] Routes reference missing ghosts_controller.rb
+  config/routes.rb
+  Create the controller or remove/rename the route.
+- [high] Route points to missing posts#create
+  app/controllers/posts_controller.rb
+  Implement the action or update/remove the route.
+- [high] Route points to missing posts#destroy
+  app/controllers/posts_controller.rb
+  Implement the action or update/remove the route.
+
+Hotspots
+- app/controllers/posts_controller.rb: score 42, 8 findings, churn 0
+- app/models/post.rb: score 33, 7 findings, churn 0
+- Gemfile.lock: score 8, 2 findings, churn 0
+- db/schema.rb: score 7, 1 findings, churn 0
+- app/models/user.rb: score 7, 1 findings, churn 0

data/exe/rails-doctor

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "rails_doctor/cli"
+
+exit RailsDoctor::CLI.new(ARGV).run

data/lib/rails_doctor/adapters/base.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RailsDoctor
+  module Adapters
+    class Base
+      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
+        self.class::NAME
+      end
+
+      def command
+        config.command(name)
+      end
+
+      def available?
+        return false if command.to_s.strip.empty?
+
+        declared_gems.any? { |gem| project.gem_declared?(gem) } || executable_names.any? { |exe| project.command_available?(exe) }
+      end
+
+      def unavailable_reason
+        "#{name} is not installed or available in this project."
+      end
+
+      def install_guidance
+        "Run rails-doctor init to add #{declared_gems.first || name} to the appropriate development/test group."
+      end
+
+      def run
+        command_result = runner.run(command, timeout_seconds: timeout_seconds)
+        {
+          tool_run: ToolRun.new(
+            name: name,
+            available: true,
+            skipped: false,
+            command: command,
+            exit_status: command_result.exit_status,
+            duration_ms: command_result.duration_ms,
+            stdout: command_result.stdout,
+            stderr: command_result.stderr,
+            metadata: metadata(command_result)
+          ),
+          findings: parse(command_result)
+        }
+      end
+
+      private
+
+      def declared_gems
+        []
+      end
+
+      def executable_names
+        [name]
+      end
+
+      def timeout_seconds
+        120
+      end
+
+      def metadata(_command_result)
+        {}
+      end
+
+      def parse_json(output)
+        JSON.parse(output.to_s)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def command_failed_finding(command_result, severity: "medium")
+        return nil if command_result.exit_status == 0
+
+        output = [command_result.stderr, command_result.stdout].compact.join("\n").strip
+        Finding.new(
+          severity: severity,
+          category: "tool-execution",
+          tool: name,
+          confidence: "high",
+          message: "#{name} exited with status #{command_result.exit_status}",
+          recommendation: "Run #{command.inspect} directly to inspect the underlying tool failure.",
+          agent_instruction: "Do not blindly edit app code. First determine whether #{name} failed because of configuration, missing dependencies, or a real project issue.",
+          metadata: { output_excerpt: output[0, 1_000] }
+        )
+      end
+
+      def severity_from_tool(value, default: "medium")
+        case value.to_s.downcase
+        when "fatal", "error", "critical" then "critical"
+        when "high" then "high"
+        when "warning", "warn", "medium" then "medium"
+        when "refactor", "convention", "low", "info" then "low"
+        else default
+        end
+      end
+    end
+  end
+end

data/lib/rails_doctor/adapters/brakeman.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module RailsDoctor
+  module Adapters
+    class Brakeman < Base
+      NAME = "brakeman"
+
+      private
+
+      def declared_gems
+        ["brakeman"]
+      end
+
+      def parse(command_result)
+        json = parse_json(command_result.stdout)
+        return [command_failed_finding(command_result, severity: "high")].compact unless json
+
+        json.fetch("warnings", []).map do |warning|
+          confidence = warning.fetch("confidence", "Medium").downcase
+          Finding.new(
+            severity: brakeman_severity(warning),
+            category: "security",
+            tool: name,
+            file: warning["file"],
+            line: warning["line"],
+            confidence: confidence,
+            message: "#{warning["warning_type"]}: #{warning["message"]}",
+            recommendation: warning["link"] ? "Review Brakeman guidance: #{warning["link"]}" : "Review and fix the security warning.",
+            agent_instruction: "Fix this security finding with the smallest behavior-preserving change. Prefer framework-safe APIs and add regression tests.",
+            metadata: { code: warning["code"], fingerprint: warning["fingerprint"] }.compact
+          )
+        end
+      end
+
+      def brakeman_severity(warning)
+        type = warning["warning_type"].to_s.downcase
+        return "critical" if type.match?(/sql|command|mass assignment|deserial/i)
+
+        case warning["confidence"].to_s.downcase
+        when "high" then "high"
+        when "weak" then "low"
+        else "medium"
+        end
+      end
+    end
+  end
+end

data/lib/rails_doctor/adapters/bundler_audit.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module RailsDoctor
+  module Adapters
+    class BundlerAudit < Base
+      NAME = "bundler_audit"
+
+      private
+
+      def declared_gems
+        ["bundler-audit"]
+      end
+
+      def executable_names
+        ["bundle-audit"]
+      end
+
+      def parse(command_result)
+        json = parse_json(command_result.stdout)
+        return [command_failed_finding(command_result, severity: "high")].compact unless json
+
+        results = json["results"] || json["vulnerabilities"] || []
+        results.map do |entry|
+          advisory = entry["advisory"] || entry
+          gem = entry["gem"] || {}
+          gem_name = gem["name"] || entry["name"] || advisory["gem"]
+          title = advisory["title"] || advisory["description"] || "Vulnerable dependency"
+          Finding.new(
+            severity: advisory_severity(advisory),
+            category: "dependency-security",
+            tool: name,
+            file: "Gemfile.lock",
+            confidence: "high",
+            message: "#{gem_name}: #{title}",
+            recommendation: "Update #{gem_name} to a patched version and rerun Bundler Audit.",
+            agent_instruction: "Update the vulnerable gem conservatively, refresh the lockfile, and run the test suite.",
+            suggested_commands: ["bundle update #{gem_name}", "bundle exec bundle-audit check"],
+            metadata: { advisory: advisory["id"] || advisory["cve"], url: advisory["url"] }.compact
+          )
+        end
+      end
+
+      def advisory_severity(advisory)
+        criticality = advisory["criticality"].to_s.downcase
+        return "critical" if criticality == "critical"
+        return "high" if criticality == "high"
+        return "medium" if criticality == "medium"
+
+        score = advisory["cvss_v3"] || advisory["cvss"]
+        score.to_f >= 9 ? "critical" : score.to_f >= 7 ? "high" : "medium"
+      end
+    end
+  end
+end

data/lib/rails_doctor/adapters/dependency_freshness.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module RailsDoctor
+  module Adapters
+    class DependencyFreshness < Base
+      NAME = "dependency_freshness"
+
+      def available?
+        File.exist?(project.join("Gemfile.lock")) && project.command_available?("bundle")
+      end
+
+      def install_guidance
+        "Install Bundler and ensure Gemfile.lock is present before running dependency freshness checks."
+      end
+
+      private
+
+      def executable_names
+        ["bundle"]
+      end
+
+      def timeout_seconds
+        180
+      end
+
+      def parse(command_result)
+        return [] if command_result.exit_status == 0 && command_result.stdout.strip.empty?
+
+        lines = command_result.stdout.lines.map(&:strip).reject(&:empty?)
+        lines.each_with_object([]) do |line, findings|
+          next unless line.include?(" ")
+
+          gem_name = line.split(/[ (]/).first
+          next if gem_name.to_s.empty?
+
+          findings << Finding.new(
+            severity: "low",
+            category: "dependency-freshness",
+            tool: name,
+            file: "Gemfile.lock",
+            confidence: "medium",
+            message: "#{gem_name} appears to be outdated",
+            recommendation: "Review the update risk and update in a separate dependency-focused change.",
+            agent_instruction: "Do not batch this with feature work. Update #{gem_name} conservatively and run the full test suite.",
+            suggested_commands: ["bundle update #{gem_name}"]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/rails_doctor/adapters/flay.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RailsDoctor
+  module Adapters
+    class Flay < Base
+      NAME = "flay"
+
+      private
+
+      def declared_gems
+        ["flay"]
+      end
+
+      def parse(command_result)
+        output = command_result.stdout.to_s
+        failed = command_failed_finding(command_result, severity: "medium")
+        return [failed].compact if failed && output.strip.empty?
+
+        groups = output.split(/Similar code found in/).drop(1)
+        groups.map.with_index(1) do |group, index|
+          files = group.scan(/([A-Za-z0-9_\/.-]+\.rb):(\d+)/).map { |file, line| "#{file}:#{line}" }
+          next if files.empty?
+
+          file, line_no = files.first.split(":")
+          Finding.new(
+            severity: "medium",
+            category: "duplication",
+            tool: name,
+            file: file,
+            line: line_no.to_i,
+            confidence: "medium",
+            message: "Similar code group #{index} across #{files.uniq.first(4).join(", ")}",
+            recommendation: "Review whether this duplication is intentional. Extract shared behavior only if the abstraction is clear.",
+            agent_instruction: "Do not blindly abstract. Compare the duplicated code paths, preserve semantics, and add tests if extracting shared code.",
+            metadata: { locations: files.uniq }
+          )
+        end.compact
+      end
+    end
+  end
+end

data/lib/rails_doctor/adapters/flog.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RailsDoctor
+  module Adapters
+    class Flog < Base
+      NAME = "flog"
+
+      private
+
+      def declared_gems
+        ["flog"]
+      end
+
+      def parse(command_result)
+        failed = command_failed_finding(command_result, severity: "medium")
+        return [failed].compact if failed && command_result.stdout.strip.empty?
+
+        threshold = config.threshold("flog_high_score").to_f
+        command_result.stdout.lines.each_with_object([]) do |line, findings|
+          next unless line =~ /^\s*(\d+(?:\.\d+)?)\s+(.+?)(?:\s+([A-Za-z0-9_\/.-]+\.rb):(\d+))?\s*$/
+
+          score = Regexp.last_match(1).to_f
+          next if score < threshold
+
+          findings << Finding.new(
+            severity: score >= threshold * 2 ? "high" : "medium",
+            category: "complexity",
+            tool: name,
+            file: Regexp.last_match(3),
+            line: Regexp.last_match(4)&.to_i,
+            confidence: "medium",
+            message: "High complexity score #{score.round(1)} for #{Regexp.last_match(2).strip}",
+            recommendation: "Extract simpler methods or objects around the complex branch.",
+            agent_instruction: "Reduce complexity with behavior-preserving extraction. Do not combine this with unrelated cleanup.",
+            metadata: { flog_score: score }
+          )
+        end
+      end
+    end
+  end
+end