rails-doctor 0.1.0

data/lib/rails_doctor/cli.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "optparse"
+
+require_relative "version"
+module RailsDoctor
+  Error = Class.new(StandardError) unless const_defined?(:Error)
+end
+
+require_relative "models"
+require_relative "config"
+require_relative "scanner"
+require_relative "project"
+require_relative "command_runner"
+require_relative "reporters/terminal"
+require_relative "reporters/json"
+require_relative "reporters/markdown"
+require_relative "reporters/html"
+require_relative "init/runner"
+require_relative "agent/handoff"
+
+module RailsDoctor
+  class CLI
+    FORMATS = %w[terminal json markdown html].freeze
+
+    def initialize(argv, stdout: $stdout, stderr: $stderr, env: ENV)
+      @argv = argv.dup
+      @stdout = stdout
+      @stderr = stderr
+      @env = env
+    end
+
+    def run
+      command = @argv.first&.start_with?("-") ? "scan" : (@argv.shift || "scan")
+      case command
+      when "scan" then run_scan
+      when "init" then run_init
+      when "agent" then run_agent
+      when "validate-config" then run_validate_config
+      when "version", "--version", "-v" then @stdout.puts VERSION; 0
+      when "help", "--help", "-h" then @stdout.puts(help); 0
+      else
+        @stderr.puts "Unknown command #{command.inspect}"
+        @stderr.puts help
+        1
+      end
+    rescue Error => error
+      @stderr.puts "rails-doctor: #{error.message}"
+      1
+    end
+
+    private
+
+    def run_scan
+      options = scan_options
+      config = Config.load(project_root: Dir.pwd, path: options[:config])
+      result = Scanner.new(project_root: Dir.pwd, config: config, env: @env).run(
+        profile: options[:profile],
+        changed_only: options[:changed_only],
+        base_ref: options[:base_ref]
+      )
+      output = render(result, options[:format], include_raw: options[:include_raw])
+      write_or_print(output, options[:output], format: options[:format])
+      threshold_exit(result, options)
+    end
+
+    def run_init
+      options = init_options
+      config = Config.load(project_root: Dir.pwd)
+      runner = CommandRunner.new(project_root: Dir.pwd, env: @env)
+      project = Project.new(root: Dir.pwd, runner: runner)
+      output = Init::Runner.new(project: project, config: config, runner: runner, options: options).run
+      @stdout.write(output)
+      0
+    end
+
+    def run_agent
+      agent_name = @argv.shift || raise(Error, "agent name required")
+      options = agent_options
+      config = Config.load(project_root: Dir.pwd, path: options[:config])
+      runner = CommandRunner.new(project_root: Dir.pwd, env: @env)
+      project = Project.new(root: Dir.pwd, runner: runner)
+      result = Scanner.new(project_root: Dir.pwd, config: config, env: @env).run(
+        profile: options[:profile],
+        changed_only: options[:changed_only],
+        base_ref: options[:base_ref]
+      )
+      options[:changed_files] = result.metadata[:changed_files]
+      output = Agent::Handoff.new(
+        agent_name: agent_name,
+        project: project,
+        config: config,
+        runner: runner,
+        options: options
+      ).run(result)
+      @stdout.write(output)
+      0
+    end
+
+    def run_validate_config
+      options = {}
+      OptionParser.new do |parser|
+        parser.on("--config PATH") { |value| options[:config] = value }
+      end.parse!(@argv)
+      Config.load(project_root: Dir.pwd, path: options[:config])
+      @stdout.puts "Rails Doctor config is valid."
+      0
+    end
+
+    def scan_options
+      options = {
+        profile: "recommended",
+        format: "terminal",
+        changed_only: false,
+        include_raw: false
+      }
+      OptionParser.new do |parser|
+        parser.banner = "Usage: rails-doctor [scan] [options]"
+        parser.on("--profile NAME") { |value| options[:profile] = value }
+        parser.on("--format FORMAT") { |value| options[:format] = validate_format(value) }
+        parser.on("--output PATH") { |value| options[:output] = value }
+        parser.on("--config PATH") { |value| options[:config] = value }
+        parser.on("--changed-only") { options[:changed_only] = true }
+        parser.on("--base REF") { |value| options[:base_ref] = value }
+        parser.on("--include-raw") { options[:include_raw] = true }
+        parser.on("--fail-on SEVERITY") { |value| options[:fail_on] = value }
+        parser.on("--min-score SCORE", Integer) { |value| options[:min_score] = value }
+      end.parse!(@argv)
+      options
+    end
+
+    def init_options
+      options = {
+        profile: "recommended",
+        dry_run: false,
+        yes: false,
+        install: false,
+        ci: false
+      }
+      OptionParser.new do |parser|
+        parser.banner = "Usage: rails-doctor init [options]"
+        parser.on("--profile NAME") { |value| options[:profile] = value }
+        parser.on("--dry-run") { options[:dry_run] = true }
+        parser.on("--yes") { options[:yes] = true }
+        parser.on("--install") { options[:install] = true }
+        parser.on("--ci") { options[:ci] = true }
+        parser.on("--test-command COMMAND") { |value| options[:test_command] = value }
+      end.parse!(@argv)
+      options
+    end
+
+    def agent_options
+      options = {
+        profile: "recommended",
+        apply: false,
+        allow_dirty: false,
+        max_findings: 10,
+        changed_only: false
+      }
+      OptionParser.new do |parser|
+        parser.banner = "Usage: rails-doctor agent AGENT [options]"
+        parser.on("--profile NAME") { |value| options[:profile] = value }
+        parser.on("--config PATH") { |value| options[:config] = value }
+        parser.on("--severity SEVERITY") { |value| options[:severity] = value }
+        parser.on("--max-findings N", Integer) { |value| options[:max_findings] = value }
+        parser.on("--changed-only") { options[:changed_only] = true }
+        parser.on("--base REF") { |value| options[:base_ref] = value }
+        parser.on("--apply") { options[:apply] = true }
+        parser.on("--allow-dirty") { options[:allow_dirty] = true }
+      end.parse!(@argv)
+      options
+    end
+
+    def render(result, format, include_raw: false)
+      case format
+      when "terminal" then Reporters::Terminal.new(result).render
+      when "json" then Reporters::Json.new(result, include_raw: include_raw).render
+      when "markdown" then Reporters::Markdown.new(result).render
+      when "html" then Reporters::Html.new(result).render
+      else raise Error, "Unknown format #{format.inspect}"
+      end
+    end
+
+    def write_or_print(output, path, format:)
+      if path
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, output)
+        @stdout.puts "Wrote #{format} report to #{path}"
+      else
+        @stdout.write(output)
+      end
+    end
+
+    def threshold_exit(result, options)
+      if options[:fail_on]
+        threshold = SEVERITY_WEIGHTS.fetch(options[:fail_on]) { raise Error, "Unknown severity #{options[:fail_on]}" }
+        return 2 if result.findings.any? { |finding| SEVERITY_WEIGHTS.fetch(finding.severity, 0) >= threshold }
+      end
+
+      if options[:min_score] && result.score&.overall.to_i < options[:min_score]
+        return 2
+      end
+
+      0
+    end
+
+    def validate_format(value)
+      raise Error, "Unknown format #{value.inspect}. Use #{FORMATS.join(", ")}." unless FORMATS.include?(value)
+
+      value
+    end
+
+    def help
+      <<~HELP
+        Rails Doctor #{VERSION}
+
+        Usage:
+          rails-doctor [scan] [--profile recommended] [--format terminal|json|markdown|html] [--base origin/main]
+          rails-doctor init [--dry-run] [--yes] [--install] [--ci]
+          rails-doctor agent codex [--severity high] [--apply]
+          rails-doctor validate-config
+
+        Scan profiles:
+          fast         static/local only, no tests, no network
+          recommended core static checks and configured local coverage
+          ci           static checks, tests, runtime warnings, artifacts
+          deep         ci plus deep quality and dependency freshness
+      HELP
+    end
+  end
+end

