Rails Doctor

CI Gem Version License: MIT

Rails Doctor is a Rails health scanner for developers, CI, and AI coding agents.

It runs trusted Ruby/Rails tools, adds Rails-specific checks, and turns the results into one normalized report for humans and agents. The goal is simple: keep fast-moving AI-assisted Rails work from quietly accumulating technical debt.

Rails Doctor HTML report

Rails Doctor CLI output

Quickstart

gem install rails-doctor
rails-doctor

For a project setup pass:

rails-doctor init --dry-run --ci
rails-doctor init --yes --ci

Generate reports:

rails-doctor --format json --output tmp/rails-doctor/report.json
rails-doctor --format markdown --output tmp/rails-doctor/summary.md
rails-doctor --format html --output tmp/rails-doctor/report.html
rails-doctor --profile ci --base origin/main --changed-only

Hand high-severity findings to an agent explicitly:

rails-doctor agent codex --severity high
rails-doctor agent codex --severity high --apply

Normal scans never mutate your repo. Agent execution requires an explicit agent command and --apply.

What It Checks

Rails Doctor delegates to mature tools where they already do the job well:

  • RuboCop and RuboCop Rails for lint/style/correctness
  • Brakeman for Rails security
  • Bundler Audit for vulnerable dependencies
  • rails zeitwerk:check for autoloading
  • Reek for code smells
  • Flog for complexity
  • Flay for duplication
  • Strong Migrations for migration safety coverage
  • Bullet or Prosopite signals captured through the configured test command
  • SimpleCov result sets for line and branch coverage metrics

Rails Doctor-owned checks focus on Rails-specific gaps and synthesis:

  • missing indexes on foreign keys
  • uniqueness validations without unique DB indexes
  • route/controller/action/view consistency
  • conservative dead route/action/view hints
  • large Rails artifact hotspots
  • TODO/FIXME/HACK density
  • missing test/spec counterparts for changed app files
  • strict test coverage thresholds for aggregate and per-file coverage
  • churn + quality hotspot scoring
  • skipped-tool coverage gaps

Test Coverage Metrics

ci and deep profiles read coverage/.resultset.json after the configured test command runs. Rails Doctor expects SimpleCov to be configured by the app test suite; rails-doctor init recommends the simplecov gem but does not edit test boot files automatically.

Default thresholds are intentionally strict to make untested generated code visible:

  • aggregate line coverage: 90%
  • per-file line coverage: 80%
  • branch coverage: unset by default, enforced when configured

Coverage appears in every report format. Low coverage emits normal test-coverage findings, so score and --fail-on medium gates can catch coverage regressions without a separate coverage gate.

Output Formats

The default terminal report is concise and human-readable.

--format json is the stable public contract for agents. It includes summary data, coverage metrics, findings, tool runs, scores, skipped tools, hotspots, metadata, fix guidance, and direct agent_instruction fields.

--format markdown is optimized for pull request comments and GitHub Actions summaries.

--format html produces a static self-contained dashboard with score, confidence, coverage, top fixes, filters, hotspots, agent brief, skipped tools, and raw tool output.

Profiles

  • fast: static/local only, no tests, no network
  • recommended: core static checks and configured local coverage
  • ci: static checks, tests, runtime warnings, coverage metrics, and artifacts
  • deep: CI plus deep quality, dependency freshness, and hotspot detail

GitHub Actions

rails-doctor init --ci can generate a workflow that runs Rails Doctor on pull requests, writes a Markdown job summary, and uploads JSON/Markdown/HTML artifacts. Use --base origin/main or the generated workflow's base-ref expression to separate inherited debt from changed-file risk.

You can gate PRs:

rails-doctor --profile ci --fail-on critical
rails-doctor --profile ci --min-score 80

Supported Versions

Rails Doctor targets modern Rails apps:

  • Ruby >= 3.2
  • Rails >= 7.1
  • First-class Rails 8 support

The project test matrix covers Ruby 3.2, 3.3, and 3.4 against Rails 7.1, 7.2, and 8.x fixture scenarios where practical.

The repository CI includes tests, RuboCop linting, Bundler Audit dependency checks, a gem build dry-run, and GitHub Pages deployment for the public site.

Documentation

Static Site

The public marketing site lives in site/index.html. The repository includes a GitHub Pages workflow that deploys the static site from site/ on pushes to main.

Monetization Posture

Rails Doctor CLI is MIT-licensed and fully useful as open source. Future paid value belongs above the CLI: hosted report history, team policy management, GitHub App checks, org-wide trends, and agent remediation queues.