joshcirre/laravel-doctor

Artisan-first Laravel codebase health scanner with diagnostics and scoring

Maintainers

Details

github.com/joshcirre/laravel-doctor

Source

Issues

Installs: 22

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 0

Forks: 0

Open Issues: 0

pkg:composer/joshcirre/laravel-doctor

v0.0.4 2026-02-18 21:23 UTC

Requires

Requires (Dev)

MIT 97b0d677592ce4a3c05b50da6df9ee02ca4c0848

This package is auto-updated.

Last update: 2026-02-18 21:24:09 UTC

README

Artisan-first Laravel codebase health scanner inspired by React Doctor.

laravel-doctor reports actionable diagnostics across security, correctness, performance, architecture, and maintainability, then computes a local deterministic 0-100 score.

Install

composer require --dev joshcirre/laravel-doctor

Publish config:

php artisan vendor:publish --tag=laravel-doctor-config

Usage

Run a full scan:

php artisan doctor

Common options:

php artisan doctor -v
php artisan doctor --score
php artisan doctor --format=json
php artisan doctor --diff
php artisan doctor --diff=main
php artisan doctor --min-score=75

Trace scanned files:

php artisan doctor -v      # first 60 scanned files
php artisan doctor -vv     # all scanned files

Progress and banner output use Laravel's console UI components by default. Disable progress indicators with:

php artisan doctor --no-progress

Auto-Fix

Apply safe built-in automated fixes:

php artisan doctor:fix

Preview changes only:

php artisan doctor:fix --dry-run

Apply only for changed files:

php artisan doctor:fix --diff

Run an optional Rector pass after built-in fixers (when vendor/bin/rector exists):

php artisan doctor:fix --with-rector

When diagnostics cannot be fixed programmatically, Laravel Doctor generates .laravel-doctor/manual-fix-plan.md with:

  • A ready-to-paste prompt for your coding agent
  • A rule-by-rule checklist with file and line references

Current Rule Set (MVP)

  • laravel/no-debug-statements
  • laravel/no-env-outside-config
  • laravel/no-mass-assignment-bypass
  • laravel/controller-missing-validation
  • laravel/no-broad-catch
  • laravel/likely-n-plus-one
  • laravel/fat-controller
  • laravel/deep-nesting

Scoring

  • Starts at 100
  • Applies weighted penalties by severity and category
  • Caps per-rule penalty to avoid one repeated issue collapsing score
  • Labels:
    • 80+: Great
    • 55-79: Needs work
    • 0-54: Critical

CI Example

php artisan doctor --format=json --min-score=75

The command exits non-zero when score is below --min-score.

Skill

This repository includes an Agent Skill at skills/laravel-doctor/SKILL.md for AI agents to run Laravel Doctor and remediate findings in priority order.