social-app/.trellis/spec/frontend/quality-guidelines.md

Quality Guidelines

Frontend quality baseline for apps/** changes.

---

Practical Conventions

1. Run Flutter analyzer/tests for touched scope before finalizing changes.
2. Keep error logging explicit at catch sites using project logger (getLogger(...)).
3. Prioritize regression tests for high-risk modules: auth/session, home viewport, cache/repository, agent SSE flows.
4. Keep docs/protocol/frontend mappings aligned for API-contract changes.

---

Real File Path Examples

• Lint/static analysis configuration:
  • apps/analysis_options.yaml
  • apps/pubspec.yaml (dev dependencies: flutter_test, bloc_test, mocktail)
• Test suites for high-risk modules:
  • apps/test/app/router/app_router_redirect_test.dart
  • apps/test/core/chat/ag_ui_service_test.dart
  • apps/test/data/cache/cached_repository_test.dart
• Logging usage examples:
  • apps/lib/features/auth/presentation/bloc/auth_bloc.dart
  • apps/lib/features/auth/presentation/cubits/login_cubit.dart
  • apps/lib/features/settings/presentation/cubits/automation_jobs_cubit.dart

---

Review Checklist

1. Layering and ownership
   • No feature business logic moved into shared data/** infra.
2. Error handling
   • Exceptions are either propagated or converted to typed user-safe errors.
   • Catch branches include context logging where actionable.
3. Contract alignment
   • If API/error/event contracts changed, protocol docs and mapping updates are in the same change.
4. Regression coverage
   • Add/adjust tests for changed behavior in critical flows.

---

Anti-patterns (with evidence)

• Error swallowing branches that silently downgrade behavior.
  • Existing examples to avoid extending:
    • apps/lib/app/di/injection.dart refresh callback catch returns false.
    • apps/lib/core/chat/ag_ui_service.dart malformed SSE payload parse catch ignores payload.
• Feature code bypassing shared feedback/loading primitives.
  • Project standard primitives exist in apps/lib/shared/widgets/toast/, apps/lib/shared/widgets/banner/, apps/lib/shared/widgets/app_loading_indicator.dart.
• Protocol changes implemented only in one layer.
  • Contract source of truth is under docs/protocols/** and must stay synchronized.

---

Uncertainties / Gaps

• The repository does not currently enforce all frontend rules via CI (for example, no strict automated checker for protocol-mapper parity).
• analysis_options.yaml is currently close to Flutter defaults; stricter lint rules may still be introduced incrementally.