essential_lints_annotations

This package provides annotations that configure lint rules from the essential_lints package. These annotations help Dart/Flutter developers define custom lint behavior for their codebases.

Features

This package includes the following annotations:

  • GettersInMemberList - Ensures that getters and fields are included in a specified member list (useful for ensuring completeness of introspection lists)
  • SubtypeAnnotating - Requires specific annotations on subtypes of an annotated class, mixin, enum, or extension type
  • SubtypeNaming - Enforces naming conventions (prefix, suffix, or containing pattern) for subtypes of an annotated type

Getting started

Add essential_lints_annotations to your analysis_options.yaml plugins:

dependencies:
  essential_lints_annotations: ^0.1.1

Ensure you have the essential_lints package configured in your analysis_options.yaml to enable these lint rules.

Usage

GettersInMemberList

Use this annotation to ensure that all relevant getters and fields of a class are included in a specific member list. This is useful for classes that need introspection capabilities or validation of their members.

import 'package:essential_lints_annotations/essential_lints_annotations.dart';

@GettersInMemberList(memberListName: 'members')
class Person {
  Person(this.name, this.age);

  final String name;
  final int age;

  // The lint will warn if 'name' or 'age' are not included in this list
  List<Object?> get members => [name, age];
}

You can customize the behavior with optional parameters:

// Only check fields, not getters
@GettersInMemberList(memberListName: 'members', getters: false)
class MyClass { ... }

// Only check getters, not fields
@GettersInMemberList(memberListName: 'members', fields: false)
class MyClass { ... }

// Only check members that are subtypes of `int`
@GettersInMemberList(
  memberListName: 'members',
  superTypes: [th<int>()],
)
class MyClass { ... }

// Only check members with specific exact types
@GettersInMemberList(
  memberListName: 'members',
  types: [th<String>(), th<int>()],
)
class MyClass { ... }

Note: Use the th<T>() type alias (short for TypeHolder) to specify types in the annotation parameters.

SubtypeAnnotating

Use this annotation to enforce that all subtypes of a class, mixin, enum, or extension type have specific annotations applied.

import 'package:essential_lints_annotations/essential_lints_annotations.dart';

@SubtypeAnnotating(annotations: [Deprecated])
abstract class BaseService {
  void execute();
}

// This will trigger a warning - missing @Deprecated annotation
class UserService extends BaseService {
  @override
  void execute() {}
}

// This is correct
@Deprecated('Use NewService instead')
class PaymentService extends BaseService {
  @override
  void execute() {}
}

You can require multiple annotations:

const experimental = 'experimental';

@SubtypeAnnotating(annotations: [Deprecated, experimental])
abstract class ExperimentalApi {}

Use the onlyConcrete parameter to only enforce the rule on concrete (non-abstract) subtypes:

@SubtypeAnnotating(
  annotations: [Deprecated],
  onlyConcrete: true,
)
abstract class BaseClass {}

// No warning - abstract class is allowed without the annotation
abstract class IntermediateClass extends BaseClass {}

// Warning - concrete class must have @Deprecated
class ConcreteClass extends BaseClass {}

SubtypeNaming

Use this annotation to enforce naming conventions on all subtypes of a class, mixin, enum, or extension type.

import 'package:essential_lints_annotations/essential_lints_annotations.dart';

// Require 'I' prefix for all subtypes (interface naming convention)
@SubtypeNaming(prefix: 'I')
abstract class Interface {}

class IUserRepository extends Interface {} // ✓ Correct
class UserRepository extends Interface {}  // ✗ Missing 'I' prefix

// Require 'Service' suffix
@SubtypeNaming(suffix: 'Service')
abstract class BaseService {}

class UserService extends BaseService {}      // ✓ Correct
class PaymentHandler extends BaseService {}   // ✗ Missing 'Service' suffix

// Require name contains 'Repository'
@SubtypeNaming(containing: 'Repository')
abstract class DataAccess {}

class UserRepositoryImpl extends DataAccess {}    // ✓ Correct
class UserDao extends DataAccess {}           // ✗ Doesn't contain 'Repository'

// Combine multiple requirements
@SubtypeNaming(prefix: 'My', suffix: 'Class')
abstract class Base {}

class MyCustomClass extends Base {}           // ✓ Correct
class MyCustom extends Base {}                // ✗ Missing 'Class' suffix
class CustomClass extends Base {}             // ✗ Missing 'My' prefix

Use the onlyConcrete parameter to only enforce naming on concrete (non-abstract) subtypes:

@SubtypeNaming(prefix: 'I', onlyConcrete: true)
abstract class Interface {}

abstract class BaseImplementation extends Interface {} // ✓ Allowed
class IUserRepository extends Interface {}             // ✓ Correct
class UserRepository extends Interface {}              // ✗ Missing 'I' prefix

Additional information

Contributing

Contributions are welcome! Please file issues and pull requests on the GitHub repository.

Issues and Support

If you encounter any issues or have questions, please file them in the issue tracker.

License

This package is licensed under the MIT License. See the LICENSE file for details.

Libraries

essential_lints_annotations