kx_lints 0.0.3
kx_lints: ^0.0.3 copied to clipboard
Opinionated Flutter lint rules that catch real bugs via custom_lint — file length, widget structure, theme access, magic numbers, hardcoded strings, and more. Configurable per-rule thresholds, quick-f [...]
kx_lints #
Opinionated, configurable Flutter lint rules that catch real bugs — not style bikeshedding.
Install #
# pubspec.yaml
dev_dependencies:
custom_lint: ^0.8.0
kx_lints: ^0.0.1
# analysis_options.yaml
analyzer:
plugins:
- custom_lint
Rules #
| Rule | Severity | Fix | Description |
|---|---|---|---|
file_length |
ERROR | — | File exceeds line limit (default 400) |
one_widget_per_file |
warn | — | Only one widget class per file |
screen_class_suffix |
warn | ✓ | Screen classes use Screen suffix, not Page |
callback_present_tense |
warn | — | Callbacks use present tense (onPress, not onPressed) |
no_theme_of |
warn | ✓ | Use context.theme instead of Theme.of(context) |
no_text_theme_access |
warn | ✓ | Use context.theme.typography instead of .textTheme |
no_color_scheme_access |
warn | ✓ | Use context.theme.colors instead of .colorScheme |
no_material_colors_constant |
warn | — | No Colors.red — use semantic color tokens |
no_raw_alpha_integer |
warn | ✓ | withValues(alpha:) expects 0.0–1.0, not 0–255 |
late_controllers_not_final |
warn | ✓ | Controllers in State: late, not late final |
prefer_geometry_types |
warn | ✓ | Widget APIs use EdgeInsetsGeometry over EdgeInsets |
no_magic_numbers |
warn | ✓ | No raw numbers in widget sizing params |
no_hardcoded_strings |
warn | — | No hardcoded user-visible strings |
Configuration #
Disable a rule or tune thresholds in analysis_options.yaml:
custom_lint:
rules:
- file_length: false # disable entirely
- callback_present_tense: false
- no_magic_numbers:
allowed_values: [0, 1, 2, -1]
Rule Details #
file_length — file exceeds line limit
Files over 400 lines are hard to navigate and review. Split into smaller, focused files.
// ✗ BAD — 500-line file
class MegaWidget extends StatelessWidget { /* ... 500 lines ... */ }
// ✓ GOOD — split into focused files
// mega_widget.dart
// mega_widget_header.dart
// mega_widget_body.dart
Configurable: max_lines (default 400).
one_widget_per_file — one widget class per file
Multiple widgets in one file make them hard to find and test independently.
// ✗ BAD
class ProfileHeader extends StatelessWidget { ... }
class ProfileBody extends StatelessWidget { ... } // ← flagged
// ✓ GOOD — each widget in its own file
State subclasses are excluded — they belong with their StatefulWidget.
screen_class_suffix — use Screen, not Page
Consistent naming across the codebase.
// ✗ BAD
class HomePage extends StatelessWidget { ... }
// ✓ GOOD
class HomeScreen extends StatelessWidget { ... }
callback_present_tense — callbacks use present tense
Flutter SDK uses past tense (onPressed), but present tense is shorter and reads as intent, not event.
// ✗ BAD
final VoidCallback? onPressed;
final ValueChanged<String>? onChanged;
// ✓ GOOD
final VoidCallback? onPress;
final ValueChanged<String>? onChange;
no_theme_of — use context.theme
Extension method is shorter, cacheable, and reads better.
// ✗ BAD
final theme = Theme.of(context);
// ✓ GOOD
final theme = context.theme;
no_text_theme_access — use context.theme.typography
// ✗ BAD
Theme.of(context).textTheme.headlineLarge
// ✓ GOOD
context.theme.typography.headlineLarge
no_color_scheme_access — use context.theme.colors
// ✗ BAD
Theme.of(context).colorScheme.primary
// ✓ GOOD
context.theme.colors.primary
no_material_colors_constant — no Material color palette
Material palette colors don't adapt to themes. Use semantic tokens or explicit hex values.
// ✗ BAD
color: Colors.red
// ✓ GOOD
color: context.theme.colors.error
color: const Color(0xFFE53935)
no_raw_alpha_integer — alpha expects 0.0–1.0
Color.withValues(alpha:) takes a normalized double. Passing an 8-bit int (e.g. 160) is a silent bug — it clamps to 1.0.
// ✗ BAD — looks like 63% opacity, actually 100%
color.withValues(alpha: 160)
// ✓ GOOD
color.withValues(alpha: 0.63)
late_controllers_not_final — controllers should be reassignable
Controllers in State subclasses may need reassignment in didUpdateWidget. late final prevents that.
// ✗ BAD
late final TextEditingController _controller;
// ✓ GOOD
late TextEditingController _controller;
prefer_geometry_types — use abstract geometry types on widget APIs
Concrete types like EdgeInsets break RTL support. Use their Geometry supertypes on public APIs.
// ✗ BAD
class MyWidget extends StatelessWidget {
final EdgeInsets padding; // ← won't accept EdgeInsetsDirectional
}
// ✓ GOOD
class MyWidget extends StatelessWidget {
final EdgeInsetsGeometry padding;
}
no_magic_numbers — extract sizing constants
Raw numbers in widget build methods obscure intent and make global changes impossible.
// ✗ BAD
padding: EdgeInsets.all(16),
SizedBox(height: 24),
// ✓ GOOD
padding: EdgeInsets.all(Spacing.md),
SizedBox(height: Spacing.lg),
Scoped to build methods and sizing-related named parameters only. Values 0, 1, 2, -1, 0.0, 1.0, 0.5 are allowed.
no_hardcoded_strings — use localized strings
Hardcoded user-visible strings can't be translated and are scattered across the codebase.
// ✗ BAD
Text('Welcome back')
TextField(decoration: InputDecoration(hintText: 'Enter email'))
// ✓ GOOD
Text(context.l10n.welcomeBack)
TextField(decoration: InputDecoration(hintText: context.l10n.emailHint))
Flagged params: Text() positional args, label, hint, hintText, labelText, title, subtitle, tooltip, semanticsLabel, errorText, helperText, prefixText, suffixText, message, placeholder, description, counterText.
Excluded: key, debugLabel, restorationId, heroTag, routeName, fontFamily, package, name, asset paths.
License #
MIT