Psalm Laravel Nova Laravel Package

Technical Evaluation

Architecture fit

• The package is a Psalm plugin (psalm-plugin Composer type) targeting Laravel Nova. It slots into Psalm's plugin event system (PluginEntryPointInterface, AfterCodebasePopulated, AfterClassLikeVisit) and/or ships stub files to teach Psalm about Nova's magic methods, fluent field chains, and dynamic resource/action/filter APIs.
• Fit is strictly developer-tooling: require-dev only, zero runtime footprint, no production coupling. That is the lowest-risk integration profile a package can have.
• It only makes sense if the team has already standardized on Psalm. Laravel shops overwhelmingly use PHPStan + Larastan; if that is the house analyzer, this package has no path in regardless of quality.
• Nova's fluent API (Text::make()->sortable()->rules(...), public function fields(Request $request)) is exactly the surface static analysis struggles with. A plugin here plausibly converts a class of runtime admin-panel errors into compile-time errors — real value, if coverage is real.
• v0.2.3 reinforces this thesis: both shipped fixes tighten modeling of Nova's callback-accepting signatures — canSee() on Actions, Filters and Lenses accepting a NovaRequest callback, and Field::make()'s resolve callback accepting a typed resource/attribute. These are precisely the "closure or scalar, magic-typed arguments" patterns Psalm cannot infer alone, which is the package's entire reason to exist.

Integration feasibility

• Mechanically trivial: composer require --dev interaction-design-foundation/psalm-laravel-nova, add <pluginClass> to psalm.xml, run vendor/bin/psalm.
• The hard blocker is Nova itself: it is commercial and closed-source, distributed via nova.laravel.com behind licensed Composer credentials. Any CI job that resolves the plugin against a real Nova install must hold NOVA_USERNAME/NOVA_PASSWORD (or a license key) as secrets. That is a procurement/security/ops dependency, not a code dependency.
• Because Nova is closed source, plugin authors must reverse-engineer internals. Compatibility is a tight matrix: Nova major version × Laravel version × PHP version × Psalm version.
• v0.2.3's fixes are evidence the authors are working against real Nova usage rather than only hand-written fixtures — but they still do not prove the plugin's own CI runs against a licensed Nova install.

Technical risk

