README

Laravel Debt Tracker

Scan, score, and report technical debt in your Laravel application — right from the CLI.

"We should fix this eventually" — every engineering team, forever.

Laravel Debt Tracker makes the invisible visible. It scans your codebase for technical debt across nine detectors, assigns a score, estimates developer hours to resolve, and produces a Markdown or JSON report you can actually show your product manager.

Features

• TODO / FIXME detection — finds every deferred problem in your comments
• Complexity analysis — cyclomatic complexity, long methods, God classes, deep nesting
• N+1 query detection — flags Eloquent lazy-load patterns inside loops and collection iterators
• Security smell detection — flags eval/exec, hardcoded credentials, md5/sha1 on passwords, SQL concatenation, unsafe unserialize, and debug leakage
• Dead code detection — flags unused private methods, properties, and constants within classes
• Test coverage heuristics — no Xdebug required; detects untested classes and methods
• Dependency audit — flags outdated or abandoned Composer packages
• Git blame enrichment — older debt scores higher; age is the multiplier
• Git author leaderboard — surfaces who owns the most debt across terminal, Markdown, and JSON reports
• Laravel Pulse cards — grade summary, score trend, hottest files, and author leaderboard visible in your Pulse dashboard with zero extra packages
• Debt grading — A through F, with estimated dev hours to resolve
• Markdown & JSON export — shareable reports with a shield badge for your README

Requirements

Support policy: Only the current release (v1.3.x) receives bug fixes, security patches, and updates. All versions below v1.3 have reached end of life. If you are on v1.0, v1.1, or v1.2 please upgrade — see CHANGELOG.md for what changed.

Installation

composer require --dev techrays-labs/laravel-debt-tracker

That's it. The package auto-discovers itself.

Optionally publish the config:

php artisan vendor:publish --tag=debt-tracker-config

Usage

Full scan

php artisan debt:scan

┌ Laravel Debt Tracker · by Techrays Labs ──────────────────┐

  Scanning files  ████████████████░░░░  249/312
  app/Services/LegacyPaymentService.php

  Project Grade: C    Total Score: 412    Est. Hours: 103h

  Debt by Category:
  ┌─────────────────────────┬───────┬──────────┐
  │ Category                │ Items │ Score    │
  ├─────────────────────────┼───────┼──────────┤
  │ TODOs / FIXMEs          │  ---  │  112     │
  │ Complexity              │  ---  │  180     │
  │ Missing Test Coverage   │  ---  │   88     │
  │ Outdated Dependencies   │  ---  │   32     │
  │ N+1 Queries             │  ---  │   24     │
  │ Security Smells         │  ---  │   18     │
  │ Dead Code               │  ---  │    6     │
  └─────────────────────────┴───────┴──────────┘

  Top 10 Worst Files:
  ┌────────────────────────────────────────┬───────┬───────┐
  │ File                                   │ Items │ Score │
  ├────────────────────────────────────────┼───────┼───────┤
  │ app/Services/LegacyPaymentService.php  │  14   │  98   │
  │ app/Http/Controllers/OrderController   │   9   │  72   │
  │ ...                                    │       │       │
  └────────────────────────────────────────┴───────┴───────┘

└ Scan complete · Grade: C · Score: 412 · 47 items found ───┘

Export to Markdown

php artisan debt:scan --export=markdown

Writes DEBT_REPORT.md to your project root — ready to commit or share.

Export to JSON

php artisan debt:scan --export=json

Writes DEBT_REPORT.json — machine-readable output for dashboards, scripts, or CI integrations.

Export both at once

php artisan debt:scan --export=markdown,json

CI-friendly summary

php artisan debt:summary
# [Techrays Debt Tracker] Grade: C | Score: 412 | Est: 103h | Files: 312
# Exit code: 1 (C), 0 (A/B), 2 (D/F) — gate your pipeline on debt grade

Scan a specific path

php artisan debt:scan --path=app/Services

Run specific detectors only

Every detector has a key you can pass to --only. Combine as many as you need with commas.

# TODOs, FIXMEs, HACKs, XXXs, TEMPs and REFACTORs in comments
php artisan debt:scan --only=todos

# Cyclomatic complexity, long methods, God classes, deep nesting
php artisan debt:scan --only=complexity

# Missing test files and untested public methods
php artisan debt:scan --only=coverage

# Outdated or abandoned Composer packages
php artisan debt:scan --only=dependencies

# Eloquent lazy-load (N+1) patterns inside loops and collection iterators
php artisan debt:scan --only=n1_queries

# Security smells: eval/exec, hardcoded credentials, weak hashing,
# SQL concatenation, unsafe unserialize, debug leakage (dd/dump)
php artisan debt:scan --only=security

# Dead code: unused private methods, properties and constants
php artisan debt:scan --only=dead_code

