Go アナリシス API ガイド

概要

パッケージ分析は、モジュラー型の静的解析ツールとそれを駆動するプログラム（ドライバ）の間のインターフェースを定義します。

• 静的解析: Go のソースコードを対象に診断情報（誤り報告など）を生成する機能。
  • チェッカー: 非公式な名称で、誤りを報告する解析器のこと（例：

    printf チェッカー

    ）。
• モジュラー型: より上位のパッケージを検証する際に、より下位の依存パッケージから情報を保存・利用する仕組み。
  • 部分的コンパイル（separate compilation）に類似した概念。
• 共通インターフェースのメリット:
  • 多様な出所のチェッカーを選定・組み込み・再利用が容易になる。
  • 以下のような様々なドライバプログラムで使用可能：
    • コマンドラインツール（例：

      vet

      ）
    • テキストエディタや IDE
    • ビルドおよびテストシステム（go build, Bazel, Buck など）
    • テストフレームワーク、コードレビューツール、インデキサー、ドキュメントビューアなど。

解析器 (Analyzer)

API の主要な型は

Analyzer

Analyzer

アナライザの構造と設定

典型的な例（

go/analysis/passes/unusedresult

var Analyzer = &analysis.Analyzer{
    Name:  "unusedresult",
    Doc:   "一部の関数への呼び出しの結果が未使用であることをチェック",
    Run:   run,
    ...
}

func run(pass *analysis.Pass) (interface{}, error) {
    ...
}

ドライバと解析器の統合

ドライバプログラム（例：

vet

import ( 
    "unusedresult"; "nilness"; "printf" ) 

var analyses = []*analysis.Analyzer{
    unusedresult.Analyzer,
    nilness.Analyzer,
    printf.Analyzer,
}

Analyzer 型のフィールド

Analyzer

Name string

Doc string

Flags flag.FlagSet

Run func(*Pass) (interface{}, error)

RunDespiteErrors bool

ResultType reflect.Type

Requires []*Analyzer

FactTypes []Fact

• Validate 関数:

  Analyzer

  の健全性チェックを行います（例：非循環な依存関係グラフ、一意な fact/結果型など）。
• Flags の扱い:

  vet

  と異なり、解析用フラグはコマンドラインに直接宣言されず、ドライバが設定します。

パス (Pass)

Pass

Analyzer

Pass の構造

解析器の

Run

type Pass struct {
    Fset         *token.FileSet
    Files        []*ast.File          // 構文木
    OtherFiles   []string             // アセンブリなどの非 Go ファイル
    IgnoredFiles []string             // 現在のパッケージに含まれないファイル
    Pkg          *types.Package       // パッケージ情報
    TypesInfo    *types.Info          // 型情報
    ResultOf     map[*Analyzer]interface{} // 依存解析の結果
    Report       func(Diagnostic)     // 診断情報の出力関数
    ...
}

ファイルの読み込みと処理

• OtherFiles

  と

  IgnoredFiles

  を含むファイル内容は

  Pass.ReadFile

  で読み込みます。
• 非 Go ファイルの診断: アセンブリファイルなどへの診断情報を報告する例は「asmdecl」または「buildtags」解析器参照。

content, err := pass.ReadFile(filename)
if err != nil { ... }
tf := fset.AddFile(filename, -1, len(content))
tf.SetLinesForContent(content)
// 診断情報の出力
pass.Reportf(tf.LineStart(line), "oops")

結果と拡張機能 (

ResultOf

)

• ResultOf

  : 依存解析器が計算した結果のマップ。
• 利点: コア API に依存を追加せずに後の解析器を拡張可能。必要な機能分のみを実装すればよい（支払うコスト削減）。
• 例:
  • 「ctrlflow」：制御フローグラフ (

    *ctrlflow.CFGs

    ) を返す。
  • 「inspect」：構文木の効率的な走査に役立つ値を返す。
  • 「buildssa」：SSA フォームの中間表現を構築する。

診断情報の報告 (

Report

)

• Diagnostic

  構造体はソース位置に関連するメッセージを含みます。
• Category: 複数の種類の診断がある場合の分類識別子（オプション）。
  • 重症度を示すフィールドはないため、フィルタリングと優先付けはドライバ側でカスタマイズする必要があります。

ヘルパーメソッド

Pass

• pass.Reportf(pos token.Pos, format string, args ...any)

生のテキストファイルの診断

1行に対して診断情報を報告するシーケンス例：

content, err := pass.ReadFile(filename)
if err != nil { ... }
tf := fset.AddFile(filename, -1, len(content))
tf.SetLinesForContent(content)
...
pass.Reportf(tf.LineStart(line), "oops")

事実（Fact）を用いたモジュラー解析

大規模プログラムにおける部分的コンパイルのメリット（効率性、拡張性）を静的解析にも適用するのがモジュラー解析です。

基本概念

• ファクト (Fact): 興味深い結果への踏台となる事実（例：「f は printf wrapper です」）。
• 役割: 新しい種類の事実型を定義し、オブジェクトやパッケージに関連付け、既存の事実を検索する機能を提供。

