bloc_signals_lint 1.3.0

Custom lint rules and analyzer diagnostics for BlocSignal and CubitSignal.

⚡ bloc_signals_lint "With the rigor of BLoC and the flex and speed of Signals" 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

The BlocSignal monorepo consists of 11 modular packages:

Package	Version	Description
bloc_signals		Core pure Dart reactive state primitives bridging BLoC & Signals
bloc_signals_flutter		Flutter UI bindings, providers, builders, listeners & selectors
bloc_signals_bloc		Classic BLoC 8/9 interop adapters & bidirectional event bridges
bloc_signals_riverpod		Bidirectional Riverpod 2/3 interop adapters & provider extensions
bloc_signals_jaspr		Jaspr web component integration and state binding for BlocSignal
bloc_signals_hydrate		Automated synchronous local state persistence & hydration
bloc_signals_replay		Undo & redo state history tracking for CubitSignal and BlocSignal
bloc_signals_otel		OpenTelemetry tracing and span generation for state transitions
bloc_signals_devtools		Universal DevTools telemetry observer using dart:developer
bloc_signals_test		Declarative unit testing utilities (blocSignalTest)
bloc_signals_lint		Custom analyzer lint rules & automated IDE quick-fixes

---

⚡ 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 (for example .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.	—
avoid_top_level_bloc_signal_instances	Warning	Flags top-level variables and static fields declared directly as BlocSignal / CubitSignal instances.	—
require_cubit_signal_mixin_init	Warning	Enforces calling initCubitSignal(initialState: ...) in constructors of classes mixing in CubitSignalMixin or BlocSignalMixin.	Cmd+. -> Add initCubitSignal(initialState: ...);
avoid_raw_signal_effects_in_bloc	Warning	Flags unmanaged top-level effect() calls inside BlocSignalBase containers, recommending createEffect().	Cmd+. -> Replace effect with createEffect
prefer_named_replay_constructor	Warning	Flags super.positional(...) invocations in ReplayCubit and ReplayBloc subclasses, recommending super(initialState: ...).	Cmd+. -> Replace super.positional(...) with super(initialState: ...)
require_emit_in_helper_name	Warning	Flags private helper methods calling emit() whose names do not reflect state emission.	Cmd+. -> Rename to ...AndEmit
avoid_multiple_synchronous_emits	Warning	Flags multiple synchronous emit() calls along the same linear execution path without an intervening await.	—
avoid_primitive_event_types	Warning	Flags BlocSignal<Event, State> or BlocSignalMixin using primitive or untyped types (int, String, bool, dynamic, etc.) as event types.	—
avoid_pseudo_events_in_telemetry	Warning	Flags emitTelemetry('...') calls inside CubitSignal where the name matches UI event action patterns (Pressed, Clicked, Submitted, etc.).	—

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 (for example onPressed), suggesting context.read<T>().	Cmd+. -> Replace watch with read
avoid_providing_existing_instance_with_create	Warning	Flags passing existing variable references to BlocSignalProvider(create: ...) instead of BlocSignalProvider.value(value: ...).	Cmd+. -> Replace create: with value:
avoid_manual_close_on_provided_bloc	Warning	Flags calling .close() manually on state containers retrieved via context.read<T>() or BlocSignalProvider.of(context).	—
avoid_invalid_context_select_generics	Warning	Flags context.select<B, R> where generic parameters are omitted or invalid.	—
avoid_context_watch_for_bloc_state	Warning	Flags context.watch<T>() on state containers inside build() methods to prevent missing state emission rebuilds.	Cmd+. -> Replace watch with read
avoid_unused_select_result	Warning	Flags calling context.select(...) as an unused expression statement where the result is discarded.	—

---

🚀 Quick Setup

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

dev_dependencies:
  custom_lint: ^0.7.0
  bloc_signals_lint: ^1.0.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));

---

🤖 AI Coding Assistant Skill

This package is supported by an official pre-packaged AI Coding Skill representing analyzer rules, IDE diagnostics, and automated quick-fix rules for BlocSignal.

If you develop with AI coding assistants (such as Claude Code, Antigravity, Gemini, Cursor, or Codex), you can load the bloc-signals skill bundle to guide your assistant's code generation and analysis.