team_guard 1.0.9

Custom lint plugin to block forbidden Flutter widgets across team projects.

Team Guard

A custom lint plugin for Dart and Flutter that helps teams enforce UI rules by blocking specific widgets/classes and suggesting approved replacements.

Features

• Integrates with custom_lint for live IDE feedback.
• Supports configurable restrictions for both widgets and classes.
• Supports warning and error severities per rule.
• Provides quick-fix suggestions with replacement names/imports.

Prerequisites

• Dart SDK >=3.0.0 <4.0.0
• IDE plugin:
  • VS Code: Custom Lint
  • Android Studio / IntelliJ: Custom Lint

Installation

Add dependencies to your app's pubspec.yaml:

dev_dependencies:
  team_guard: ^1.0.9

Then run:

# Flutter project
flutter pub get

# Dart project
dart pub get

Setup (Required)

1. Initialize Team Guard in your project root:

dart run team_guard:init

This command:

• generates team_guard.yaml automatically in the project root (if missing)
• creates analysis_options.yaml if missing
• adds custom_lint plugin under analyzer.plugins if missing
• generates missing replacement files in lib/core based on team_guard.yaml

2. Run the linter:

dart run custom_lint

custom_lint is included transitively by team_guard, so the command is available after pub get.

3. If your IDE still does not show lints, restart analysis server/IDE.

Configuration

After running dart run team_guard:init, you will find team_guard.yaml generated in your project root. Edit it as needed:

widgets:
  Text:
    replacement: CustomText
    # import: package:your_app/widgets/custom_text.dart
    severity: error

  GestureDetector:
    replacement: AppGestureDetector
    severity: error

classes:
  Colors:
    replacement: AppColors
    # import: package:your_app/theme/app_colors.dart
    severity: error

Full setup example: example/team_guard_example.dart

When you run dart run team_guard:init, replacement stubs are created automatically in lib/core (for example, CustomText -> lib/core/custom_text.dart) if the files do not already exist.

Import Field Format

import in team_guard.yaml is optional.

• If provided, Team Guard uses it directly for quick-fix auto-import.
• If omitted, Team Guard tries to auto-detect the import from your lib/ folder when the replacement class exists in exactly one file.

Correct:

import: package:your_app/widgets/custom_text.dart

or

import: "package:your_app/widgets/custom_text.dart"

Also accepted:

import: "import 'package:your_app/widgets/custom_text.dart';"

Severity Values

• warning
• error

Use error if you want violations to appear as red errors in IDE problems.

Example Violation

If Text is restricted:

Text('Hello');

You will get a lint message suggesting CustomText instead.

Troubleshooting

Lints appear in terminal but not in IDE

1. Confirm analysis_options.yaml contains:

analyzer:
  plugins:
    - custom_lint

2. Install IDE plugin Custom Lint.
3. Restart analysis:
   • VS Code: Dart: Restart Analysis Server
   • Android Studio/IntelliJ: restart IDE
4. Check Problems filter is not set to errors-only if your rules are warning.

team_guard.yaml was not generated

• Run dart run custom_lint from the project root.
• If still missing, create team_guard.yaml manually using the example above.

To Uninstall

flutter pub remove team_guard

Additional Information

• Package: https://pub.dev/packages/team_guard
• custom_lint docs: https://pub.dev/packages/custom_lint
• Issues and contributions: https://github.com/HazemHamdy7/team_guard