Перейти к содержимому

Линтинг

cherrypick_lint — это плагин анализатора, который подсвечивает неверное использование API CherryPick в IDE и в dart analyze — без build_runner. На этой странице показано, что ловит каждое правило (пример «плохо → хорошо»), и как подключить и настроить плагин.

Плагин не является зависимостью проекта — analysis server резолвит его сам. Достаточно назвать его в top-level секции plugins файла analysis_options.yaml:

analysis_options.yaml
plugins:
cherrypick_lint: ^4.0.0

Требуется Dart >=3.10 (Flutter >=3.38).

Пакет опубликован на pub.dev. Чтобы попробовать ещё не выпущенное изменение, укажите плагину путь к локальной копии репозитория:

analysis_options.yaml
plugins:
cherrypick_lint:
path: /absolute/path/to/cherrypick/cherrypick_lint

Секция plugins принимает только три формы: версионный констрейнт, констрейнт вместе с адресом hosted-сервера и путь.

После этого перезапустите Dart Analysis Server (в VS Code: Dart: Restart Analysis Server) — плагины анализатора подхватываются только при старте. Дальше правила видны и в IDE, и в dart analyze / flutter analyze, так что отдельного шага в CI не нужно.

Плагин не зависит от cherrypick — он только читает ваш код, поэтому включить его можно на любой версии. Различается другое: верно ли утверждение каждого правила для того API, который у вас реально есть. Это проверено запуском плагина на файле, нарушающем все правила, и выполнением каждого заявленного рантайм-поведения на cherrypick 2.2.0, 3.0.0, 3.0.2 и 4.0.0-dev.6.

cherrypick Какие правила применимы
4.x Все 15.
3.x (проверено: 3.0.0, 3.0.2) 14 из 15. Кроме avoid_extends_silent_observer: fast-path, о котором оно предупреждает, есть только в 4.x. Там правило стоит отключить.
2.x и старше Не поддерживается. closeScope и closeSubScope — синхронные void, а Scope.dispose() не существует, поэтому await-правила ругаются на вызовы, которым нечего ждать, а их quick fix даёт ошибку use_of_void_result. avoid_resolve_in_to_instance и avoid_singleton_on_provide_with_params описывают поведение, которого в 2.x нет.

Берите ту же мажорную версию cherrypick_annotations и cherrypick_generator.

Пропущенный await на закрытии скоупа означает, что ресурсы могут быть ещё не освобождены к следующей строке кода. Оборачивание вызова в unawaited(...) считается осознанным fire-and-forget и не вызывает срабатывание этих правил.

// ❌ avoid_unawaited_close_sub_scope
scope.closeSubScope('feature');
// ✅
await scope.closeSubScope('feature');
// ❌ avoid_unawaited_close_scope
CherryPick.closeScope(scopeName: 'feature');
// ✅
await CherryPick.closeScope(scopeName: 'feature');
// ❌ avoid_unawaited_scope_dispose
scope.dispose();
// ✅
await scope.dispose();

Те же классы ошибок, на которых AnnotationValidator генератора бросает исключение во время сборки — только теперь они видны в IDE ещё до запуска генератора.

moduleBuilder — это PartBuilder, и part-директива задаёт файл, в который пишется сгенерированный класс. Без неё сборка проходит успешно и не создаёт ничего, предупредив лишь в логе build_runner.

// ❌ module_requires_part_directive — кодогенерация ничего не пишет
@module()
abstract class AppModule extends Module {
@provide()
Api api() => Api();
}
// ✅
part 'app_module.module.cherrypick.g.dart';
@module()
abstract class AppModule extends Module {
@provide()
Api api() => Api();
}

Генерируемый part — это final class $AppModule extends AppModule, тело builder() в нём состоит из вызовов bind<T>(). Оба члена объявлены в Module, поэтому без наследования генератор выдаёт part, который не компилируется.

// ❌ module_must_extend_module — сгенерированный part не скомпилируется
@module()
abstract class AppModule {
@provide()
Api api() => Api();
}
// ✅
@module()
abstract class AppModule extends Module {
@provide()
Api api() => Api();
}

Сам генератор модификатор не проверяет, но конкретный @module-класс тупиковый в любом случае: Module.builder абстрактный, поэтому без переопределения класс отвергает Dart, а с переопределением генератор отвергает builder как метод без @provide и @instance.

// ❌ module_must_be_abstract
@module()
class AppModule extends Module {
@provide()
Api api() => Api();
}
// ✅
@module()
abstract class AppModule extends Module {
@provide()
Api api() => Api();
}