解析器での Fact の宣言

var Analyzer = &analysis.Analyzer{
    Name:      "printf",
    FactTypes: []analysis.Fact{new(isWrapper)},
    ...
}

type isWrapper struct{} // => *types.Func f “is a printf wrapper”

シリアル化とプロパゲーション

• 責任: ドライバは事実を 1 つのパッケージから別のパッケージ（アドレス空間をまたいで）に伝播させる必要があります。
• シリアル化:

  • encoding/gob

    を使用して事実をシリアル化する必要がある（決定論的）。
  • デフォルトが不適切な場合、

    GobEncoder

    /

    GobDecoder

    インターフェースを実装できます。
  • 事実は状態を持たない（stateless）べきです。
• 理由: ビルダシステムでコンテンツアドレス可能なキャッシュを使用する際に見かけ上のキャッシュミスを回避するため。

Pass での Fact の管理

type Pass struct {
    ...
    ExportObjectFact func(types.Object, Fact)
    ImportObjectFact func(types.Object, Fact) bool
    
    ExportPackageFact func(fact Fact)
    ImportPackageFact func(*types.Package, Fact) bool
}

• 制約: 解析器は現在のパッケージまたはそのオブジェクトに関連する事実のみをエクスポートできますが、インポート依存関係にある任意の事実をインポートできます。
• 実装注意: 一部のドライバ（Bazel など）は標準ライブラリパッケージに対して解析器を適用しないため、事実を標準パッケージで利用可能とは見做すべきではありません。

アナリシストのテストとコマンド

テスト (

analysistest

)

analysistest

• testData ファイルのパッケージに対して解析器を実行。
• 予想されるすべての診断情報と事实在が報告されているかチェック。
• 期待値の記述: 入力コード内の

  // want ...

  コメントを使用。

スタンドアロンコマンド

vet

1. SingleChecker (

   singlechecker

   ):
   • 単一の解析器を実行するコマンドの

     main

     関数を生成。

package main

import (
    "golang.org/x/tools/go/analysis/passes/findcall"
    "golang.org/x/tools/go/analysis/singlechecker"
)

func main() { singlechecker.Main(findcall.Analyzer) }

1. MultiChecker (

   multichecker

   ):
   • 複数の解析器を提供するツール向け。Analyzers のリストを与えます。

API リファレンスサマリー

関数と型一覧

• func Validate(analyzers []*Analyzer) error

  • 誤設定があった場合のエラー報告機能。
  • チェック項目：名前の有効性、Doc の空有無、Run の nil 判定、依存グラフの非循環性、Fact 型の一意性及びポインタ型であること。

• type Analyzer

  • 解析関数とオプションを記述する主要型。
  • メソッド：

    String() string

• type CycleInRequiresGraphError struct

  • 依存関係グラフに循環が存在する場合のエラー構造体。

• type Diagnostic

  • ソース位置または範囲に関連するメッセージ。
  • 特徴:
    • オプションの

      Category

      （定数）で分類。

    • Pos

      値は

      Pass.Fset

      に相対的に解釈される。

    • End

      が提供された場合、診断はその範囲に適用される。

• type Fact interface

  • 解析中に生成される中間事実。
  • 特徴:
    • 命名された宣言（

      types.Object

      ）またはパッケージ全体に関連付けられる。
    • 「決して戻らない」ような述語を表す（主体ではない）。
    • アドレス空間を超えて生成・消費可能。
    • ビルド出力内の型エクスポートデータに類似。
    • 各パスは、直接インポートしたパッケージから始まる事実セットで動作。
    • 必須: 型はポインタである必要がある (

      Validate

      でチェック)。
    • エンコード:

      encoding/gob

      を使用（カスタマイズ時は

      GobEncoder

      /

      GobDecoder

      ）。
    • エクスポート後は変更不可。

• type Module

  |

  type ModuleError struct

  : モジュールおよび読み込みエラーを表す。

• type ObjectFact

  |

  type PackageFact

  : 対象と関連付けられた事実の具体化型。

• type Pass

  • 解析器とドライバの間のインターフェースを形成。入力・出力両方のコンポーネントを持つ。
  • 注意: 1 つのパスは他のパスの結果に依存可能だが、

    Run

    関数は並行して呼び出してはいけない。
  • メソッド：

    • ReportRangef(rng Range, format string, args ...any)

    • Reportf(pos token.Pos, format string, args ...any)

    • String() string

• type Range

  • 範囲を提供する型（

    ast.Node

    と同等）。

• type RelatedInformation struct

  • 診断に関連する情報（例：変数の重複宣言時の既存宣言リスト）を含む。

• type SuggestedFix struct

  • ユーザーがコードに適用できる変更（

    Message

    ,

    TextEdits

    ）。
  • 制約:

    TextEdit

    は重なり合ったり、他のパッケージを含んではいけない。挿入順序は重要でないが、適用順序を決定する必要がある。

• type TextEdit

  • Pos と End の間のコードを新しいテキストに置換する操作を表す。各エディットは単一ファイルに適用される。