# Larastan (PHPStan for Laravel)

Static analysis for the Crewli backend. Configured at level 6 with
an accept-all baseline.

## Running locally

- `composer analyse` — run static analysis. Suppresses baselined errors.
- `composer analyse:baseline` — regenerate the baseline. Use after a
  reduction sprint to lock in the new lower-debt state.
- `composer analyse:clear-cache` — clear PHPStan result cache.

Memory: 2G default. Bump to 4G in `composer.json` if you hit OOM.

## The accept-all baseline model

`phpstan-baseline.neon` is a time-snapshot of every error that existed
when Larastan was first installed. Errors in the baseline are
suppressed; Larastan reports only errors NOT in the baseline.

### Rules

1. **New code must not introduce new errors.** Fix them before merge.
   Do NOT regenerate the baseline to absorb new errors.
2. **Refactoring that REMOVES baseline errors is good.** Regenerate
   the baseline (`composer analyse:baseline`) so the file reflects
   the new lower-debt reality. Commit alongside the refactor.
3. **Reduction sprints REPLACE baseline entries with fixes.** See
   `/dev-docs/BACKLOG.md` for sprint items.

## Current target

Level 6. Catches:
  - missing typehints
  - method existence
  - null-safety on common paths
  - Laravel model property existence

Level 8 is the eventual target — deferred until level 6 baseline
reaches zero.

## Adding exclusions

Do NOT add blanket `ignoreErrors` patterns to `phpstan.neon`. False
positives get a code-level `@phpstan-ignore-next-line` comment with
upstream-issue justification. Pattern-level ignores rot fast.

## CI integration

Not enabled yet. When added, `composer analyse` is a blocking PR
gate. The "new code must not introduce new errors" rule is only
enforceable with CI.