bloc_signals_lint

⚡ 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 10 modular packages:

Package Version Description
bloc_signals pub Core pure Dart reactive state primitives bridging BLoC & Signals
bloc_signals_flutter pub Flutter UI bindings, providers, builders, listeners & selectors
bloc_signals_jaspr pub Jaspr web component integration and state binding for BlocSignal
bloc_signals_riverpod pub Bidirectional Riverpod 2/3 interop adapters & provider extensions
bloc_signals_hydrate pub Automated synchronous local state persistence & hydration
bloc_signals_replay pub Undo & redo state history tracking for CubitSignal and BlocSignal
bloc_signals_otel pub OpenTelemetry tracing and span generation for state transitions
bloc_signals_devtools pub Universal DevTools telemetry observer using dart:developer
bloc_signals_test pub Declarative unit testing utilities (blocSignalTest)
bloc_signals_lint pub 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 (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. —
avoid_top_level_bloc_signal_instances Warning Flags top-level variables and static fields declared directly as BlocSignal / CubitSignal instances. —

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
avoid_providing_existing_instance_with_create Warning Flags passing existing variable references to BlocSignalProvider(create: ...) instead of BlocSignalProvider.value(value: ...). —
avoid_manual_close_on_provided_bloc Warning Flags calling .close() manually on state containers retrieved via context.read<T>() or BlocSignalProvider.of(context). —

🚀 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
  1. 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.

Libraries

bloc_signals_lint