apadmi_lints

The Apadmi lint rule set for Dart and Flutter projects, built on top of flutter_lints. It enables a stricter set of additional rules and escalates a number of important lints to analysis errors.

Usage

1. Add apadmi_lints to your dev_dependencies in pubspec.yaml:

   dev_dependencies:
     apadmi_lints: ^3.0.0

2. Include the rule set in your analysis_options.yaml:

   include: package:apadmi_lints/apadmi_lints.yaml

3. Enable the analyzer plugin for the custom rules by adding a top-level plugins section to the root analysis_options.yaml:

   plugins:
     apadmi_lints: ^3.0.0

   Note: the plugins section cannot be inherited through include, so it must be declared in the root analysis_options.yaml of every project — the include line alone does not activate the custom rules.

4. Restart the Dart Analysis Server so your IDE picks up the plugin (VS Code: "Dart: Restart Analysis Server" from the command palette; IntelliJ/Android Studio: the restart icon in the Dart Analysis panel).

Version 3.x requires Dart 3.10 / Flutter 3.38 or newer (in practice a Flutter version whose SDK ships meta 1.18.0 or newer, i.e. Flutter 3.44+). Older projects can stay on apadmi_lints 2.x, which is identical except for the custom rules.

Custom rules

On top of the standard analyzer lints, this package ships its own rules as a native analyzer plugin.

avoid_returning_widgets

Flags helper functions, methods, and getters that return Widget (or a subtype). Returning widgets from helpers hides part of the widget tree from Flutter, hurting rebuild granularity, const-ability, and DevTools inspection. Extract a StatelessWidget subclass instead. Overrides such as build are exempt.

// Bad
Widget _buildHeader() => const Text('header');
Widget get _spacer => const SizedBox(height: 8);

// Good
class _Header extends StatelessWidget {
  const _Header();

  @override
  Widget build(BuildContext context) => const Text('header');
}

See the full rule documentation for do/don't examples, the rationale, and how to suppress or disable the rule.

