dart-tooling

Dart Tooling & Package Workflows

Contents

• Static Analysis Resolution
• Resolving Package Conflicts
• Migrating Tests to package:checks

Static Analysis Resolution

Use this sequential workflow to identify, fix, and verify static analysis errors in a Dart project.

1. Run Static Analyzer: dart analyze . --fatal-infos
2. Apply Automated Fixes:
   • dart fix --dry-run
   • dart fix --apply
3. Resolve Manually: Address Type Mismatches, Null Safety, or Invalid Overrides that dart fix couldn't automatically resolve.
4. Performance Diagnostics: Utilize the Analysis Server diagnostics page (available at http://localhost:8082 when analyzer runs) to trace and diagnose slow analysis times.
5. Verify: Ensure both dart analyze . and dart test pass.

Resolving Package Conflicts

When pub get fails due to incompatible package versions, use this systematic approach.

Understanding dart pub outdated

Column	Meaning
Current	Version in pubspec.lock right now
Upgradable	Latest version allowed by pubspec.yaml constraints
Resolvable	Latest version that CAN be resolved with all other deps
Latest	Latest published version (ignoring constraints)

dart pub outdated

Git LFS Support

Introduced in Dart 3.12

• The dart pub package management command natively supports Git Large File Storage (LFS). Dependencies fetched from Git repositories that contain LFS objects (e.g. assets, binaries, models) resolve automatically without requiring local configuration.

Version Constraint Best Practices

• Use Caret Syntax: Always use ^1.2.3 - allows non-breaking updates up to next major version.
• Tighten Dev Dependencies: Set lower bounds to exact current version for dev_dependencies.
• CI Reproducibility: Use dart pub get --enforce-lockfile in CI to ensure exact tested versions.

Upgrading Dependencies

If updating to "Upgradable" versions:

dart pub upgrade
dart pub upgrade --tighten  # Auto-update lower bounds in pubspec.yaml

If updating to "Resolvable" versions (major):

1. Manually edit pubspec.yaml to bump constraints.
2. Run dart pub upgrade.
3. Run dart analyze → fix breaking API changes.
4. Run dart test → fix regressions.

Surgical Lockfile Removal

NEVER delete the entire pubspec.lock. This causes uncontrolled upgrades across the dependency graph.

Instead, remove ONLY the conflicting package's block:

1. Open pubspec.lock.
2. Find and delete ONLY the conflicting package's YAML block.
3. Run dart pub get: fetches newest compatible version for that package only.
4. Verify: dart pub deps → check dependency graph resolves correctly.

Temporary Overrides (Last Resort)

dependency_overrides:
  shared_package: ^x.y.z  # Remove once direct deps support newer version

Migrating Tests to package:checks

Transition test assertions from the package:matcher syntax to the literate API provided by package:checks for more readable output.

• Dependency: Add dev_dependency checks via dart pub add dev:checks.
• Basic Equality: Replace expect(actual, equals(expected)) with check(actual).equals(expected).
• Type Checking: Replace expect(actual, isA<Type>()) with check(actual).isA<Type>().
• Asynchronous Expectations:
  • await check(Future.value(10)).completes((it) => it.equals(10));
• Workflow:
  1. Add package:checks and import package:checks/checks.dart.
  2. Rewrite expect() calls to check().
  3. Run static analyzer and tests to verify.