data/lib/rails_doctor/command_runner.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "open3"
+require "shellwords"
+require "timeout"
+
+module RailsDoctor
+  CommandResult = Struct.new(:command, :stdout, :stderr, :exit_status, :duration_ms, keyword_init: true)
+
+  class CommandRunner
+    attr_reader :project_root, :env
+
+    def initialize(project_root:, env: ENV)
+      @project_root = File.expand_path(project_root)
+      @env = env
+    end
+
+    def run(command, timeout_seconds: 120)
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      stdout = +""
+      stderr = +""
+      status_code = nil
+
+      begin
+        Timeout.timeout(timeout_seconds) do
+          stdout, stderr, status = Open3.capture3(env.to_h, command, chdir: project_root)
+          status_code = status.exitstatus
+        end
+      rescue Timeout::Error
+        stderr = "Command timed out after #{timeout_seconds}s"
+        status_code = 124
+      rescue Errno::ENOENT => error
+        stderr = error.message
+        status_code = 127
+      end
+
+      finished = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      CommandResult.new(
+        command: command,
+        stdout: stdout,
+        stderr: stderr,
+        exit_status: status_code,
+        duration_ms: ((finished - started) * 1000).round
+      )
+    end
+
+    def executable?(name)
+      path = env.fetch("PATH", "").split(File::PATH_SEPARATOR)
+      path.any? do |dir|
+        candidate = File.join(dir, name)
+        File.file?(candidate) && File.executable?(candidate)
+      end
+    end
+  end
+end

