CLAUDE.md

Many Lints - Project Context

Custom Dart linter package for Flutter projects, built on analysis_server_plugin. Provides lint rules, fixes, and assists that integrate directly with dart analyze and IDEs.

Commands

dart pub get              # Install dependencies
dart test                 # Run tests
dart analyze              # Verify lints work
dart format .             # Format code

Project Structure

lib/
  main.dart               # Re-exports many_lints.dart for analysis_server_plugin discovery
  many_lints.dart         # Plugin entry point - registers all rules, fixes, and assists
  src/
    type_checker.dart     # Type matching utilities for analyzer
    type_inference.dart   # Context type inference utilities
    class_suffix_validator.dart # Base class for suffix naming rules
    text_distance.dart    # String distance utilities (Levenshtein)
    hook_detection.dart   # Hook widget detection helpers
    ast_node_analysis.dart # AST node analysis helpers
    constant_expression.dart # Constant expression/identifier checking helpers
    disposal_utils.dart   # Shared disposal helpers (findCleanupMethod, cleanupMethods)
    flutter_widget_helpers.dart # Flutter widget helpers (FlexAxis enum)
    riverpod_type_checkers.dart # Shared Riverpod TypeChecker constants
    async_guard_utils.dart # Async helpers (containsAwait, isMountedGuardWithReturn)
    rules/                # Lint rules (AnalysisRule + SimpleAstVisitor pattern)
    fixes/                # Quick fixes (ResolvedCorrectionProducer pattern)
    assists/              # Code assists (ResolvedCorrectionProducer pattern)
test/
  *.dart                  # Test files (analyzer_testing pattern)
docs/                     # Astro Starlight docs site (see docs/CLAUDE.md)

Reference Docs

Before writing any code:

1. Read these reference docs to understand the framework:
   • Writing a plugin
   • Writing rules
   • Testing rules
   • Writing assists

Adding a New Lint Rule

Use the /new-lint skill for step-by-step guidance, or /release to prepare a new version. See the full cookbooks:

• Rules patterns - Rule structure, type checking, AST, visitors, reporting
• Rules recipes - Copy-paste recipes for common patterns
• Fixes cookbook - Quick fix implementation patterns
• Assists cookbook - Code assist implementation patterns

Quick summary:

1. Create lib/src/rules/<rule_name>.dart
2. Extend AnalysisRule, define a static LintCode with name, problemMessage, correctionMessage
3. Implement registerNodeProcessors() to register visitors via RuleVisitorRegistry
4. Create _Visitor extending SimpleAstVisitor, report issues with rule.reportAtNode()
5. Register the rule in lib/many_lints.dart via registry.registerWarningRule()
6. Optionally create a fix in lib/src/fixes/ extending ResolvedCorrectionProducer
7. Create test/<rule_name>_test.dart using analyzer_testing patterns
8. Create a documentation page in docs/src/content/docs/docs/rules/<category>/
9. Create example/lib/<lint_name>_example.dart with bad/good/edge-case examples

Code Conventions

• Language: English only (code, comments, commits)
• Lint names: snake_case (use_cubit_suffix, prefer_align_over_container)
• Rule classes: PascalCase (UseCubitSuffix, PreferCenterOverAlign)
• Fix classes: PascalCase with Fix suffix (PreferCenterOverAlignFix)
• Type checking: Use TypeChecker.fromName() or TypeChecker.fromUrl()
• Pattern matching: Dart 3.0+ patterns for AST analysis
• SDK: Dart ^3.10.0, analyzer ^11.0.0

Key Helpers

📂 Quick References (For Understanding Existing Code)

• lib/src/rules/CLAUDE.md - Lint rules quick reference
• lib/src/fixes/CLAUDE.md - Quick fixes quick reference
• lib/src/assists/CLAUDE.md - Code assists quick reference

🔧 Utility Files

• lib/src/type_checker.dart - Type matching utilities
• lib/src/type_inference.dart - Context type inference (inferContextType, resolveReturnType, etc.)
• lib/src/class_suffix_validator.dart - Base class for suffix naming rules
• lib/src/text_distance.dart - Levenshtein edit distance
• lib/src/hook_detection.dart - Hook widget detection helpers
• lib/src/ast_node_analysis.dart - AST node analysis helpers (enclosingClassDeclaration, hasOverrideAnnotation, negateExpression, buildEveryReplacement)
• lib/src/constant_expression.dart - Constant expression and identifier checking (isConstantExpression, isConstantIdentifier)
• lib/src/disposal_utils.dart - Shared disposal helpers (findCleanupMethod, cleanupMethods)
• lib/src/flutter_widget_helpers.dart - Flutter widget helpers (FlexAxis enum for spacing rules)
• lib/src/riverpod_type_checkers.dart - Shared Riverpod TypeChecker constants (notifierChecker)
• lib/src/async_guard_utils.dart - Async helpers (containsAwait, isMountedGuardWithReturn)