Known issue: on some Dart SDK versions, dart analyze on the command line prints non-plugin diagnostics twice while a plugin is enabled (dart-lang/sdk#63497, fixed upstream). IDE analysis is unaffected. If the analysis server crashes after changing the plugins section, restart it (VS Code: "Dart: Restart Analysis Server"); if the crash persists, clear the server cache by removing ~/.dartServer.

Formatter settings

The configuration also sets the following formatter options:

• page_width: 120 — lines are formatted to a width of 120 characters.
• trailing_commas: preserve — trailing commas you write are kept as-is.

Additional rules

The following rules are enabled on top of what flutter_lints (and the underlying core and recommended sets from package:lints) already provides. Each rule links to the official Dart documentation, which explains the rule and includes good/bad examples.

• always_declare_return_types
• always_use_package_imports
• avoid_annotating_with_dynamic
• avoid_bool_literals_in_conditional_expressions
• avoid_catching_errors
• avoid_dynamic_calls
• avoid_equals_and_hash_code_on_mutable_classes
• avoid_escaping_inner_quotes
• avoid_field_initializers_in_const_classes
• avoid_implementing_value_types
• avoid_js_rounded_ints
• avoid_null_checks_in_equality_operators
• avoid_private_typedef_functions
• avoid_redundant_argument_values
• avoid_returning_this
• avoid_setters_without_getters
• avoid_slow_async_io
• avoid_type_to_string
• avoid_types_on_closure_parameters
• avoid_unused_constructor_parameters
• avoid_void_async
• cancel_subscriptions
• cascade_invocations
• cast_nullable_to_non_nullable
• close_sinks
• combinators_ordering
• comment_references
• conditional_uri_does_not_exist
• deprecated_consistency
• deprecated_member_use_from_same_package
• directives_ordering
• discarded_futures
• do_not_use_environment
• eol_at_end_of_file
• implicit_reopen
• invalid_case_patterns
• join_return_with_assignment
• leading_newlines_in_multiline_strings
• library_names
• literal_only_boolean_expressions
• matching_super_parameters
• missing_code_block_language_in_doc_comment
• missing_whitespace_between_adjacent_strings
• no_adjacent_strings_in_list
• no_literal_bool_comparisons
• no_runtimeType_toString
• no_self_assignments
• noop_primitive_operations
• omit_local_variable_types
• one_member_abstracts
• only_throw_errors
• package_prefixed_library_names
• parameter_assignments
• prefer_asserts_in_initializer_lists
• prefer_asserts_with_message
• prefer_const_constructors
• prefer_const_declarations
• prefer_const_literals_to_create_immutables
• prefer_constructors_over_static_methods
• prefer_final_in_for_each
• prefer_final_locals
• prefer_foreach
• prefer_int_literals
• prefer_mixin
• prefer_null_aware_method_calls
• prefer_single_quotes
• prefer_void_to_null
• require_trailing_commas
• sized_box_shrink_expand
• sort_pub_dependencies
• sort_unnamed_constructors_first
• test_types_in_equals
• throw_in_finally
• tighten_type_of_initializing_formals
• type_annotate_public_apis
• unawaited_futures
• unnecessary_await_in_return
• unnecessary_breaks
• unnecessary_lambdas
• unnecessary_library_directive
• unnecessary_null_aware_operator_on_extension_on_nullable
• unnecessary_null_checks
• unnecessary_parenthesis
• unnecessary_raw_strings
• unnecessary_statements
• unreachable_from_main
• use_colored_box
• use_decorated_box
• use_enums
• use_if_null_to_convert_nulls_to_bools
• use_is_even_rather_than_modulo
• use_late_for_private_fields_and_variables
• use_named_constants
• use_raw_strings
• use_setters_to_change_properties
• use_string_buffers
• use_test_throws_matchers
• use_to_and_as_if_applicable

Stricter severities

Violations of the following rules are reported as errors instead of the default severity, so they fail analysis outright.

Runtime crashes and wrong results:

• avoid_dynamic_calls
• avoid_web_libraries_in_flutter
• conditional_uri_does_not_exist
• no_logic_in_create_state
• null_check_on_nullable_type_parameter
• null_closures
• use_build_context_synchronously
• valid_regexps

Swallowed exceptions:

• avoid_empty_else
• avoid_void_async
• control_flow_in_finally
• discarded_futures
• throw_in_finally
• unawaited_futures

Leaks:

• cancel_subscriptions
• close_sinks

Always-wrong comparisons, unreachable branches, and no-op statements:

• avoid_types_as_parameter_names
• collection_methods_unrelated_type
• dead_code (analyzer diagnostic)
• exhaustive_cases
• hash_and_equals
• literal_only_boolean_expressions
• no_duplicate_case_values
• no_wildcard_variable_uses
• test_types_in_equals
• unnecessary_statements
• unrelated_type_equality_checks

In addition, the following rules are escalated to warnings — issues to fix before merging, but rarely a crash:

• avoid_print
• avoid_shadowing_type_parameters
• avoid_slow_async_io
• avoid_type_to_string
• avoid_unused_constructor_parameters
• cast_nullable_to_non_nullable
• curly_braces_in_flow_control_structures
• depend_on_referenced_packages
• do_not_use_environment
• empty_statements
• implicit_reopen
• library_private_types_in_public_api
• no_runtimeType_toString
• no_self_assignments
• prefer_is_empty
• prefer_typing_uninitialized_variables
• prefer_void_to_null
• provide_deprecation_message
• recursive_getters
• secure_pubspec_urls
• sort_pub_dependencies
• type_annotate_public_apis
• unreachable_from_main
• use_late_for_private_fields_and_variables
• use_string_buffers

The authoritative list lives in lib/apadmi_lints.yaml under analyzer: errors:.

Excluded files

Analysis is disabled for native folders (android, ios), generated files and assets folders.