はじめに

Dart / Flutter の静的解析の基礎を学びたい。

静的解析（static analysis）

ソースコード、バイナリなどのプログラムを「実行せずに」解析すること。

バグやコーディングルール違反の検出のために実施される。

Diagnostic

静的解析を行うことは「診断」と表現され、診断結果は Diagnostic と表現される。

Dart Analysis Server や analyzer などのパッケージが Analyzer として様々なルールに基づいて Diagnostic（診断結果）を生成する。

Diagnostic は以下の仕組みによって出力されるエラー（error）、警告（warning）、情報（info）を表す。

言語レベルでの規約違反
Lint の規約違反
- Lint のルールセットは linter と表現される
Plugin による規約違反

error / warning / info は severity と言い、変更することができる。

Diagnostic は Analyzer が出力する診断結果の総称であるため、Lint や Plugin による指摘も Diagnostic の一種として扱われる。

また Diagnostic は抑制することもできる。

Diagnostic Message

Diagnostic から出力されるメッセージは Diagnostic messages にて一覧化されている。

https://dart.dev/tools/diagnostics

この一覧は

出力された Diagnostic について詳細を知りたい
ignore したい
severity を変更したい

といった時に役立つ。

Linter rules

Lint ルールは Linter rules にて一覧を確認することができる。

https://dart.dev/tools/linter-rules

出力された Diagnostic について詳細を知りたい
ignore したい

といった時に役立つ。

YAML

YAML Ain't Markup Language

YAML ファイルを扱う上で、頭に入れておきたい注意点。

インデントは「半角の空白」2 つ分
- タブによるインデントは不可
同じフィールドは 2 回記述できない
配列は [] で表現する

glob

ファイルパスをまとめて指定するための簡易パターン記法。

Dart に限らず、

Unix / Linux
Git
npm
CI 設定

などでも広く使われる。

glob を使わない場合

build/a.dart
build/b.dart
build/temp/c.dart

を設定値として使用したいとき、

glob を使った場合

