very-good-analysis-upgrade

very_good_analysis をアップグレードする

このスキルでは、Dart または Flutter プロジェクトで very_good_analysis を完全にアップグレードする方法を説明します。 目標は、対象を絞ったクリーンな PR です。pubspec.yaml のバージョン更新と、そのバージョンで新たに導入された lint ルールに対応するために必要な最小限のコード変更だけを含めます。

---

基本方針

以下の方針は、すべての very_good_analysis のアップグレードに適用されます。

• キャレットを付ける — very_good_analysis: ^x.y.z と記述します。キャレットは VGV の規約です。 lint のパッチリリースが PR なしで適用されるようになります。正確なバージョン指定を求められた場合は、 その理由を添えてキャレット付きの記述を示します。その理由を説明した後、ユーザーが再度求めた場合に限り、 キャレットのないバージョン指定を記述します。
• PR の対象を絞る — バージョン更新と必要な lint 修正だけを含めます。同じ依頼にまとめられている無関係な依存関係の更新、 コメントの一括整理、一括の dart fix --apply は断り、別の PR に含めるべきだと伝えます。そのうえで、バージョン更新は実行します。
• 新しい警告だけを修正する — 既存の問題は同じ PR で対応しません。
• 依存関係の解決を無理に進めない — 更新後に pub get が失敗した場合は、指示された場合でも、解決のために別の依存関係をアップグレード、緩和、削除しません。競合している両方の制約を示し、判断をユーザーに委ねます。
• 動作変更を避ける — lint の修正で実行時の動作が変わる場合は、レビューが必要であることを伝えます。
• 解析で確認する — 最後に、問題のない flutter analyze または dart analyze の結果を確認します。

---

開始前

作業を進める前に、次の 2 点を確認します。

1. 対象バージョン — ユーザーがバージョン（例：10.0.0）を指定している場合は、対象バージョンとして $ARGUMENTS を使用します。 $ARGUMENTS が空、または文字列 $ARGUMENTS のまま（ホストによって置換されていない）場合は、 pub.dev API から最新バージョンを取得して使用します。質問せず、調べて作業を進めます。

   curl -s https://pub.dev/api/packages/very_good_analysis | jq -r '.latest.version'
   

   変更を加える前に、どのバージョンにアップグレードするかをユーザーに伝えます。

2. プロジェクトの範囲 — 単一パッケージか、モノレポかを確認します。モノレポの場合は、 各サブパッケージの pubspec.yaml にある very_good_analysis の項目を編集します。pubspec.yaml ごとに 1 か所を編集し、 ルートレベルやワークスペースレベルの項目で代用しません。次に、実行場所に応じて 2 つのコマンドを使い分けます。

   • pub get は各パッケージ内で実行します。1 つの pubspec を解決するものであり、他のパッケージも含めてルートから一度に実行することはできません。
   • analyze はリポジトリのルートから 1 回だけ実行します。すべてのパッケージで新たに発生した警告を、一度に確認できます。パッケージごとに解析しないでください。

   パッケージに合ったツールを使います。純粋な Dart パッケージには dart pub get / dart analyze、 Flutter に依存するパッケージには flutter pub get / flutter analyze を使用します。

---

ステップ 1 — pubspec.yaml のバージョンを更新する

プロジェクトの pubspec.yaml ファイルを探します。dev_dependencies の下にある very_good_analysis の項目を更新します。

dev_dependencies:
  very_good_analysis: ^x.y.z # replace x.y.z with the target version

キャレット（^）の接頭辞を付けてください。これは VGV の規約です。ファイル内の他の箇所は変更しません。 他の dev_dependencies の項目、dependencies ブロック、environment 制約はそのままにします。

正確なバージョン指定を求める依頼（「正確に固定して」「キャレット範囲は使いたくない」「pubspec で範囲を指定しないで」）には、 固定指定ではなく、キャレット付きの項目と理由を示して応えます。理由は、lint のみを目的とする開発用依存関係を正確に固定すると、 パッチリリースのたびに個別の PR が必要になり、他のすべての VGV パッケージでもキャレットが使われているためです。

# ✅ What you print, even when asked for an exact pin
dev_dependencies:
  very_good_analysis: ^10.0.0 # caret is the VGV convention — patch lints land without a PR

# ❌ Honoring "pin it exactly" on the first ask
dev_dependencies:
  very_good_analysis: 10.0.0

最初の依頼は、この規約が応えるためにある要望であり、強い主張ではありません。キャレットを使う理由を説明した後、 ユーザーが再度求めた場合に限り、キャレットのないバージョン指定を記述します。

編集後、次を実行します。

flutter pub get

（Flutter を使わない純粋な Dart パッケージの場合は、代わりに dart pub get を使用します。）

接続されていて pub コマンドを公開している場合は、Dart/Flutter MCP サーバーを使用します。それ以外の場合は Bash 経由で実行します。

---

ステップ 2 — flutter analyze を実行する

flutter analyze

Dart のみのパッケージの場合は、こちらを実行してください。

dart analyze

出力全体を記録してください。バージョン更新によって新たに導入された警告やエラー、つまり以前は指摘されなかった Lint を確認します。更新と無関係な既存の問題は無視してください（すでに壊れていたものは修正しないでください。それは別の PR で対応します）。

---

ステップ 3 — Lint 警告を修正する

