Skip to main content

cherrypick_lint 1.1.0 copy "cherrypick_lint: ^1.1.0" to clipboard
cherrypick_lint: ^1.1.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.

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: ^1.1.0

Not on pub.dev yet. The version-constraint form above starts working once the package is published; until then point the plugin at a local checkout of this repository:

# 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 —

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 always what you want instead.

.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: ^1.1.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.

Versions 0.1.x were built on custom_lint, whose repository is archived and which its author no longer publishes; 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: ^1.0.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
160
points
783
downloads

Documentation

Documentation
API reference

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

Apache-2.0 (license)

Dependencies

analysis_server_plugin, analyzer, analyzer_plugin

More

Packages that depend on cherrypick_lint