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

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

Optionally publish the config:

Usage

Full scan

Export to Markdown

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

Export to JSON

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

Export both at once

CI-friendly summary

Scan a specific path

Run specific detectors only

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

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

CI Debt Gate

Block a pull request when technical debt crosses a line you set. Both debt:scan and debt:summary accept two opt-in flags:

If both are set, the gate fails when either threshold is breached.

Exit codes: 0 = passed (or gate not configured), 1 = a threshold was breached, 2 = invalid flag value (bad grade letter or non-numeric score).

Set the policy once in config

Instead of repeating flags in every workflow, set defaults in config/debt-tracker.php — a CLI flag always overrides the config value:

GitHub Actions

Note on debt:summary: without any gate flag or ci config, debt:summary keeps its historical exit codes (0 for A/B, 1 for C, 2 for D/F). Passing a gate flag (or setting the ci config) switches it to the gate's 0/1 scheme.

Configuration

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):

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

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

3. Populate the cards — run a 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:

Disabling Pulse push

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

How Scoring Works

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

Reports

Markdown

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

JSON

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

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

License

MIT · © Techrays Labs

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