flutter_slick_lints
Analyzer lints for flutter_slick — the rules that a doc comment can only ask for.
They run through custom_lint, so they appear in the IDE as you type, in
dart run custom_lint, and in CI.
Installing
dev_dependencies:
custom_lint: ^0.8.1
flutter_slick_lints: ^0.2.0
# analysis_options.yaml
analyzer:
plugins:
- custom_lint
flutter pub get, then restart the analysis server (in VS Code: Dart: Restart
Analysis Server). The SDK warns that analyzer: plugins: is deprecated —
custom_lint 0.8.x still registers that way, and there is nothing to move to
until it adopts the new analyzer plugin system. Silence it with
analysis_options_deprecated_plugins: ignore under analyzer: errors:.
In CI, add:
dart run custom_lint
Every rule is on by default. To switch one off:
custom_lint:
rules:
- avoid_redundant_redraw: false
Rules
| Rule | Catches | Quick-fix |
|---|---|---|
avoid_redundant_redraw |
A redraw() beside a loading()/idle() that already notifies |
deletes the line |
avoid_state_calls_in_init_state |
loading(), idle() or redraw() in initState(), where none of them reaches the view |
deletes the line |
avoid_notify_during_build |
A notification made while the view builds — setState() called during build |
— |
use_on_redirect |
A route overriding redirect instead of onRedirect, so its guard never runs |
renames it |
use_navigation_logic |
A route change made around NavigationLogic |
rewrites it as goTo |
use_slick_page_host |
A buildPage override that drops SlickPageHost and with it snapshot loading |
— |
avoid_redundant_redraw
A redraw() beside a loading() or idle() draws the view twice.
Future<void> refresh() async {
loading();
vehicles = await VehicleService.getAll();
idle();
redraw(); // LINT: 'idle()' notifies the view already
}
Every state method on ViewModel ends in notifyListeners(): loading() and
idle() when they change the loading state, redraw() on its own. So a
loading() … idle() pair rebuilds the view once, at the end, with the new
data already in place, and the redraw() after it is a second rebuild of the
same fields — worse, it tells the next reader that idle() left something
undrawn.
redraw() is for a change that no loading transition announces:
void search(String query) {
vehicles = VehicleService.search(query);
redraw(); // fine — nothing else notifies
}
The neighbour has to be a real transition. loading() and idle() are
guarded — each returns early when the loading flag already holds the value it
would set — so they notify on the transition, not on the call. An idle()
with no loading() before it therefore notifies nothing, and the redraw()
beside it is the only thing publishing the fields:
Future<void> annotate() async {
vehicles = await VehicleService.getAll();
redraw(); // fine — the idle() below returns early and notifies nothing
idle();
}
So the rule reads the loading state the body has reached: a view model is idle
by the time one of its methods runs, and each loading()/idle() before the
neighbour moves it. When one of those sits inside a branch, a loop or a try,
the state cannot be read off the source and the rule stays quiet — the fix
deletes code, so an uncertain report is worse than a missed one.
The rule resolves types, so a loading()/idle()/redraw() trio on a class
that is not a ViewModel is left alone, and it comes with a quick-fix that
deletes the line (dart run custom_lint --fix).
avoid_state_calls_in_init_state
The widget owns the loading state until initState() completes, so nothing
called in there reaches the view.
@override
Future<void> initState() async {
loading(); // LINT: already loading
vehicles = await _fetch();
redraw(); // LINT: nothing on screen to redraw
idle(); // LINT: the widget does this for you
}
Each one is a different shade of nothing. loading() returns early because the
flag starts true. redraw() notifies a view that is still behind the loading
widget. idle() clears the flag before isInitialised is set, so the widget
carries on showing the loading view regardless — and the framework's own
idle() afterwards then returns early.
Set the fields and let initState() return. A closure scheduled from
initState() is a different matter: it runs after initialisation, from a timer
or a future, and is not flagged.
avoid_notify_during_build
@override
Widget buildView(BuildContext context) {
vm.idle(); // LINT: this is a rebuild, mid-build
return Text(vm.title);
}
A ViewModelWidget listens to its view model and calls setState() on every
notification, so notifying from inside buildView, buildLoading or
buildLoadingOverlay is the framework's setState() or markNeedsBuild() called during build error — a red screen in debug, and a frame that never settles in
release.
Callbacks are fine, and are the usual destination for one of these:
onPressed: () => vm.refresh() runs after the build, not during it. A build
may read as much state as it likes; it just may not change it.
use_on_redirect
class DashboardRoute extends SlickRoute with $DashboardRoute {
@override
FutureOr<String?> redirect(BuildContext context, GoRouterState state) async {
// LINT: Slick calls onRedirect from here; this replaces that call
}
}
redirect is Slick's own override of go_router's hook — it is where the
framework hands control to onRedirect. Overriding it again takes that
dispatch out, and the compiler has nothing to say about it: both methods exist,
both have the right signature, and onRedirect simply stops being called. A
guard written there never runs, which reads as a route with no protection at
all.
The quick-fix renames the override. It is not offered when the class already
has an onRedirect — only the author knows which body to keep.
use_navigation_logic
const SampleRoute().go(context); // LINT
context.go('/sample'); // LINT
GoRouter.of(context).go('/sample'); // LINT
navigation.goTo(const SampleRoute()); // this one
NavigationLogic.goTo is not a wrapper around context.go. It clears the
DirtyStateMonitor, pushes the current path onto Slick's own history — the
history canGoBack, goBack() and goUp() read — and captures the page so
the destination can show it while its view model initialises. go_router knows
about none of that, so a route changed through it leaves unsaved-work warnings
armed, goBack() going somewhere else entirely, and the destination falling
back to its loading widget.
goTo, goReplace, goBack and goUp cover the same ground. Inside a view
model the quick-fix writes navigation.goTo(route) for you.
Popping a dialog is not a route change: Navigator.pop and popDialog are
left alone. So are .g.dart files — go_router's generated route mixins are
built out of the very calls this rule reports, and they are the ones goTo
ends up using.
use_slick_page_host
@override
Page<void> buildPage(BuildContext context, GoRouterState state) {
return CustomTransitionPage( // LINT: no SlickPageHost
key: state.pageKey,
child: build(context, state),
transitionsBuilder: _fade,
);
}
SlickPageHost is what makes snapshot loading work, in both directions: it
owns the repaint boundary NavigationLogic captures when you leave the page,
and it paints the previous page's snapshot while this one's view model
initialises. Slick's own buildPage wraps every page in one.
An override that does not leaves the page out of the mechanism — it shows its
loading widget on the way in, and the page after it does too, because there was
nothing to capture on the way out. Wrap the page's child in SlickPageHost, or
return super.buildPage(context, state) when the override only meant to change
something else.
Testing the rules
example/ is the test. It is a real Flutter package with real view models,
screens and routes, and its expect_lint markers make dart run custom_lint
fail when a marked line is not reported, or when any other line is:
cd example
flutter pub get
dart run custom_lint
A new rule lands with its cases in there — the ones it must catch and, just as important, the neighbouring ones it must not. The files are grouped by what they exercise:
| File | Rule |
|---|---|
vehicle_list_view_model.dart |
avoid_redundant_redraw |
init_state.dart |
avoid_state_calls_in_init_state |
vehicle_list_screen.dart |
avoid_notify_during_build |
vehicle_routes.dart |
use_on_redirect, use_navigation_logic, use_slick_page_host |
vehicle_routes.g.dart |
that generated files are skipped |