cherrypick_lint 4.0.0
cherrypick_lint: ^4.0.0 copied to clipboard
Analyzer plugin that catches CherryPick DI API misuse right in the IDE and in dart analyze: missing await on scope disposal, misused annotations, and runtime traps.
cherrypick_lint #
An analyzer plugin that
catches CherryPick DI API misuse in the
IDE and in dart analyze — no build_runner required.
cherrypick_generator already validates annotations, but only when you run
codegen. cherrypick_lint surfaces the same class of mistakes (plus a few
runtime traps codegen can't see) as you type.
Built for
cherrypick4.x, usable with 3.x, not for 2.x. See Whichcherrypickversions for what changes.
Install #
The plugin is not a dependency of your project — the analysis server
resolves it itself. Name it in the top-level plugins section of your
analysis_options.yaml:
# analysis_options.yaml
plugins:
cherrypick_lint: ^4.0.0-dev.0
The package is on pub.dev. To try an unreleased change, point the plugin at a local checkout of this repository instead:
# analysis_options.yaml
plugins:
cherrypick_lint:
path: /absolute/path/to/cherrypick/cherrypick_lint
A version constraint, a constraint plus a hosted server URL, and a path are
the only forms the plugins section accepts.
Then restart the Dart Analysis Server (in VS Code: Dart: Restart Analysis
Server); analyzer plugins are only picked up on start-up. The rules then show
up both in the IDE and in dart analyze / flutter analyze — there is no
separate command to run.
Requires Dart >=3.10 (Flutter >=3.38) — the release that introduced analyzer plugins.
Rules #
await-rules — missing await on scope disposal (warning) #
| Rule | Triggers on | Quick fix |
|---|---|---|
avoid_unawaited_close_sub_scope |
scope.closeSubScope(name) without await |
Add await |
avoid_unawaited_close_scope |
CherryPick.closeScope(...) without await |
Add await |
avoid_unawaited_scope_dispose |
scope.dispose() without await, where scope is a Scope |
Add await |
Wrapping the call in unawaited(...) is treated as an explicit, intentional
fire-and-forget and doesn't trigger these rules.
annotation-rules — invalid annotation usage (error) #
| Rule | Triggers on | Quick fix |
|---|---|---|
module_requires_part_directive |
a @module library without part '<file>.module.cherrypick.g.dart'; |
Add the generated part directive |
module_must_extend_module |
@module class without Module in its supertype chain |
— |
module_must_be_abstract |
@module on a non-abstract class |
Make class abstract |
module_method_missing_binding |
a method in a @module class without @provide/@instance — private and static included |
— |
inject_field_must_be_late_final |
@inject field not declared late final |
Add late final |
named_value_must_not_be_empty |
@named('') |
— |
params_requires_provide |
@params without @provide |
— |
module_requires_part_directive covers the one requirement whose failure is
silent: moduleBuilder is a PartBuilder, so without the part directive
build_runner finishes successfully having written nothing, saying so only
through a log warning.
module_must_extend_module covers the other hard requirement. The generated
part is final class $Foo extends Foo, whose builder() body is a list of
bind<T>() calls; both members come from Module, so a @module class that
doesn't extend it gets a part that can't compile — and the generator itself
reports nothing, since it writes the file happily.
abstract, by contrast, is not something the generator checks: it collects the
non-abstract methods and emits final class $Foo extends Foo either way. A
concrete @module class is still a dead end, which is why the rule stays an
error — Module.builder is abstract, so without an override Dart rejects the
class (non_abstract_class_inherits_abstract_member), and with one the
generator's validator rejects builder itself as a method carrying neither
@provide nor @instance.
That same validator is why module_method_missing_binding ignores neither
private nor static methods: GeneratedClass collects ClassElement.methods
filtered only by !isAbstract, and every one of them must carry @provide or
@instance or the build fails. Getters and setters are the only exemption —
they live in ClassElement.getters/.setters, which codegen never reads.
An abstract method inside a @module class is a different problem the rule
does not yet describe well: codegen skips it, but the generated
final class $Foo extends Foo then leaves it unimplemented, so the part
doesn't compile — and annotating it doesn't help (with @provide the binding
is silently dropped and builder() comes out empty). The rule still reports
such a method; the fix is to give it a body or move it out of the module
class, not to add an annotation.
runtime-trap-rules — footguns codegen can't see #
| Rule | Severity | Triggers on | Quick fix |
|---|---|---|---|
avoid_extends_silent_observer |
warning |
class Foo extends SilentCherryPickObserver |
Replace with implements CherryPickObserver |
avoid_redundant_singleton_on_instance |
info |
.singleton() chained after .toInstance(...)/.toInstanceAsync(...) |
Remove redundant .singleton() |
avoid_singleton_on_provide_with_params |
info |
.singleton() chained after .toProvideWithParams(...)/.toProvideAsyncWithParams(...) |
— |
avoid_resolve_in_to_instance |
warning |
scope.resolve()/resolveAsync()/tryResolve()/tryResolveAsync() inside .toInstance(...)/.toInstanceAsync(...) |
— |
avoid_precomputed_value_in_provide |
warning |
.toProvide(...)/.toProvideAsync(...)/.toProvideWithParams(...)/.toProvideAsyncWithParams(...) closure that just returns a variable built outside it |
— |
On cherrypick 4.x, SilentCherryPickObserver is deliberately skipped by
Scope's fast path (if (_observer is SilentCherryPickObserver)), so an
extends subclass silently receives none of the 14 observer callbacks —
implements CherryPickObserver is what you want instead. That fast path does
not exist in 3.x, where extending the class is harmless: disable the rule
there (see Disabling a rule).
.singleton() after .toInstance(...) is a documented no-op (see
Binding.singleton()'s doc comment): the bound value is already a single,
constant instance, so the call does nothing but read as if it did.
.singleton() after .toProvideWithParams(...) turns the binding into a
"master singleton" that only honors params on the very first resolve — every
later resolve returns the same cached instance regardless of params. That's
sometimes intentional, so this rule has no quick fix; it's a nudge to
double-check, not an auto-correctable mistake.
.toInstance(...) bindings inside a Module.builder are applied
sequentially, so calling scope.resolve<T>() (or resolveAsync/tryResolve/
tryResolveAsync) to build the value can throw Can't resolve dependency ...
if T is registered later in the same builder (see Binding.toInstance()'s
doc comment for the full example). Deferring the resolve with
.toProvide(() => ...) runs it lazily, once every sibling binding is already
registered — this rule has no quick fix since the fix depends on how the
dependency chain should actually be built.
A provider closure exists to be re-invoked on every resolve<T>() — the
value should be built there. bind<T>().toProvide(() => variable), where
variable was already constructed earlier in the same method, actually
builds the value once, at Module.builder() time; every resolve<T>() then
silently returns that same instance, an unintended pseudo-singleton that
bypasses .singleton()'s explicit opt-in. .toInstance(...) isn't affected
by this — it always constructs eagerly regardless of where the value comes
from, so precomputing a value for it is fine.
Disabling a rule #
Every rule is enabled by default. Switch one off under the plugin's
diagnostics key:
# analysis_options.yaml
plugins:
cherrypick_lint:
version: ^4.0.0-dev.0
diagnostics:
avoid_extends_silent_observer: false
A single line or file can be exempted with an ignore comment, using the
<plugin>/<rule> form:
// ignore: cherrypick_lint/avoid_unawaited_scope_dispose
scope.dispose();
Compatibility #
Requires Dart >=3.10.0 (Flutter >=3.38).
Every published analysis_server_plugin release pins one exact analyzer
version, and analyzer >=13.1.0 requires Dart >=3.11 — so which versions you
actually get follows from your SDK. Both resolutions are tested from the same
sources:
| Dart 3.10 (Flutter 3.38) | Dart 3.11+ (Flutter 3.41+) | |
|---|---|---|
analysis_server_plugin |
0.3.14 | 0.3.22 |
analyzer |
12.1.0 | 14.3.0 |
analyzer_plugin |
0.14.8 | 0.14.16 |
The rules and fixes compile against both analyzer majors unchanged.
Which cherrypick versions #
The plugin does not depend on cherrypick — it only reads your code — so
nothing stops you enabling it on any version. What differs is whether each
rule's claim is true for the API you actually have. This was checked by
running the plugin on a file that violates every rule, and by executing each
claimed runtime behaviour, against cherrypick 2.2.0, 3.0.0, 3.0.2 and
4.0.0-dev.6:
cherrypick |
Rules that apply |
|---|---|
| 4.x | All 15. |
| 3.x (tested: 3.0.0, 3.0.2) | 14 of 15. Not avoid_extends_silent_observer: the fast path it warns about exists only in 4.x, and on 3.x a subclass of SilentCherryPickObserver still receives its callbacks. Disable it there. |
| 2.x and older | Not supported. closeScope and closeSubScope are synchronous void and Scope.dispose() does not exist, so the await-rules flag calls with nothing to await, and their quick fix produces a use_of_void_result error. avoid_resolve_in_to_instance and avoid_singleton_on_provide_with_params describe behavior 2.x does not have (an eager resolve inside toInstance works, and .singleton() honors params on every resolve). |
Use the matching major of cherrypick_annotations and cherrypick_generator.
The module_*, inject_*, named_* and params_* rules mirror what the
generator enforces; the behavior they rely on (a PartBuilder writing
<file>.module.cherrypick.g.dart, the @provide/@instance validator) is
present in the cherrypick_generator sources of every release from 1.1.0.
Versions 0.1.x were built on custom_lint,
whose repository is archived and which its author no longer publishes. They were
never published to pub.dev — only relevant if you used the plugin from a
checkout of this repository; see Migration from 0.x
below.
Migration from 0.x #
The rules, their messages, severities and quick fixes are unchanged. Only installation changes:
0.1.x (custom_lint) |
1.0.0+ (analyzer plugin) |
|---|---|
dev_dependencies: custom_lint, cherrypick_lint |
no dependency at all |
analyzer: plugins: [custom_lint] |
top-level plugins: cherrypick_lint: ^4.0.0-dev.0 |
custom_lint: rules: - <rule>: false |
plugins: cherrypick_lint: diagnostics: <rule>: false |
dart run custom_lint in CI |
plain dart analyze |
// ignore: <rule> |
// ignore: cherrypick_lint/<rule> |
So: drop both dev_dependencies, replace the analyzer: plugins: block with
the top-level plugins: block above, delete any dart run custom_lint step
from CI, and restart the analysis server.
Development #
Every rule is covered by unit tests built on
analyzer_testing — inline
sources plus assertDiagnostics/assertNoDiagnostics, no fixture files and
no subprocess:
dart test
example/ is a rule-clean CherryPick setup that doubles as an
installation demo: its analysis_options.yaml enables this plugin by path,
and dart analyze there is expected to stay quiet.
Quick fixes have no automated coverage: analyzer_testing has no API for
testing fixes, and dart fix does not apply plugin fixes. Check them by hand
in the IDE.
Note: after changing this package's dependencies (or the Dart SDK),
dart analyzein a package that enables the plugin can start failing withBad state: The analysis server crashed unexpectedly. The analysis server caches a synthetic wrapper package per plugin configuration under~/.dartServer/.plugin_manager/<hash>/and reuses it after the plugin's dependencies have moved on. Delete the stale directories and the crash goes away:rm -rf ~/.dartServer/.plugin_manager