data/lib/rails_doctor/config.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module RailsDoctor
+  class Config
+    DEFAULT_FILE = ".rails-doctor.yml"
+
+    DEFAULTS = {
+      "version" => 1,
+      "profiles" => {
+        "fast" => {
+          "adapters" => %w[rubocop brakeman zeitwerk rails_checks],
+          "run_tests" => false,
+          "network" => false,
+          "deep_quality" => false
+        },
+        "recommended" => {
+          "adapters" => %w[rubocop brakeman bundler_audit zeitwerk reek strong_migrations rails_checks],
+          "run_tests" => false,
+          "network" => false,
+          "deep_quality" => false
+        },
+        "ci" => {
+          "adapters" => %w[rubocop brakeman bundler_audit zeitwerk reek strong_migrations rails_checks test_runner test_coverage],
+          "run_tests" => true,
+          "network" => false,
+          "deep_quality" => false
+        },
+        "deep" => {
+          "adapters" => %w[rubocop brakeman bundler_audit zeitwerk reek strong_migrations rails_checks test_runner test_coverage flog flay dependency_freshness],
+          "run_tests" => true,
+          "network" => true,
+          "deep_quality" => true
+        }
+      },
+      "commands" => {
+        "rubocop" => "bundle exec rubocop --format json",
+        "brakeman" => "bundle exec brakeman --format json --quiet",
+        "bundler_audit" => "bundle exec bundle-audit check --format json",
+        "zeitwerk" => "bundle exec rails zeitwerk:check",
+        "reek" => "bundle exec reek --format json",
+        "flog" => "bundle exec flog app lib",
+        "flay" => "bundle exec flay app lib",
+        "dependency_freshness" => "bundle outdated --parseable",
+        "test" => nil
+      },
+      "reports" => {
+        "default_format" => "terminal",
+        "output_dir" => "tmp/rails-doctor",
+        "include_raw_output" => true
+      },
+      "coverage" => {
+        "enabled" => true,
+        "source" => "simplecov",
+        "result_path" => "coverage/.resultset.json",
+        "include" => [
+          "app/**/*.rb",
+          "lib/**/*.rb"
+        ],
+        "max_files" => 10
+      },
+      "thresholds" => {
+        "fail_on" => nil,
+        "min_score" => nil,
+        "coverage" => {
+          "line" => 90.0,
+          "file_line" => 80.0,
+          "branch" => nil
+        },
+        "large_file_lines" => {
+          "model" => 250,
+          "controller" => 220,
+          "job" => 160,
+          "mailer" => 160,
+          "view" => 180
+        },
+        "todo_density_per_100_lines" => 2.0,
+        "flog_high_score" => 25.0
+      },
+      "git" => {
+        "churn_window_days" => 90,
+        "base_ref" => nil
+      },
+      "agents" => {
+        "codex" => {
+          "command" => "codex exec",
+          "apply_requires_clean_worktree" => true
+        },
+        "claude-code" => {
+          "command" => "claude",
+          "apply_requires_clean_worktree" => true
+        },
+        "cursor" => {
+          "command" => "cursor-agent",
+          "apply_requires_clean_worktree" => true
+        }
+      }
+    }.freeze
+
+    attr_reader :project_root, :path, :data
+
+    def initialize(project_root:, path: nil, data: nil)
+      @project_root = File.expand_path(project_root)
+      @path = path || File.join(@project_root, DEFAULT_FILE)
+      @data = deep_merge(DEFAULTS, data || load_file(@path))
+    end
+
+    def self.load(project_root:, path: nil)
+      new(project_root: project_root, path: path)
+    end
+
+    def profile(name)
+      data.fetch("profiles").fetch(name) do
+        raise Error, "Unknown profile #{name.inspect}. Available profiles: #{data.fetch("profiles").keys.join(", ")}"
+      end
+    end
+
+    def adapters_for(profile_name)
+      profile(profile_name).fetch("adapters")
+    end
+
+    def command(name)
+      data.fetch("commands", {})[name.to_s]
+    end
+
+    def threshold(key)
+      data.fetch("thresholds", {})[key.to_s]
+    end
+
+    def agent(name)
+      data.fetch("agents", {})[name.to_s]
+    end
+
+    def report_output_dir
+      File.join(project_root, data.fetch("reports").fetch("output_dir"))
+    end
+
+    def to_yaml
+      data.to_yaml
+    end
+
+    private
+
+    def load_file(file)
+      return {} unless file && File.exist?(file)
+
+      YAML.safe_load(File.read(file), aliases: true) || {}
+    end
+
+    def deep_merge(left, right)
+      left.merge(right) do |_key, old_value, new_value|
+        if old_value.is_a?(Hash) && new_value.is_a?(Hash)
+          deep_merge(old_value, new_value)
+        else
+          new_value
+        end
+      end
+    end
+  end
+end