Кодогенерация валидирует каждый неабстрактный метод класса, включая приватные и static. Исключение — только геттеры и сеттеры: они не входят в ClassElement.methods.

@module()
abstract class AppModule extends Module {
// ❌ module_method_missing_binding — нет @provide/@instance
Api api() => Api();
// ❌ module_method_missing_binding — приватные тоже валидируются
String _token() => 'secret';
// ✅
@provide()
Api api() => Api();
}
class ProfileScreen with _$ProfileScreen {
// ❌ inject_field_must_be_late_final
@inject()
UserManager manager;
// ✅
@inject()
late final UserManager manager;
}
// ❌ named_value_must_not_be_empty
@named('')
ApiClient mockApi() => MockApiClient();
// ✅
@named('mock')
ApiClient mockApi() => MockApiClient();
@module()
abstract class FeatureModule {
// ❌ params_requires_provide
@params()
UserManager createManager(Map<String, dynamic> args) => ...;
// ✅
@provide()
@params()
UserManager createManager(Map<String, dynamic> args) => ...;
}

Ловушки, которые проявляются только в рантайме — cherrypick_generator их не видит, потому что это не неверное использование аннотаций.

В cherrypick 4.x Scope содержит fast-path if (_observer is SilentCherryPickObserver), поэтому наследник через extends молча не получает ни одного из 14 колбэков наблюдателя.

// ❌ avoid_extends_silent_observer
class MyObserver extends SilentCherryPickObserver {}
// ✅
class MyObserver implements CherryPickObserver {
// ... реализовать все 14 методов
}

Согласно doc-комментарию Binding.singleton(), вызов после .toInstance()/.toInstanceAsync() не имеет эффекта — переданное значение уже единственный константный экземпляр. .singleton() осмыслен только после провайдера.

// ℹ️ avoid_redundant_singleton_on_instance
bind<Api>().toInstance(ApiMock()).singleton();
// ✅
bind<Api>().toInstance(ApiMock());
// либо, если действительно нужно ленивое создание единственного экземпляра:
bind<Api>().toProvide(() => ApiMock()).singleton();

.singleton() после .toProvideWithParams()/.toProvideAsyncWithParams() превращает биндинг в «master singleton»: параметры учитываются только при самом первом resolve<T>(params: ...), все последующие resolve возвращают тот же закэшированный экземпляр независимо от params. Иногда это именно то, что нужно, поэтому у правила нет quick fix — только напоминание проверить намерение.

// ℹ️ avoid_singleton_on_provide_with_params
bind<Service>().toProvideWithParams((params) => Service(params)).singleton();
// нормально, если нужен новый экземпляр на каждый набор params — просто уберите .singleton()
bind<Service>().toProvideWithParams((params) => Service(params));

.toInstance(...)-биндинги внутри Module.builder применяются последовательно, поэтому вызов scope.resolve<T>() (или resolveAsync/tryResolve/tryResolveAsync) для построения значения может бросить Can't resolve dependency ..., если T регистрируется позже в том же builder’е. Отложите резолв через .toProvide(() => ...) — он выполнится лениво, когда все соседние биндинги уже зарегистрированы.

// ❌ avoid_resolve_in_to_instance
bind<int>().toInstance(scope.resolve<String>().length);
// ✅
bind<int>().toProvide(() => scope.resolve<String>().length);

Замыкание провайдера существует для того, чтобы выполняться заново при каждом resolve<T>() — значение должно строиться внутри него. Если замыкание просто возвращает переменную, построенную ранее в том же методе, значение на самом деле создаётся один раз, в момент Module.builder(), и каждый resolve<T>() молча возвращает тот же экземпляр — непреднамеренный псевдо-singleton в обход явного .singleton(). На .toInstance(...) это не влияет: он всегда конструирует значение сразу независимо от того, откуда оно взялось, поэтому предвычисление для него безопасно.

// ❌ avoid_precomputed_value_in_provide
final api = ApiMock();
bind<Api>().toProvide(() => api);
// ✅
bind<Api>().toProvide(() => ApiMock());
analysis_options.yaml
plugins:
cherrypick_lint:
version: ^4.0.0
diagnostics:
avoid_extends_silent_observer: false

Отдельную строку или файл можно исключить комментарием в форме <плагин>/<правило>:

// ignore: cherrypick_lint/avoid_unawaited_scope_dispose
scope.dispose();