ML-195: Add credo check for put_toast/put_toast! usage in live components

2026-05-21 08:08:11 +01:00
parent 66fb688b2a
commit ff42f24972
5 changed files with 310 additions and 6 deletions
@@ -0,0 +1,73 @@
+---
+id: ML-195
+title: Add Credo check for LiveComponent toast helper usage
+status: Done
+assignee:
+  - pi
+created_date: "2026-05-21 06:57"
+updated_date: "2026-05-21 07:05"
+labels: []
+dependencies: []
+priority: medium
+ordinal: 38000
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+
+Add a custom Credo check that flags calls to `put_toast/3` from LiveComponent modules so contributors use the LiveComponent-safe `put_toast!/2` helper instead.
+
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+
+<!-- AC:BEGIN -->
+
+- [x] #1 Credo fails when a LiveComponent module calls `put_toast/3`.
+- [x] #2 Credo does not flag allowed `put_toast!/2` calls inside LiveComponents.
+- [x] #3 Credo does not flag `put_toast/3` usage outside LiveComponent modules.
+- [x] #4 Automated tests cover the new check behavior.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+
+1. Review Credo configuration and any existing custom checks/tests to match project conventions.
+2. Add a custom Credo check that detects modules using `use MusicLibraryWeb, :live_component` and reports calls to `put_toast/3`, including pipeline form when applicable.
+3. Register the check in Credo config so `mix credo` runs it.
+4. Add focused tests for disallowed LiveComponent usage, allowed `put_toast!/2`, and allowed non-LiveComponent `put_toast/3` usage.
+5. Run the relevant test file and Credo check to validate behavior.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+
+Implemented `MusicLibrary.Credo.NoLiveComponentPutToast`, registered it in `.credo.exs`, and updated existing `RecordForm` LiveComponent toast calls to `put_toast!/2` so the new rule can be enabled cleanly. Validation: `mix test test/music_library/credo/no_live_component_put_toast_test.exs`; `mix test test/music_library_web/live/collection_live/show_test.exs --max-failures 1`; `mix test test/music_library_web/live/collection_live/index_test.exs --max-failures 1`; `mix credo --strict`.
+
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+
+Summary:
+
+- Added `MusicLibrary.Credo.NoLiveComponentPutToast`, a custom Credo warning that detects `put_toast/3` calls inside LiveComponent modules and covers direct, piped, qualified, and captured call forms.
+- Registered the custom check in `.credo.exs`.
+- Cleaned up existing `RecordForm` LiveComponent toast usage by switching to `put_toast!/2` before returning/pushing patches.
+- Added focused Credo check tests for disallowed LiveComponent usage and allowed LiveComponent/non-LiveComponent cases.
+
+Validation:
+
+- `mix test test/music_library/credo/no_live_component_put_toast_test.exs`
+- `mix test test/music_library_web/live/collection_live/show_test.exs --max-failures 1`
+- `mix test test/music_library_web/live/collection_live/index_test.exs --max-failures 1`
+- `mix credo --strict`
+
+Docs:
+
+- No documentation update needed; `docs/project-conventions.md` already documents the LiveView vs LiveComponent toast helper rule.
+<!-- SECTION:FINAL_SUMMARY:END -->