警告を 1 つずつ確認して対応してください。修正は最小限にとどめ、Lint への準拠のみにしてください。

• flutter analyze で指摘された箇所だけを修正する
• 必要な範囲を超えて、リファクタリング、名前の変更、再構成をしない
• 更新前から存在していた Lint 警告は修正しない
• 警告への対応に動作の変更が必要そうな場合（単なるスタイルの変更ではない場合）は、黙って修正せず、人によるレビューが必要なものとして提示する

flutter analyze を再実行してください。期待される結果は No issues found!、または手を加えていない既存の問題のみです。警告が残る場合は、その一覧を示して、どう進めるかユーザーに確認してください。

---

ステップ 4 — PR を作成する

変更したファイルだけをステージングします。

git add pubspec.yaml pubspec.lock   # always include these
# plus any .dart files you edited for lint fixes

プロジェクトの規約に従い、内容が明確なコミットメッセージでコミットします。既定の例：

chore: upgrade very_good_analysis to x.y.z

Bump very_good_analysis from <old> to <new> and resolve
lint warnings introduced by newly enabled rules.

その後、プッシュして PR を作成します。PR にはほかの変更を含めないでください。機能の追加、無関係なリファクタリング、余分なクリーンアップは行いません。レビュー担当者が、Lint 準拠のみを目的とした更新だとひと目でわかるようにしてください。

プロジェクトに PR テンプレートがある場合は、それに記入してください。警告への対応でコードを変更した場合は、新たに有効になったルールを具体的に記載してください。

---

ヒントとエッジケース

モノレポ：very_good_analysis に依存する各パッケージで、それぞれの pubspec.yaml を更新する必要があります。pub get はパッケージごとに実行する必要があります。リポジトリのルートで analyze を実行すると、すべてのパッケージの警告をまとめて確認できるため、パッケージごとに実行するのではなく、ルートで実行してください。

まとめて依頼された変更：ユーザーは、アップグレードにクリーンアップを加えるよう依頼することがよくあります。「ついでに http も更新して」「TODO を削除して」「以前から無視していた警告に対して dart fix --apply を実行して」などです。依頼全体を拒否するのではなく、返答を分けてください。very_good_analysis の更新と、それによって新しいルールへの対応として必要になるリント修正は引き受け、それ以外はリント準拠の PR の範囲外であることを明示して、個別に断ったうえで後続の PR として提案してください。無関係な依存関係の更新と一括自動修正は、「リントのアップグレードの一環」としてレビューをすり抜けやすい変更です。対象外とし、但し書きを付けて更新することも避けてください。パッケージの内容を確認できない場合も、ユーザーの説明をもとに同じように対応してください。どの変更を PR に含めるかはスコープの判断であり、ファイルによって決まるものではありません。

analysis_options.yaml：very_good_analysis には独自の analysis_options.yaml が含まれており、プロジェクト独自のオプションファイルから読み込まれます。通常、プロジェクトの analysis_options.yaml を変更する必要はありません。新しいルールを取り込むには、pubspec.yaml の更新で十分です。

破壊的なルール変更：新しいバージョンで、以前は有効だったルールが無効になったり、重大度が変更されたりすることがあります。その結果、以前は警告されていた問題が表示されなくなる場合がありますが、その場合は問題ありません。再び有効にしないでください。

flutter pub get が失敗する場合：更新後に依存関係の解決に失敗したら、ソルバーの出力を確認し、そこで作業を止めてください。更新を解決するために、別の依存関係を強制的にアップグレードしたり、制約を緩めたり、削除したりしないでください。また、pub upgrade --major-versions も実行しないでください。これはリントの PR に無関係なメジャーバージョンの更新を持ち込み、レビュー担当者がリスクを把握できなくなるまさにその変更です。ユーザーが「必要なものは何でもアップグレードして」と言っても、この方針は変わりません。このようなケースに対応するためのルールです。

代わりに、競合している両方の依存関係と解決方法を明示して報告し、どれを選ぶかはユーザーに委ねてください。たとえば、build_runner depends on analyzer ^6.4.1 と very_good_analysis 10.0.0 depends on analyzer ^7.0.0 が競合してソルバーが失敗した場合は、次のように伝えます。

build_runner ^2.4.0 は analyzer ^6.4.1 を固定しており、very_good_analysis 10.0.0 は analyzer ^7.0.0 を必要としています。両方を同時に満たすことはできないため、この更新だけでは適用できません。選択肢は、まず別の PR で analyzer ^7 を許容するリリースに build_runner を更新する、build_runner がすでに満たせる analyzer の制約を持つ最新の very_good_analysis を使用する、または build_runner を削除する、のいずれかです。どれを希望しますか？

「競合があります」とだけ伝えるのでは不十分です。2 つの制約を明示してください。

---

追加リソース

よくあるリントルールとその一般的な修正方法、および動作へのリスクがあるルール（prefer_const_constructors、use_super_parameters、unnecessary_late、avoid_dynamic_calls、require_trailing_commas、unnecessary_null_checks）をまとめた早見表については、references/lint-fixes.md を参照してください。また、very_good_analysis 11.0.0 で追加される Dart 3.13 のコンストラクター関連ルール（unnecessary_type_name_in_constructor、use_declaring_parameters、unnecessary_primary_constructor_body、empty_container_bodies）も掲載しています。