# Combine any detectors in a single run
php artisan debt:scan --only=security,dead_code
php artisan debt:scan --only=todos,complexity,n1_queries
php artisan debt:scan --only=todos,complexity,coverage,dependencies,n1_queries,security,dead_code

Note: --only works at the detector level. For example, --only=dead_code reports unused private methods, properties, and constants together — there is no sub-filter within a detector.

Inspect a single file or class

php artisan debt:show-file app/Services/PaymentService.php
php artisan debt:show-class "App\Services\PaymentService"

Configuration

// config/debt-tracker.php

return [
    'scan_paths' => ['app'],
    'exclude_paths' => ['app/Http/Middleware'],

    'thresholds' => [
        'method_length'        => 30,   // lines
        'class_length'         => 500,  // lines
        'max_public_methods'   => 20,
        'nesting_depth'        => 4,
        'complexity_per_method'=> 10,
    ],

    'cost' => [
        'hours_per_point' => 0.25,
        'hourly_rate'     => null, // set to show $ estimates
    ],

    'detectors' => [
        'todos'        => true,
        'complexity'   => true,
        'coverage'     => true,
        'dependencies' => true,
        'git_age'      => true,
        'n1_queries'   => true,
        'security'     => true,
        'dead_code'    => true,
    ],

    'n1_ignore_properties'     => ['id', 'uuid', 'created_at', 'updated_at', 'deleted_at'],
    'security_exclude_paths'   => ['tests', 'database/seeders'],
    'dead_code_ignore_methods' => [],

    'export' => [
        'path'      => base_path('DEBT_REPORT.md'),
        'json_path' => base_path('DEBT_REPORT.json'),
    ],
];

Laravel Pulse Integration

Laravel Debt Tracker ships with four built-in Pulse dashboard cards. No extra package needed — the cards activate automatically when laravel/pulse and livewire/livewire are present in your app.

Requirements

• laravel/pulse ^1.0 — tested with v1.0 through v1.7
• livewire/livewire ^3.0 — pulled in automatically as a dependency of Pulse
• MySQL 8 or MariaDB — MySQL 9 is not currently supported due to a bug in Pulse's DatabaseStorage where key_hash is omitted from INSERTs on MySQL 9, causing a strict-mode constraint failure. Track progress at laravel/pulse#476 (or check the Pulse changelog for a fix).

Neither package is a hard dependency of laravel-debt-tracker. Install them in your app and the integration activates on its own.

Setup

1. Publish the card views (optional — only needed to customise them):

php artisan vendor:publish --tag=debt-tracker-pulse-views

2. Add the cards to your Pulse dashboard in resources/views/vendor/pulse/dashboard.blade.php:

<livewire:debt-tracker-summary-card cols="2" />
<livewire:debt-tracker-score-card cols="4" />
<livewire:debt-tracker-files-card cols="3" />
<livewire:debt-tracker-authors-card cols="3" />

The cols values above fill a standard 12-column Pulse grid row. Adjust to your layout.

3. Populate the cards — run a scan:

php artisan debt:scan

Cards update automatically every time debt:scan runs.

Scheduled scans

To keep your dashboard up to date automatically, schedule debt:scan in routes/console.php:

use Illuminate\Support\Facades\Schedule;

Schedule::command('debt:scan')->daily();

Disabling Pulse push

To run ad-hoc scans without updating the dashboard, set in config/debt-tracker.php:

'pulse' => [
    'enabled' => false,
],

How Scoring Works

Each detected debt item gets a base score multiplied by an age multiplier:

Item Score = Base Weight × Age Multiplier

Reports

Markdown

The exported DEBT_REPORT.md includes a shields.io badge you can embed in your README:

![Debt Grade](https://img.shields.io/badge/Debt%20Grade-C-yellow)

JSON

DEBT_REPORT.json uses a stable schema suitable for CI dashboards or custom tooling:

{
  "generated_at": "2026-06-09T19:49:00+00:00",
  "grade": "B",
  "total_score": 141,
  "estimated_hours": 35.3,
  "file_count": 18,
  "item_count": 21,
  "by_category": [...],
  "authors": [{"author": "Jane Doe", "debt_score": 87}, ...],
  "top_files": [...],
  "top_classes": [...],
  "items": [...],
  "meta": { "package": "techrays-labs/laravel-debt-tracker", "url": "..." }
}

Contributing

Contributions are welcome!

• Read CONTRIBUTING.md for setup instructions, coding standards, and how to add a new detector
• Read CODE_OF_CONDUCT.md before participating in discussions or submitting contributions
• Report security vulnerabilities privately via SECURITY.md — do not open a public issue
• Use the Bug Report or Feature Request issue templates

git clone https://github.com/techrays-labs/laravel-debt-tracker
cd laravel-debt-tracker
composer install
php vendor/bin/testbench package:test

License

MIT · © Techrays Labs

Built with ❤️ by Techrays Labs · Ahmedabad, India
_{We build software and the teams that build software.}