data/lib/rails_doctor/init/runner.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "yaml"
+
+module RailsDoctor
+  module Init
+    class Runner
+      RECOMMENDED_GEMS = {
+        "rubocop" => "development,test",
+        "rubocop-rails" => "development,test",
+        "brakeman" => "development,test",
+        "bundler-audit" => "development,test",
+        "reek" => "development,test",
+        "strong_migrations" => "development,test",
+        "prosopite" => "development,test",
+        "simplecov" => "development,test",
+        "flog" => "development,test",
+        "flay" => "development,test"
+      }.freeze
+
+      attr_reader :project, :config, :runner, :options
+
+      def initialize(project:, config:, runner:, options:)
+        @project = project
+        @config = config
+        @runner = runner
+        @options = options
+      end
+
+      def run
+        changes = planned_changes
+        lines = []
+        lines << "Rails Doctor init"
+        lines << "Profile: #{options.fetch(:profile, "recommended")}"
+        lines << ""
+        lines << "Planned file changes"
+        changes.each do |change|
+          lines << "- #{change.fetch(:path)} (#{change.fetch(:action)})"
+        end
+        lines << ""
+
+        missing = missing_gems
+        if missing.any?
+          lines << "Missing recommended gems"
+          missing.each { |gem| lines << "- #{gem} (#{RECOMMENDED_GEMS.fetch(gem)})" }
+          lines << ""
+        end
+
+        if options[:dry_run]
+          lines << "Dry run only. No files were changed."
+          return lines.join("\n") + "\n"
+        end
+
+        if options[:yes] || confirm?("Apply Rails Doctor configuration? [y/N] ")
+          changes.each { |change| write_change(change) }
+          lines << "Wrote Rails Doctor configuration."
+        else
+          lines << "Skipped file changes."
+        end
+
+        if missing.any? && should_install_missing?
+          install_missing(missing, lines)
+        elsif missing.any?
+          lines << "Skipped gem installation. Run rails-doctor init --install to install missing tools."
+        end
+
+        lines.join("\n") + "\n"
+      end
+
+      private
+
+      def planned_changes
+        changes = [
+          {
+            path: Config::DEFAULT_FILE,
+            action: File.exist?(project.join(Config::DEFAULT_FILE)) ? "update" : "create",
+            content: generated_config
+          }
+        ]
+
+        if options[:ci]
+          changes << {
+            path: ".github/workflows/rails-doctor.yml",
+            action: File.exist?(project.join(".github/workflows/rails-doctor.yml")) ? "update" : "create",
+            content: github_workflow
+          }
+        end
+
+        changes
+      end
+
+      def generated_config
+        data = Config::DEFAULTS.dup
+        data = deep_dup(data)
+        data["commands"]["test"] = options[:test_command] || detect_test_command
+        data["reports"]["output_dir"] = "tmp/rails-doctor"
+        data.to_yaml
+      end
+
+      def github_workflow
+        <<~YAML
+          name: Rails Doctor
+
+          on:
+            pull_request:
+            workflow_dispatch:
+
+          permissions:
+            contents: read
+            pull-requests: write
+
+          jobs:
+            rails-doctor:
+              runs-on: ubuntu-latest
+              strategy:
+                fail-fast: false
+                matrix:
+                  ruby: ["3.2", "3.3", "3.4"]
+              steps:
+                - uses: actions/checkout@v4
+                  with:
+                    fetch-depth: 0
+                - uses: ruby/setup-ruby@v1
+                  with:
+                    ruby-version: ${{ matrix.ruby }}
+                    bundler-cache: true
+                - run: bundle exec rails-doctor --profile ci --base origin/${{ github.base_ref || 'main' }} --format markdown --output tmp/rails-doctor/summary.md
+                - run: bundle exec rails-doctor --profile ci --base origin/${{ github.base_ref || 'main' }} --format json --output tmp/rails-doctor/report.json
+                - run: bundle exec rails-doctor --profile ci --base origin/${{ github.base_ref || 'main' }} --format html --output tmp/rails-doctor/report.html
+                - name: Rails Doctor summary
+                  run: cat tmp/rails-doctor/summary.md >> "$GITHUB_STEP_SUMMARY"
+                - name: Optional PR comment
+                  if: github.event_name == 'pull_request' && vars.RAILS_DOCTOR_PR_COMMENT == 'true'
+                  run: gh pr comment "$PR_URL" --body-file tmp/rails-doctor/summary.md
+                  env:
+                    GH_TOKEN: ${{ github.token }}
+                    PR_URL: ${{ github.event.pull_request.html_url }}
+                - uses: actions/upload-artifact@v4
+                  with:
+                    name: rails-doctor-${{ matrix.ruby }}
+                    path: tmp/rails-doctor
+        YAML
+      end
+
+      def write_change(change)
+        path = project.join(change.fetch(:path))
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, change.fetch(:content))
+      end
+
+      def missing_gems
+        RECOMMENDED_GEMS.keys.reject { |gem| project.gem_declared?(gem) }
+      end
+
+      def should_install_missing?
+        return true if options[:install]
+        return false if options[:yes]
+
+        confirm?("Install missing recommended gems with bundle add? [y/N] ")
+      end
+
+      def install_missing(missing, lines)
+        missing.group_by { |gem| RECOMMENDED_GEMS.fetch(gem) }.each do |group, gems|
+          command = "bundle add #{gems.join(" ")} --group=#{group}"
+          result = runner.run(command, timeout_seconds: 300)
+          lines << "Ran #{command}: exit #{result.exit_status}"
+          lines << result.stderr.strip unless result.stderr.to_s.strip.empty?
+        end
+      end
+
+      def detect_test_command
+        return "bundle exec rspec" if File.exist?(project.join("spec"))
+        return "bin/rails test" if File.exist?(project.join("test")) || File.exist?(project.join("bin/rails"))
+
+        nil
+      end
+
+      def confirm?(prompt)
+        return false unless $stdin.tty?
+
+        print prompt
+        $stdin.gets.to_s.strip.downcase.start_with?("y")
+      end
+
+      def deep_dup(value)
+        Marshal.load(Marshal.dump(value))
+      end
+    end
+  end
+end