build/**

という記法で簡略化することができる。

記号	意味
`*`	任意の文字列
`?`	任意の 1 文字
`**`	任意の階層（再帰的）
`/`	ディレクトリ区切り

glob の例	説明
`lib/*.dart`	`lib` 配下の `.dart` ファイル
`lib/*/.dart`	`lib` 配下の全ての `.dart` ファイル（サブディレクトリ内も含む）
`lib/**`	`lib` 配下の全てのファイル

手動で静的解析を実行する

Dart SDK から $ dart analyze コマンドが提供されている。

カレントディレクトリ配下の静的解析を実行する

$ dart analyze

特定のディレクトリやファイルを指定する

$ dart analyze [<DIRECTORY> | <DART_FILE>]

Flutter SDK からは $ flutter analyze コマンドが提供されている。

静的解析を実行する

$ flutter analyze

Diagnostic を抑制する

Diagnostic Message の name もしくは Linter rules の name を指定する。

特定の行の規約違反を抑制する

int x = ''; // ignore: invalid_assignment

特定の行の規約違反を「複数」抑制する

// ignore: invalid_assignment, const_initialized_with_non_constant_value
const x = y;

特定のファイルの規約違反を抑制する

// ignore_for_file: unused_local_variable

特定のファイルの規約違反を「複数」抑制する

// ignore_for_file: unused_local_variable, duplicate_ignore, dead_code

全てのリント規約違反を抑制する

// ignore_for_file: type=lint

pubspec.yaml に関する解析の警告を抑制することもできる。

pubspec.yaml

dependencies:
  flutter:
    sdk: flutter

  # ignore: sort_pub_dependencies
  collection: ^1.19.0

plugin の場合

特定の行の規約違反を抑制する

// ignore: some_plugin/some_code

ファイル全体の規約違反を抑制する

// ignore_for_file: some_plugin/some_code

`analysis_options.yaml`

静的解析をカスタマイズする際に利用するファイル。

analysis_options.yaml

include: package:lints/recommended.yaml

analyzer:
  exclude: [build/**]
  language:
    strict-casts: true
    strict-raw-types: true

linter:
  rules:
    - cancel_subscriptions

使用できるフィールドは Customizing static analysis に記載されている。

include:
analyzer:
linter:
formatter:
plugin:

analysis_options.yaml は解析対象のディレクトリのルートに配置する。

下記の例では my_other_package と my_other_other_package で実行した静的解析は #1 を使用され、my_package で実行した静的解析は #2 が利用される。

https://dart.dev/tools/analysis

接頭語 package: を使用したパスと、相対パスが使用できるが、相対パスを使用する場合、analysis_options.yaml を配置したパスを起点とした相対パスを使用する。

`include:`

他の .yaml ファイルを引用するという設定。

analysis_options.yaml

include: <url>

例

include: package:flutter_lints/flutter.yaml

例

include:
  - package:flutter_lints/recommended.yaml
  - ../team_options.yaml

`analyzer:`

analyzer をカスタマイズするためのフィールド。

exclude:
language:
errors:

analysis_options.yaml

analyzer:
  exclude:
    - lib/client.dart
    - lib/server/*.g.dart
    - test/_data/**
  language:
    strict-casts: true
    strict-raw-types: true
  errors:
    invalid_assignment: warning
    missing_return: error
    dead_code: info

`exclude:`

静的解析の対象外とするファイル。

analysis_options.yaml

analyzer:
  exclude:
    - lib/client.dart
    - lib/server/*.g.dart
    - test/_data/**

`language:`

型 check を強化するかどうかを true / false で設定する（デフォルト値は false）。

コーディングルールであるリントとは異なり、言語仕様レベルで許可もしくは禁止を強制することができる。

strict-casts
- dynamic 型から特定の型への 「暗黙的な」キャストを許容しない
strict-inference
- 「dynamic 型で宣言された後に、実際には特定の型として利用される変数」などの、型推測を許容しない
strict-raw-types
- raw type（型引数を省略したジェネリクス）を許容しない

analysis_options.yaml

analyzer:
  language:
    strict-casts: true
    strict-inference: true
    strict-raw-types: true

`errors:`

Diagnostic は「重大度（severity）」を持っていて、これは変更することができる。

ignore : 無視する
info : $ dart analyze 実行時の終了ステータスが失敗扱いにならない
warning : 終了ステータスが失敗扱いになる
error : 終了ステータスが失敗扱いになる

analysis_options.yaml

analyzer:
  errors:
    todo: ignore
    invalid_assignment: warning
    missing_return: error
    dead_code: info

`linter:`

リントルールを設定するためのフィールド。

指定できるフィールド値は Linter rules に一覧がある。

https://dart.dev/tools/linter-rules

package として提供されるリントルールもある。

https://pub.dev/packages/lints

静的解析とは異なり Lint にはコーディング規約、主観（好み）による判断があるため、誤検知が存在したり、静的解析の中では少し性質が異なる側面を持つことを理解して使用する必要がある。

pub.dev 上で公開される Dart / Flutter の package には score が付けられる。

例

linter:
  rules:
    - always_declare_return_types
    - annotate_redeclares
    - cancel_subscriptions
    - close_sinks
    - combinators_ordering
    - comment_references
    - invalid_case_patterns
    - one_member_abstracts
    - only_throw_errors

羅列するだけではなく、true / false を選択することができる。

Dart 言語のアップデートに伴って、過去のリントルールを明示的に無効化する場合などに利用する。

true / false を選択する

include: package:lints/recommended.yaml

linter:
  rules:
    avoid_shadowing_type_parameters: false
    await_only_futures: true

ただしこの場合、YAML の制限により true / false 省略スタイルと混在させることができない に注意する。

公式で推奨されているリントルール

Flutter で Dart を利用する場合には lint package ではなく flutter_lints package の使用が推奨されている。

If you're working on Flutter code, then instead of using the lints package, use flutter_lints, which provides a superset of the recommended rules.
https://dart.dev/tools/analysis#lints

analysis_options.yaml

include: package:lints/recommended.yaml

`formatter:`

フォーマットのルールをカスタマイズすることができる。

1 行 80 文字ルールを変更する

formatter:
  page_width: 123

`plugin:`

カスタムリント、警告（warning）、エディタによる自動修正（quick fix として提案されるやつ）のカスタマイズを実現する。

↓ quick fix

pub.dev からダウンロードした plugin（package）を plugins フィールドに追加する。

analysis_options.yaml

plugins:
  my_plugin: ^1.0.0

ローカル環境上の自前 plugin がある場合、ローカルのパスを記述しても良い。

analysis_options.yaml

plugins:
  my_plugin:
    path: /path/to/my_plugin

plugin で定義される「警告warning）」と「リント」はそれぞれデフォルトの挙動が異なる。

警告
- デフォルト: true
リント
- デフォルト: false

analysis_options.yaml

plugins:
  my_plugin:
    path: /path/to/my_plugin
    diagnostics:
      rule_1: true
      rule_2: true
      rule_3: false

自前 plugin

自前の plugin を作成するには Plugin クラスを提供する analysis_server_plugin パッケージが必要。

Set up the plugin package で解説されている。

フォーマット

手動でフォーマットを実行する

Dart SDK から $ dart format コマンドが提供されている。

特定のファイルに対してフォーマットを行う

$ dart format <DIRECTORY|DART_FILE>

ディレクトリ配下のファイル全てに対してフォーマットを行う

$ dart format <DIRECTORY>
$ dart format .

CI（continuous integration）上で、フォーマットが発生した場合に $ dart format を終了ステータスと共に終了（exit）させることができる（Notify when changes occur）。

$ dart format -o none --set-exit-if-changed <DIRECTORY|DART_FILE>

※ -o none：変更があったファイルのみ表示する

自動でフォーマットを実行する（VSCode）

VSCode の settings.json に以下の設定を追加することで、ソースコードの保存時に自動的にフォーマットが実行されるようになる。

setings.json

{
  "[dart]": {
    "editor.formatOnSave": true
  }
}