bloc_signals_lint 0.1.1

Custom lint rules and analyzer diagnostics for BlocSignal and CubitSignal.

⚡ bloc_signals_lint

"With the rigor of Bloc and the flex and speed of Signal"

Custom static analysis lints, diagnostics, and automated IDE quick-fixes for bloc_signals.

Built on top of custom_lint, bloc_signals_lint catches common framework misuse, preserves Zone-context transition tracing, and enforces BlocSignal architectural invariants directly inside your IDE.

---

🌐 Ecosystem Packages

Package	Purpose	Pub.dev Link
bloc_signals	Core pure-Dart state containers, event registry, & VM Service telemetry	📦 pub.dev
bloc_signals_flutter	Flutter UI widgets (BlocSignalProvider, BlocSignalBuilder, BlocSignalListener, BlocSignalConsumer, BlocSignalSelector)	📦 pub.dev
bloc_signals_riverpod	Bidirectional Riverpod interop adapters (toBlocSignal(ref), toProvider())	📦 pub.dev
bloc_signals_hydrate	Persistent state storage (HydratedCubitSignal, HydratedBlocSignal)	📦 pub.dev
bloc_signals_devtools	Dedicated Flutter DevTools extension inspector UI	📦 pub.dev
bloc_signals_test	Declarative unit testing helpers (blocSignalTest)	📦 pub.dev
bloc_signals_lint	Static analysis lints & IDE quick-fixes	📦 pub.dev
otel_bloc_signals	OpenTelemetry tracing observers	📦 pub.dev

---

⚡ Rules & Quick-Fixes

Core Framework Rules

Rule	Default Severity	Description	Automated Fix
avoid_duplicate_event_handlers	Warning	Flags multiple on<E> registrations for the exact same event type E within a BlocSignal constructor.	—
require_super_on_event	Warning	Enforces calling super.onEvent(event) inside onEvent overrides to preserve Zone event context.	Cmd+. -> Add super.onEvent(event);
avoid_stream_transformers_on_bloc_signal	Warning	Flags stream transformer invocations (e.g. .transform(), .debounce(), .switchMap()) directly on synchronous BlocSignalBase instances.	—
avoid_direct_signal_mutation_outside_bloc	Warning	Prevents external code outside the state container class from calling protected emit() or mutating internal signal state.	—

Flutter UI Rules

Rule	Default Severity	Description	Automated Fix
avoid_emit_in_build	Warning	Flags calls to emit() or add() on state containers directly inside Flutter Widget.build() methods.	—
avoid_unmanaged_signal_effects	Warning	Flags unmanaged effect() calls created inside Flutter Widget or State methods without lifecycle cleanup.	—
prefer_bloc_signal_provider_read_in_callbacks	Warning	Warns when context.watch<T>() is used inside event callback closures (e.g. onPressed), suggesting context.read<T>().	Cmd+. -> Replace watch with read

---

🚀 Quick Setup

1. Add custom_lint and bloc_signals_lint to your pubspec.yaml:

dev_dependencies:
  custom_lint: ^0.7.0
  bloc_signals_lint: ^0.1.0

2. Enable custom_lint in your analysis_options.yaml:

analyzer:
  plugins:
    - custom_lint

---

⚙️ Customization & Inline Ignores

Disable or customize severity in analysis_options.yaml:

custom_lint:
  rules:
    - avoid_duplicate_event_handlers: false
    - require_super_on_event: error

Or ignore inline in code:

// ignore: avoid_duplicate_event_handlers
on<Increment>((event, emit) => emit(stateValue + 1));