Download the PHP package ticoscope/laravel without Composer

TicoScope

Deterministic, diff-based pre-deployment risk analysis for Laravel.

git diff tells you which files changed. It doesn't tell you which of those changes are operationally significant: a migration that drops a column, a config key that will silently resolve to null in production, a queued job whose payload will break for jobs already sitting on the queue. TicoScope reads the git diff between two revisions and flags exactly that kind of risk — deterministically, with no AI guessing and no live database or queue connection required — so your CI pipeline can gate a deploy on it the same way it already gates on a failing test.

Requirements

• PHP 8.2, 8.3, or 8.4
• Laravel (illuminate/support/illuminate/console) 11, 12, or 13 — Laravel 13 itself requires PHP 8.3 or 8.4; PHP 8.2 remains valid only alongside Laravel 11 or 12

Installation

It's a development-time analysis tool, not a runtime dependency — install it as --dev.

Quick start

Exit code is non-zero as soon as any finding meets or exceeds the --fail-on threshold — drop it straight into an existing CI job.

How it works

TicoScope computes a merge-base-relative diff (git diff base...head, the same semantics git diff --raw and rename detection give you), runs a set of independent, deterministic rules against it, and reports every finding with a severity, the responsible rule, and a specific, human-readable reason — never a generic "this changed" warning. Every rule is pure pattern-matching over the diff and file content: no code is executed, no database or queue connection is made, and no finding is ever based on anything other than a rule a human can read and reason about. See VISION.md for the full design philosophy, architecture principles, and scope.

Rules

Fifteen rules across four categories. Severity is Critical (destructive regardless of context), Warning (a real but conditional operational risk), or Info (worth a look, often not actually a problem).

Config / Environment

Queue Jobs

Migrations

Composer

CLI reference

• --fail-on={info|warning|critical} — optional, lowercase-only. Omit it to always exit successfully regardless of findings; set it to gate CI on a minimum severity. The command exits non-zero as soon as any finding meets or exceeds that threshold.
• --format=json — machine-readable output for CI, a PR-comment bot, or any other integration. stdout carries only the JSON document — safe to pipe straight into jq or any JSON consumer. Every failure path (an invalid option, a Git error) also emits valid JSON under --format=json, with the same exit code as console mode.

JSON output & compatibility

schema_version is a stated compatibility promise, not an incidental field:

• Within schema_version: "1", changes are additive only — a new field may be added; no existing field is ever renamed, removed, or repurposed.
• A breaking change increments schema_version to "2" — it never silently changes what "1" means. A consumer that ignores unknown fields is safe across additive changes without ever branching on schema_version.
• New rule ids may be added at any time; an existing rule id, once shipped, is not renamed.
• reason_code is always present as a key, null when a rule has none to give — never conditionally omitted.

Known Limitations

TicoScope is entirely static analysis of git diffs and file content — it never executes code, never runs a migration, never introspects a live database or queue. That trade-off (speed, safety, zero-config CI use) shapes every rule the same few ways:

• Pattern-based, not size/shape-aware — a rule recognizes a code pattern, not the actual size of a table or the real impact of a dependency bump.
• Diff-scoped, not a full-codebase audit — most rules only look at what a diff actually added, so untouched code never re-fires; the trade-off is that an effect felt elsewhere in an untouched file isn't caught.
• Never guesses at an unresolvable value — a variable or dynamic expression is always skipped, never assumed. A missed finding is always preferred over a fabricated one.

See each rule's own entry above for anything more specific, and VISION.md §4 for the full reasoning.

Compatibility & CI

CI runs the full suite against every valid combination of PHP 8.2/8.3/8.4 and Laravel 11/12/13 (PHP 8.2 × Laravel 13 is excluded — Laravel 13 itself requires PHP 8.3+), plus a dedicated --prefer-lowest job against the oldest declared combination — see .github/workflows/tests.yml.

Prior art / related projects

TicoScope leads with a multi-signal report (migrations, queued jobs, config/env, Composer dependencies, one severity model) and a CI-gate-first design, not with migration detection alone:

• Migration-risk linters (the closest overlap): aofdafaw/Laravel-migration-guard, malikad778/laravel-migration-guard, shashankafre/migration-guard, nkmryu/laravel-strong-migrations, catidegla/safe-migrations, roslov/laravel-migration-checker — modeled on Ruby's strong_migrations. If all you want is deep migration-only linting, one of these may suit you better.
• Schema-drift detection (a related, distinct problem): MigrAlign, laravel-schema-sentinel, erimeilis/laravel-migrations-drift.
• The closest architectural precedent: Roave/BackwardCompatibilityCheck — diffs two git revisions and classifies API breaks by severity, for library backward compatibility rather than application deployment risk.
• Not the same category: Laravel Pulse, Telescope, Horizon, and Nightwatch are runtime observability, not pre-deploy analysis. Forge, Envoyer, and Laravel Cloud execute deployments; they don't analyze what's in one.

Contributing

See CONTRIBUTING.md — adding a new Rule is the primary way this project grows, and it's a deliberately small, reviewable kind of PR.

License

MIT. See LICENSE.