DART-RUN-STATIC-ANALYSIS

Analysis Configuration
Diagnostic Suppression Rules
Workflow: Running Static Analysis
Workflow: Applying Automated Code Fixes
Examples

Analysis Configuration

Enforce strict formatting, stylistic cleanliness, and code sanity by configuring analysis_options.yaml in the root of your Dart package:

Inheriting Lints: Inherit a baseline recommended rule set using the include directive. Prefer package:lints/recommended.yaml for pure Dart packages or package:flutter_lints/flutter.yaml for Flutter applications.
Strict Type Checking: Explicitly declare strict static types under the analyzer: language: configuration to eliminate unsafe dynamic types:
```
analyzer:
  language:
    strict-casts: true
    strict-inference: true
    strict-raw-types: true
```
Linter Rules Customization: Customize specific rules under linter: rules:. Use a map key structure (rule_name: true/false) to explicitly activate or deactivate rules when overriding an inherited configuration.
Auto-Formatting Options: Declare formatter parameters under the formatter: node (e.g. configuring page_width: 80).

Diagnostic Suppression Rules

When an analyzer warning or style lint yields a false positive or hits generated files, suppress the warning explicitly using one of these strategies:

Exclusion Filters: Exclude entire files or directory trees (such as JSON generated models or internationalization files) from analysis under the analyzer: exclude: list using standard glob patterns:
```
analyzer:
  exclude:
    - "lib/generated/**"
    - "**/*.g.dart"
```
File-Level Suppressions: Add // ignore_for_file: diagnostic_name on a dedicated line at the absolute top of the Dart file to disable specific rules across the entire file context.
Line-Level Suppressions: Add // ignore: diagnostic_name on the line directly preceding the target statement, or appended at the end of the matching line.
Pubspec Suppressions: Suppress package dependency warnings within the pubspec.yaml by injecting comments (e.g. # ignore: sort_pub_dependencies).

Workflow: Running Static Analysis

Follow this checklist to perform static code auditing:

[ ] Establish analysis config: Ensure analysis_options.yaml exists at the project root.
[ ] Run analysis: Run the analyzer from the terminal:
```
dart analyze .
```
[ ] Escalate infos to fatal: In CI/CD pipelines, ensure informational lints fail the build by appending the fatal flag:
```
dart analyze . --fatal-infos
```
[ ] Triage diagnostics: Review warnings, correcting type hierarchies or unused variables, or applying suppressions where appropriate.

Workflow: Applying Automated Code Fixes

Follow this checklist to apply mechanical quick-fixes automatically:

[ ] Verify lints: Confirm that the target linter rules are enabled in analysis_options.yaml.
[ ] Dry run check: Run a dry run to inspect proposed mechanical modifications:
```
dart fix --dry-run
```
[ ] Apply fixes: Apply the quick-fixes directly across the workspace:
```
dart fix --apply
```
[ ] Format code: Format the modified code files:
```
dart format .
```
[ ] Re-run analysis: Confirm that dart analyze reports clean results.

Examples

Comprehensive `analysis_options.yaml` Template

include: package:lints/recommended.yaml

analyzer:
  exclude:
    - "lib/generated/**"
    - "**/*.g.dart"
    - "**/*.freezed.dart"
  language:
    strict-casts: true
    strict-inference: true
    strict-raw-types: true
  errors:
    todo: ignore
    missing_required_param: error
    missing_return: error

linter:
  rules:
    always_declare_return_types: true
    avoid_empty_else: true
    prefer_const_constructors: true
    sort_pub_dependencies: false

formatter:
  page_width: 100
  trailing_commas: preserve

Inline Suppression Techniques

// 1. Suppress all instances of unused variables inside this specific file
// ignore_for_file: unused_local_variable

void calculateMetrics() {
  // 2. Suppress a single line using a preceding comment ignore
  // ignore: invalid_assignment
  int x = 'not_an_int';

  final unusedString = 'value'; // File-level ignore handles this
  
  // 3. Suppress at the end of the line
  final double pi = 3.14; // ignore: constant_identifier_names
}

Contents