rails-doctor 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 33475f8da3160d83e02d37cb0854981fee269452d9d6ec18ee40d928e8355c82
+  data.tar.gz: e21a6029b7fb00a519455fbca1a94f6f529e3dafc551c309629f6e017e752f3f
+SHA512:
+  metadata.gz: d6b1afe0d88e480f68941c9e375324c67003775c2f3836bb4864f91270a8413074aea3e0f793f66ce758d0ddbb543d12392d3e10bf8f7b6de7bcf04f7a460e38
+  data.tar.gz: b6de0130d08f3467d220895d1d7f0d1a136e06a649c543fd396bffbee93d4313341813934e60a5c9b7f7cc25ca72f6e2d46c73d1744a5250e2b9337f0c936d5a

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0
+
+- Initial Rails Doctor CLI and gem scaffold.
+- Added normalized findings, scores, hotspots, skipped-tool coverage, and profile support.
+- Added adapters for RuboCop, Brakeman, Bundler Audit, Zeitwerk, Reek, Strong Migrations, Flog, Flay, dependency freshness, and test runtime signals.
+- Added Rails-specific checks for index coverage, uniqueness backing, routes/views, artifact size, TODO density, and test counterparts.
+- Added terminal, JSON, Markdown, and static HTML reports.
+- Added conservative init workflow, GitHub Actions template, and explicit agent handoff.
+- Added repository CI, Pages deployment, Dependabot, security policy, release docs, and copy-paste GitHub Actions examples.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rails Doctor Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,148 @@
+# Rails Doctor
+
+[![CI](https://github.com/joshsaintjacque/rails-doctor/actions/workflows/ci.yml/badge.svg)](https://github.com/joshsaintjacque/rails-doctor/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/rails-doctor.svg)](https://rubygems.org/gems/rails-doctor)
+[![License: MIT](https://img.shields.io/badge/License-MIT-teal.svg)](LICENSE)
+
+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](site/assets/report-preview.png)
+
+![Rails Doctor CLI output](site/assets/cli-output.png)
+
+## Quickstart
+
+```sh
+gem install rails-doctor
+rails-doctor
+```
+
+For a project setup pass:
+
+```sh
+rails-doctor init --dry-run --ci
+rails-doctor init --yes --ci
+```
+
+Generate reports:
+
+```sh
+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:
+
+```sh
+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:
+
+```sh
+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
+
+- [CLI reference](docs/cli-reference.md)
+- [Configuration reference](docs/config-reference.md)
+- [Output schema](docs/output-schema.md)
+- [Scoring model](docs/scoring-model.md)
+- [Adapter architecture](docs/adapter-architecture.md)
+- [Architecture diagram](docs/architecture.md)
+- [GitHub Actions](docs/github-actions.md)
+- [Agent handoff](docs/agent-handoff.md)
+- [Monetization path](docs/monetization.md)
+- [Contributing](CONTRIBUTING.md)
+- [Security policy](SECURITY.md)
+- [Release process](RELEASE.md)
+
+## Static Site
+
+The public marketing site lives in [site/index.html](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.

data/docs/adapter-architecture.md

@@ -0,0 +1,21 @@
+# Adapter Architecture
+
+Adapters provide one contract:
+
+1. detect availability
+2. run a command or coverage check
+3. parse output into normalized findings
+4. return a `ToolRun` record
+
+Rails Doctor delegates to mature tools instead of duplicating their domains:
+
+- security: Brakeman
+- lint/correctness: RuboCop and RuboCop Rails
+- vulnerable dependencies: Bundler Audit
+- code smells: Reek
+- complexity: Flog
+- duplication: Flay
+- migration safety: Strong Migrations
+- test coverage: SimpleCov result set reader
+
+Rails Doctor-owned checks fill Rails-specific gaps and synthesize cross-tool signals for reports and agents.

data/docs/agent-handoff.md

@@ -0,0 +1,22 @@
+# Agent Handoff
+
+Rails Doctor is agent-ready by design, but normal scans are read-only.
+
+```sh
+rails-doctor agent codex --severity high
+rails-doctor agent codex --severity high --apply
+```
+
+Without `--apply`, Rails Doctor writes a Markdown repair brief under `.rails-doctor/agent-briefs`.
+
+Agent briefs include the current coverage summary and low-coverage files when `ci` or `deep` profiles capture SimpleCov metrics. Agents should use that section to add or update behavior tests before expanding low-coverage implementation code.
+
+With `--apply`, Rails Doctor:
+
+1. filters findings
+2. writes the exact repair brief
+3. checks dirty-worktree policy
+4. invokes the configured agent command
+5. writes an audit JSON file under `.rails-doctor/agent-runs`
+
+Rails Doctor never commits automatically in v1.

data/docs/architecture.md

@@ -0,0 +1,21 @@
+# Architecture
+
+```mermaid
+flowchart LR
+  A[Rails app] --> B[Tool adapters]
+  A --> C[Rails Doctor checks]
+  B --> D[Normalized findings]
+  C --> D
+  B --> M[Coverage metrics]
+  M --> D
+  D --> E[Scoring]
+  D --> F[Hotspots]
+  D --> G[Terminal report]
+  D --> H[JSON schema]
+  D --> I[Markdown summary]
+  D --> J[HTML dashboard]
+  D --> K[Agent briefs]
+  K --> L[Codex / Claude Code / Cursor]
+```
+
+Adapters run mature tools, normalize their output, and read SimpleCov coverage metrics. Rails Doctor-owned checks fill gaps, then every output format renders from the same report model.

data/docs/cli-reference.md

@@ -0,0 +1,48 @@
+# CLI Reference
+
+## `rails-doctor [scan]`
+
+Runs a scan from the current Rails project root.
+
+Options:
+
+- `--profile fast|recommended|ci|deep`
+- `--format terminal|json|markdown|html`
+- `--output PATH`
+- `--config PATH`
+- `--changed-only`
+- `--base REF`
+- `--include-raw`
+- `--fail-on info|low|medium|high|critical`
+- `--min-score N`
+
+`ci` and `deep` profiles read SimpleCov coverage metrics after the configured test command. Low coverage is reported as `medium` `test-coverage` findings, so existing severity and score gates can enforce it.
+
+## `rails-doctor init`
+
+Detects the Rails app, writes `.rails-doctor.yml`, optionally writes GitHub Actions workflow files, and offers to install missing development/test tooling.
+
+Options:
+
+- `--profile NAME`
+- `--dry-run`
+- `--yes`
+- `--install`
+- `--ci`
+- `--test-command COMMAND`
+
+## `rails-doctor agent AGENT`
+
+Generates a repair brief for an AI coding agent. Supported adapter names are configurable; defaults are `codex`, `claude-code`, and `cursor`.
+
+Options:
+
+- `--profile NAME`
+- `--severity SEVERITY`
+- `--max-findings N`
+- `--changed-only`
+- `--base REF`
+- `--apply`
+- `--allow-dirty`
+
+Without `--apply`, no external agent process is invoked.

data/docs/config-reference.md

@@ -0,0 +1,50 @@
+# Configuration Reference
+
+Rails Doctor reads `.rails-doctor.yml` from the project root.
+
+```yaml
+profiles:
+  recommended:
+    adapters:
+      - rubocop
+      - brakeman
+      - bundler_audit
+      - zeitwerk
+      - reek
+      - strong_migrations
+      - rails_checks
+commands:
+  test: bin/rails test
+reports:
+  output_dir: tmp/rails-doctor
+coverage:
+  enabled: true
+  source: simplecov
+  result_path: coverage/.resultset.json
+  include:
+    - app/**/*.rb
+    - lib/**/*.rb
+  max_files: 10
+thresholds:
+  fail_on:
+  min_score:
+  coverage:
+    line: 90.0
+    file_line: 80.0
+    branch:
+git:
+  churn_window_days: 90
+  base_ref:
+agents:
+  codex:
+    command: codex exec
+    apply_requires_clean_worktree: true
+```
+
+Profiles let teams choose fast local scans, CI coverage, or deeper quality analysis. Commands are strings because projects often run tools through Bundler, binstubs, Docker, or custom scripts.
+
+Coverage metrics are read from SimpleCov's `.resultset.json` after the configured test command runs. Rails Doctor reports missing coverage as an informational coverage gap and reports low aggregate line coverage, low per-file line coverage, and any configured low branch coverage as normal `test-coverage` findings. `coverage.max_files` limits displayed low-file detail, not threshold evaluation.
+
+Dependency freshness checks should only run in profiles where the team accepts network or cache use.
+
+Set `git.base_ref` or pass `--base origin/main` in CI to compute changed-file scores against a pull request base instead of only considering uncommitted local changes.

data/docs/github-actions.md

@@ -0,0 +1,36 @@
+# GitHub Actions
+
+Rails Doctor supports two GitHub Actions surfaces:
+
+1. the Rails Doctor repository CI, which tests and packages the gem
+2. the generated Rails app workflow, which runs `rails-doctor` against application pull requests
+
+## Generated Rails App Workflow
+
+Run:
+
+```sh
+rails-doctor init --ci
+```
+
+The generated workflow:
+
+- runs on pull requests and manual dispatch
+- installs Ruby with Bundler caching
+- generates Markdown, JSON, and HTML reports
+- appends Markdown to the GitHub Actions job summary
+- uploads report artifacts
+- supports optional PR comments through `RAILS_DOCTOR_PR_COMMENT`
+- passes `--base origin/${{ github.base_ref || 'main' }}` for changed-file scoring
+- reads SimpleCov coverage metrics from `coverage/.resultset.json` when the configured test command generates it
+
+See [examples/github-actions/rails-doctor.yml](../examples/github-actions/rails-doctor.yml).
+
+## Threshold Gates
+
+```sh
+bundle exec rails-doctor --profile ci --fail-on critical
+bundle exec rails-doctor --profile ci --min-score 80
+```
+
+Prefer `--fail-on critical` at first. Score gates are useful once a team has agreed on a baseline and understands how skipped tools affect confidence. Teams that want strict AI-generated-code guardrails can use `--fail-on medium` after SimpleCov is configured, because coverage regressions are emitted as medium-severity findings.

data/docs/monetization.md

@@ -0,0 +1,14 @@
+# Monetization Path
+
+Rails Doctor's CLI is fully useful as free MIT-licensed software. The commercial path should stay above the local scanner rather than limiting OSS functionality.
+
+Good future paid layers:
+
+- hosted report history across repositories
+- team policy management and approved scanner profiles
+- GitHub App checks with hosted artifacts and comments
+- org-wide trends for new vs inherited technical debt
+- agent remediation queue with status tracking
+- private benchmarks across repositories in an organization
+
+V1 prepares for this by keeping JSON output stable, including repo/report metadata, preserving report artifacts, and avoiding any required login or hosted backend.

data/docs/output-schema.md

@@ -0,0 +1,57 @@
+# Output Schema
+
+`rails-doctor --format json` emits schema version `1.1`.
+
+Top-level fields:
+
+- `schema_version`
+- `generated_at`
+- `project_root`
+- `profile`
+- `metadata`
+- `summary`
+- `coverage`
+- `findings`
+- `hotspots`
+- `tool_runs`
+
+`coverage` is `null` for profiles that do not run the `test_coverage` adapter. When present, it contains:
+
+- `available`
+- `status`
+- `source`
+- `report_path`
+- `line_percent`
+- `branch_percent`
+- `covered_lines`
+- `missed_lines`
+- `total_lines`
+- `covered_branches`
+- `missed_branches`
+- `total_branches`
+- `thresholds`
+- `top_files`
+- `low_file_count`
+- `changed_files_below_threshold`
+- `metadata`
+
+`status` is one of `ok`, `below_threshold`, `missing`, `invalid`, `empty`, or `disabled`. Missing or empty coverage emits an informational `coverage-gap` finding. Invalid coverage emits a `tool-execution` finding. Aggregate line, per-file line, and configured branch thresholds emit normal `test-coverage` findings.
+
+Each finding contains:
+
+- `id`
+- `severity`
+- `category`
+- `tool`
+- `file`
+- `line`
+- `confidence`
+- `message`
+- `recommendation`
+- `agent_instruction`
+- `suggested_commands`
+- `metadata`
+
+Agents should treat `agent_instruction` and `suggested_commands` as guidance, not permission to mutate code. Mutation only occurs through an explicit agent workflow outside JSON report generation.
+
+`metadata` includes detected Ruby and Rails versions, current branch, optional base ref, and changed files used for changed-file scoring.

data/docs/scoring-model.md

@@ -0,0 +1,23 @@
+# Scoring Model
+
+Rails Doctor scores are communication aids. Findings are the source of truth.
+
+Severity penalties:
+
+- `critical`: 15
+- `high`: 7
+- `medium`: 3
+- `low`: 1
+- `info`: 0
+
+Confidence changes penalty weight:
+
+- `high`: 100%
+- `medium`: 75%
+- `low`: 40%
+
+Skipped tools reduce report confidence rather than directly penalizing the health score. Reports show `overall_score` and `changed_files_score` so teams can separate inherited debt from new PR risk.
+
+Coverage below the configured aggregate or per-file thresholds is represented as `medium` `test-coverage` findings. Those findings affect the health score like any other medium-severity issue, which lets existing gates such as `--fail-on medium` enforce coverage expectations.
+
+Hotspots combine severity-weighted findings, Git churn, and changed-file status. In CI, pass `--base origin/main` or configure `git.base_ref` so changed-file score and hotspots are computed against the pull request base.

data/examples/github-actions/rails-doctor.yml

@@ -0,0 +1,40 @@
+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