Richter Laravel Package

Getting Started

Richter is a static risk/reachability analyser for Laravel applications. It parses your app into a graph (entry points → controllers/jobs/middleware/models), grades the reachable surface, and emits text, markdown, and HTML reports with per-entry-point risk levels and the reasons behind them.

1. Install as a dev dependency so it never ships to production, and publish its config if the package offers a config file (check the README for the exact command and config path).
2. Define entryPoints first. This is the single most important config decision — everything else is measured relative to these roots. Typical roots: HTTP routes you expose, console commands, queue consumers, scheduled tasks. Order them deliberately: as of v0.70.0, entryPointKeepSet.kept and the task-slice kept list follow entryPoints order, so the order you write becomes the order in your reports and diffs.
3. Run the analysis once and expect a slow first pass. The graph cache format is now 28, so any existing cache rebuilds once after upgrading. This is normal, not a hang.
4. Read the HTML report first. The report's stat tiles now print the risk cause as text, matching what the text and markdown reports already did — so you can triage from the HTML without cross-referencing another format.
5. First use case: produce a baseline report of your app's current risk surface and commit/artifact it. Then use subsequent runs to diff risk movement across PRs, especially around refactors that delete classes or move jobs.

Implementation Patterns

Baseline-then-delta in CI. Generate the markdown report as a build artifact and diff it against the previous run. Markdown is the right format for this: it is stable, greppable, and already carries the same risk-cause text the HTML tiles now show. Keep the HTML for human review links.

Entry-point-scoped risk budgets. Grade per entry point rather than per app. With kept lists ordered by entryPoints, you can put your highest-risk surfaces (public HTTP, payment webhooks, anything queue-consumer driven) first and have the report read top-down in priority order. This also makes task-slices — the PR-scoped subset of kept surfaces — line up with your review order.

Model middleware from bootstrap/app.php, not the Kernel. In Laravel 11+ style apps, withMiddleware now correctly hides the app's Kernel groups during analysis. Keep middleware registration in one place; if you register groups in both bootstrap/app.php and a Kernel, the analysis will model the Laravel 11+ stack (bootstrap wins), which may not match what you assume is running.

Make dispatches resolvable. Queued classes that live outside \Jobs\ now read unresolved when the graph contains unresolved dispatches. If you want clean grades, keep ShouldQueue/Dispatchable classes in the conventional namespace and avoid dispatching from shapes the analyser cannot follow (see the spread note below). unresolved is a valid signal, but it is contagious — one unresolvable dispatch site can flip unrelated classes.

Write mass-assignment declarations separately. Combined declarations like $fillable = [...], $guarded = [...] were previously read incorrectly. They are fixed now, but separate $fillable and $guarded statements remain the least ambiguous form for both humans and the analyser.

Cache the graph across CI runs, keyed on package version. Tie your CI cache key to the Richter version plus composer.lock. A cache-format bump is a rebuild, not a failure, and refused cache entries (below) degrade gracefully.

Gotchas and Tips

• Expect a one-time full rebuild after upgrading. Cache format 28 invalidates existing caches. Budget CI time accordingly on the first run after the bump.
• Partial caches are refused, not trusted. A cache entry with a missing or mis-typed unparseable-files flag, or with no node metadata, is now rejected. Killed or timed-out CI jobs that leave a half-written cache will simply rebuild next time — good behaviour, but it means flaky CI shows up as slow runs, not as errors.
• Golden-file snapshots will break. entryPointKeepSet.kept and task-slice kept lists now follow entryPoints order instead of whatever order they previously had. If you snapshot JSON or markdown, re-record the snapshot as part of the upgrade; the semantic content is unchanged.
• Risk levels moved in both directions in this release — re-baseline before trusting a diff.
  • Up: a removed member's hazard now inherits the reach of the class's surviving members, so partially-deleted classes can grade higher.
  • Down: task-slices previously graded every kept surface as unproven, pinning risk at medium or above; that is fixed, so risk can now drop.
  • Both: a local tested two ways now keeps one absence style consistently, so sibling-read findings can appear or disappear between runs. The first post-upgrade report is not a regression signal. Diff run N against run N (same version), not against your pre-upgrade baseline.
• Dispatch-site detection changed in two opposing ways. A spread in a dispatched array is now an unresolved dispatch site (previously silent); a new of a non-dispatchable class inside an accumulated job array is no longer one. If you have ...$jobs-style dispatch helpers, expect new unresolved entries and either refactor the dispatch or accept the noise.
• Middleware reporting got noisier (by design). Group-size notes are now emitted for appendToGroup, prepend, a second call on the same group, and group(). On middleware-heavy apps this adds report lines that are informational, not hazards — filter on hazard/tier rather than scanning the raw list.
• group('name', [...]) is now read. If you previously worked around the analyser by inlining group definitions, you can move back to named groups.
• Fixed tier-3 hazard for guards that a group both appends and removes. That pattern previously produced a spurious tier-3 middleware hazard; if you suppressed or ignored it, remove the suppression.
• Sibling reads on parameters no longer borrow a same-named property's type. Findings on typed parameters in classes that also declare a property with the same name may shift; that is a correctness fix, not a behaviour change to work around.
• Extension points are thin. Day-to-day leverage comes from entryPoints configuration and report consumption rather than plugin hooks. Reach for config, not code, before considering a fork.