• Maturity is the dominant risk, modestly reduced but not resolved. 2 stars, 0 dependents, opportunity score ~30, single-org provenance (InteractionDesignFoundation). Still effectively an internal tool that was open-sourced.
• Version 0.2.3 is a pre-1.0 patch. No breaking changes and no deprecations in this release; upgrades within 0.2.x should be low-risk. But 0.x semantics mean the plugin author reserves the right to change configuration/plugin-class surface before 1.0 — pin explicitly.
• Bus factor / abandonment unchanged. If IDF stops using Nova or migrates analyzers, the plugin goes stale silently. Nova majors shift internals, and a stale plugin produces false confidence rather than loud failure. The presence of a Renovate bot (PR #23) is a weak but positive automation signal; it does not indicate feature maintenance.
• Closed-source target. Coverage claims cannot be verified from the repo alone; you must read the stubs and hooks. v0.2.3 confirms Actions, Filters, Lenses and Fields are modeled at least for these callback paths — nothing is demonstrated for resources, metrics, lenses-as-classes, or custom field types beyond that.
• Psalm's own trajectory. Psalm is in a weaker ecosystem position than PHPStan for Laravel. Betting dev tooling on the less-supported analyzer compounds risk.
• License is MIT, which mitigates abandonment: fork-and-maintain is legally clean, though it costs engineering hours.
• Release cadence is the most useful new datapoint. A fix release landing on the 0.2.x line, with named human authorship on both functional PRs, indicates an actively triaged project rather than an abandoned dump. One release is not a trend; re-check at the next Nova or Psalm major.

Key questions

1. Which Nova major versions and which Psalm versions are supported, and is there a tested compatibility matrix?
2. Does it ship static stubs, dynamic hooks, or both — and what is the actual coverage of Nova's surface (resources, fields, actions, filters, lenses, metrics, custom field types)?
3. Is CI for the plugin itself run against a licensed Nova install, or is it developed against hand-written fixtures? v0.2.3's fixes look fixture- or usage-driven; ask directly whether a real Nova install is in the plugin's own pipeline.
4. What is the maintenance model — one maintainer, a team, best-effort? Is alies-dev a funded maintainer or a volunteer?
5. Does it degrade gracefully (warn/error) when Nova bumps a version, or silently no-op?
6. Is there an internal owner willing to fork and maintain it if upstream stalls?
7. Is there a 1.0 roadmap or a stated stability commitment for the plugin-class/config surface?

Integration Approach

Stack fit

• Target stack: Laravel + Laravel Nova + Psalm (dev). Confirm analyzer choice before evaluating the plugin further; if the answer is PHPStan/Larastan, stop here.
• Best fit is a team with an existing Psalm baseline that is already suppressing a large volume of Nova-related MixedAssignment/UndefinedMethod/PossiblyInvalidArgument issues. That is the measurable pain this package addresses.
• Teams that currently suppress canSee() and Field::make() callback complaints specifically should see a measurable delta from v0.2.3 alone — that makes it a good first spike target.
• Poor fit for teams with no static analysis today — adopting Psalm and a low-maturity Nova plugin simultaneously doubles the unknown surface.

Migration path

1. Decide analyzer strategy (Psalm vs. PHPStan) as an architectural decision, not a per-repo one.
2. Provision Nova license credentials for CI as managed secrets; document rotation and access scope.
3. Add the plugin on a branch at v0.2.3 (not ^0.2), run psalm --set-baseline before and after to isolate the plugin's delta.
4. Diff the issue set: expect a drop in Nova-related false positives and a possible rise in genuine errors previously masked.
5. Pin the plugin version explicitly; revisit floating constraints only after a compatibility matrix is confirmed or 1.0 ships.

Compatibility

• Lock the quadruple: PHP, Laravel, Nova, Psalm. Any Nova minor/patch upgrade warrants re-running the plugin and inspecting the delta.
• v0.2.3 is a patch on the 0.2 line: no config keys renamed, no plugin class changed, no deprecations announced. In-place upgrade from 0.2.2 is expected to be drop-in; still re-run the baseline diff because removing false positives shifts the issue set in both directions.
• Because Nova resolution needs credentials, local dev environments and CI both need the Composer auth configured; missing auth fails as a dependency-resolution error, not a plugin error, which is confusing to diagnose.
• Verify the plugin's composer.json constraints against your Nova pin before adopting; an over-broad constraint is a red flag.

Sequencing

• Phase 1 (evaluation, 1–2 days): spike on a single Nova-heavy module — ideally one using canSee() closures and Field::make() resolve callbacks, to exercise the v0.2.3 fixes — measure issue delta, inspect stub coverage, read the plugin source.
• Phase 2 (pilot): enable for one package/module in CI in non-blocking mode; collect false positives.
• Phase 3 (adoption): promote to blocking, vendor/fork the plugin internally, add a maintainer-of-record.
• Phase 4 (ongoing): tie plugin upgrades to Nova upgrades in the same change window; take patch releases opportunistically but always behind a baseline diff.

Operational Impact

Maintenance

• Near-zero runtime maintenance: dev-only dependency, no deploy artifact, no production surface.
• Real maintenance is version treadmill work: every Nova major (and many minors) and every Psalm major requires validating the plugin still functions. Budget a recurring task, not a one-off.
• Given the maturity signals, plan for the possibility of owning a fork. MIT license makes this viable; estimate a few engineer-days per year plus spike work on Nova majors. v0.2.3 slightly lowers the near-term probability of that call being needed, but does not change the sizing.

Support

• GitHub issues only, no SLA, tiny user base — issues filed may sit. Internal ownership is mandatory; treat upstream as a convenience, not a support channel.
• Positive counter-signal: both functional PRs in v0.2.3 are authored by a named maintainer and reference concrete Nova API behaviour, suggesting issues do get triaged. Weight this lightly until a second or third release confirms the pattern.
• Onboarding cost: engineers need working knowledge of both Psalm plugin configuration and Nova's fluent/magic API to interpret diagnostics correctly. The latter is niche.

Scaling

• Psalm runs full-codebase analysis and is generally slower than PHPStan; in a monorepo this becomes a CI wall-clock cost. Use --threads, incremental cache, and scoping (analyze changed packages only).
• The plugin adds per-file hook overhead on class-like and method visits; typically small, but measure rather than assume on a large Nova codebase.
• Nova codebases are often small relative to the app, so analysis scope can be limited to app/Nova and adjacent service classes to keep cost proportionate.

Failure modes

• Silent regression: plugin loads but no longer matches Nova internals after an upgrade → analysis passes with false confidence. Mitigate with a periodic sanity test asserting known-bad Nova code is still flagged — add canSee() callback misuse and a mistyped Field::make() resolve callback as explicit regression cases, since upstream now covers them.
• CI breakage via credentials: expired Nova license or rotated secrets fail the build with a dependency error. Alert on resolution failure specifically.
• False-positive creep: v0.2.3 is a direct, welcome counterexample — two whole classes of false positives removed. But the same dynamic works in reverse: adopting a new plugin version can surface issues in previously clean code. Keep the baseline + non-blocking rollout discipline for every upgrade, including patches.
• Upstream abandonment: no commits for a Nova cycle; plugin constraints become unsatisfiable. Mitigate with internal fork and a documented exit path.
• Pre-1.0 API churn: a future 0.3/1.0 may rename plugin classes or config keys. Pin exactly, and read release notes before bumping the minor.
• Baseline drift: a large committed baseline can mask the plugin's actual contribution; keep baselines scoped and reviewed.

Ramp-up

• Low mechanical ramp-up: one config stanza, one Composer line, familiar Psalm workflow. v0.2.3 requires no config change.
• Moderate cognitive ramp-up: interpreting Nova-specific diagnostics requires understanding the fluent API and the plugin's modeling choices; expect false-positive triage during the first month — though the two most common callback-related sources are now fixed upstream.
• Overall recommendation: pilot, don't standardize — unchanged, with slightly improved confidence. v0.2.3 is a competent patch that fixes real false positives and demonstrates active triage, which nudges the maturity picture from "possibly abandoned" to "small but alive." It does not change the fundamentals: 2 stars, 0 dependents, a closed-source target, a pre-1.0 surface, and no evidence of a published compatibility matrix. Gate adoption on a measured issue-delta in one module and on securing an internal maintainer with a fork-ready posture.