Skip to main content

cherrypick_lint 4.0.0-dev.0 copy "cherrypick_lint: ^4.0.0-dev.0" to clipboard
cherrypick_lint: ^4.0.0-dev.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 cherrypick 4.x, usable with 3.x, not for 2.x. See Which cherrypick versions 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 analyze in a package that enables the plugin can start failing with Bad 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
0
likes
0
points
783
downloads

Documentation

Documentation

Publisher

unverified uploader

Weekly Downloads

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.

Homepage
Repository (GitHub)
View/report issues

Topics

#lint #di #ioc #dependency-injection #static-analysis

License

unknown (license)

Dependencies

analysis_server_plugin, analyzer, analyzer_plugin

More

Packages that depend on cherrypick_lint