dependency-hygiene

Dependency hygiene

Every dependency is a permanent liability someone else may have to service. Optimise for resolves and builds years from now, not for latest. This skill governs pubspec/lock mechanics, the gate a new package must pass, and the escape hatch when a critical package rots.

Read the reference for the task at hand:

• references/dependency-gate-and-audit.md — the refuse/accept gate, transitive auditing, licence recording, upgrade discipline.
• references/sdk-pin-and-lint-include.md — recording the SDK version and the silent-lint-disable trap on any SDK bump.
• references/vendoring-behind-an-interface.md — vendoring a bus-factor-1 native plugin into third_party/ without touching lib/.

Run scripts/audit-deps.sh before a PR that changes pubspec.yaml.

Non-negotiable rules

1. Caret ranges in pubspec.yaml, exact pins only in pubspec.lock. drift: ^2.31.0, never drift: 2.31.0. The lock pins; ranges only keep resolution solvable. Exact pins in a pubspec manufacture unsolvable conflicts on the next SDK bump and buy nothing the lock is not already delivering.
2. Commit pubspec.lock. This is an application, not a package — the asymmetry that flips the rule. The default Dart .gitignore template lists pubspec.lock; delete that line. The committed lock is the only thing that makes a stranger's git clone resolve the exact versions that were tested on a real device.
3. A pubspec.yaml diff without its pubspec.lock delta is incomplete. Run flutter pub get and stage the lock in the same commit — add, upgrade, and remove alike.
4. Record the SDK version separately from the tool. Keep environment: sdk: a real range so pub can solve; pin the exact tested Flutter version in a committed record CI reads (see reference). The record is what a stranger and CI read; do not confuse a version-manager tool with the file.
5. The lint include filename is coupled to the resolved SDK. A version-pinned include: that names a file absent from the resolved linter package emits include_file_not_found — fatal to default dart analyze/flutter analyze, so standard CI catches it. It only goes silent-and-green where warnings are made non-fatal, and even then it is your ruleset's added/promoted rules that stop applying, not the analyzer's built-ins. Verify it after any SDK bump (see reference).
6. Audit the transitive tree before adding, not the pubspec. The second hop is exactly where a banned SDK arrives. Run scripts/audit-deps.sh (or dart pub deps --json + the audit script) before committing a new dependency.
7. Refuse by policy anything that opens a network path, reports crashes/usage, drags in a telemetry core, or collects device identifiers for an unshipped feature — directly or transitively. Green CI is not evidence a native capability works. See the gate reference.
8. Grep lib/ after removing a dependency. A package deleted from pubspec.yaml but still transitively resolvable keeps compiling today and breaks on the clone that matters. The analyzer catches an unresolved import, not one that resolves by accident.
9. Wrap a bus-factor-1 native plugin behind an interface now, vendor later. The interface is cheap insurance; pre-emptive vendoring is a maintenance burden against a break that has not happened. See the vendoring reference.