Doctor による診断

vize doctor は、Vue コンポーネントとスクリプトモジュールを横断して、アプリケーションの健全性を調べます。 依存性注入の不一致、循環 import、サーバーとクライアントの境界、コンポーネント間の props 契約などの問題を、 判断の根拠となるソースの位置とともに報告します。まずターミナルでレポートを読み、該当するコードを確認してください。 変更後に同じコマンドを実行すると、診断の変化を確かめられます。

CLI のインストールははじめに、ほかのコマンドは CLI ガイドを参照してください。

最初のレポートを読む

プロジェクトのディレクトリで、解析するソースのディレクトリを指定します。

vize doctor src

src は、アプリケーションのソースがあるディレクトリに置き換えてください。 パスを指定せずに vize doctor を実行すると、現在のワークスペースを調べます。 共有コードも含めるには、複数のディレクトリを指定します。

vize doctor src packages/shared

このコマンドは Vue SFC とスクリプトモジュールを読み取り、ファイルを書き換えません。 テキスト形式のレポートには、最初にワークスペース、100 点満点の健全性スコア、エラー・警告・通知の件数が表示されます。 それぞれの診断には、診断コード、メッセージ、ソースの位置が含まれます。コードを変更する前に、 示された位置をたどり、問題とされた関係を確認してください。その後、同じコマンドで結果を確かめます。

診断がないレポートは、現在の解析機能が対象のソースから問題を見つけなかったことを意味します。 アプリケーションのすべての動作を検証したという意味ではありません。 確実または高い確信度のエラーがある場合の終了コードは 1、探索・解析・レポート出力に失敗した場合は 2 です。 警告や確信度の低い診断は、デフォルトでは実行を失敗にしません。 詳しい方針はスコアと終了コードで説明します。

CI 用のレポートを保存する

ほかのツールで診断を扱う場合は、JSON 形式で出力します。

vize doctor src --format json > doctor-report.json

JSON レポートには、各診断のコード、位置、スコアが含まれます。ファイルにリダイレクトしても終了コードは 変わらないため、同じコマンドで CI のジョブを失敗させられます。

GitHub のコードスキャンなど SARIF を読むツールには、SARIF で出力します。

vize doctor src --format sarif > doctor.sarif

Tip

--exit-zero は、ビルドを失敗させるかどうかをほかのシステムが決める場合にだけ使ってください。 レポートを読むツールを作る前に、自動化で使う際の契約を確認してください。

診断を絞り込む

特定のカテゴリ、重大度、ルール、変更したソースに注目するには、フィルターを追加します。 フィルターはアプリケーション全体を解析した後で診断を選ぶため、コンポーネントをまたぐ診断が失われることは ありません。残った診断に対してスコアを計算し直します。まずレポート全体を読み、それから絞り込んでください。

フィルターを組み合わせる

同じフィルターを繰り返すと、複数の値を指定できます。 カテゴリ、重大度、確信度では、カンマ区切りの値も使えます。 同じ項目に指定した値は OR、値を指定した異なる項目の間は AND で組み合わせます。

vize doctor src \
  --category correctness,security \
  --severity error \
  --confidence certain,high \
  --rule 'VIZE_DOCTOR_CF_*' \
  --path 'packages/**/src/*.vue' \
  --changed-file 'packages/account/**'

この例では、値を指定したすべての項目に一致する診断だけを残します。 値を指定しない項目は、すべてに一致します。 そのため、--rule を繰り返すとルールの選択範囲が広がり、 --severity を追加すると別の条件によって結果が絞られます。

識別子とパスのフィルターには、大文字と小文字を区別するシェル形式の glob（*、?、[abc]、再帰的な **） を使い、どのプラットフォームでも / を区切り文字にします。不正なパターンや空のパターンがあると、終了コード 2 で停止し、誤っているフィルターを表示します。

変更ファイルによる絞り込み

--changed-file は、--path より広い範囲を調べます。 変更したファイルが次のいずれかに当たる場合、その診断を残します。

• 診断が報告された位置、または関連する位置
• 診断の判断がたどるファイル
• 提案された修正が編集するファイル
• 変更されると診断の結果が変わる入力

そのため、変更していないコンポーネントの診断でも、依存する共有コンポーネントや宣言が変わっていれば 表示されます。プルリクエストへの注釈には --changed-file が適しています。

スコアと終了コード

件数、カテゴリごとの健全性、全体のスコア、終了コードは、絞り込み後に残った診断だけを対象にします。 最後に残った、実行を失敗にする診断をフィルターで除外すると、終了コードは 1 から 0 に変わります。

レポートを参考情報として使い、ほかのシステムが失敗条件を決める場合は、--exit-zero を使います。 このオプションが変えるのはプロセスの終了コードだけです。 レポート内の、実行を失敗にするエラーがあるという状態は書き換えません。

自動化で使う際の契約

CI、エディター、ダッシュボード、AI ツールでは --format json を使ってください。JSON には、形式とスコア計算の バージョン、安定したルールコード、正規化されたパス、確信度、影響、各診断の根拠、修正を利用できるかどうかが 含まれます。JSON から診断を自分で削除するのではなく、上記の CLI オプション（Rust では vize_doctor::DoctorFilterSpec）で絞り込んでください。そうすれば、スコアと終了コードが表示内容と一致します。 テキスト、JSON、SARIF のどの出力にも同じフィルターが適用されます。