HN 日本語サマリー

← 一覧へ戻る
プログラミング

Go分析フレームワーク:Goチームによるモジュラー静的解析

Go Analysis Framework: modular static analysis by go team (pkg.go.dev)

212 pointsby AbuAssar70 コメント

要約

この記事は、Go言語のコードに対するモジュラー静的解析ツールを構築するためのフレームワークである`go/analysis`パッケージを紹介しています。このフレームワークは、解析ロジックを`Analyzer`として定義し、`Pass`オブジェクトを通じてパッケージ情報や他の解析結果にアクセスできるようにします。これにより、`vet`のようなコマンドラインツールからIDEまで、様々なドライバープログラムで解析機能を容易に統合・再利用できます。

全文翻訳

analysis

概要

analysisパッケージは、モジュール式静的解析と、それを実行するドライバープログラムとの間のインターフェースを定義します。

背景

静的解析とは、Goコードのパッケージを検査し、一連の診断情報(通常はコード中の間違い)を報告する関数、あるいはその他の結果(例えば、リファクタリングの提案など)を生成する関数です。間違いを報告する解析は、非公式には「チェッカー」と呼ばれます。例えば、printfチェッカーはfmt.Printfのフォーマット文字列中の間違いを報告します。

「モジュール式」解析とは、一度に1つのパッケージを検査するが、低レベルのパッケージから情報を保存し、より高レベルのパッケージを検査する際にそれを使用できる解析を指します。これはツールチェインにおける別コンパイルに似ています。printfチェッカーはモジュール式です。log.Fatalfのような関数がfmt.Printfに委譲していることを発見すると、その事実を記録し、他のパッケージからの呼び出しも含め、その関数への呼び出しもチェックします。

共通のインターフェースを実装することで、様々なソースからのチェッカーを、コマンドラインツール(vetなど)、テキストエディタやIDE、ビルド・テストシステム(go build、Bazel、Buckなど)、テストフレームワーク、コードレビューツール、コードベースインデクサー(SourceGraphなど)、ドキュメントビューア(godocなど)、大規模コードベース向けのバッチパイプラインなど、幅広いドライバープログラムで容易に選択、組み込み、再利用できます。

Analyzer

APIの主要な型は[Analyzer](https://pkg.go.dev/golang.org/x/tools/go/analysis#Analyzer)です。Analyzerは、解析関数の名前、ドキュメント、フラグ、他のアナライザーとの関係、そしてもちろんそのロジックを静的に記述します。

解析を定義するために、ユーザーはAnalyzer型の(論理的に定数である)変数を宣言します。以下は、go/analysis/passes/サブディレクトリ内のアナライザーの典型的な例です。

package unusedresult

var Analyzer = &analysis.Analyzer{
	Name: "unusedresult",
	Doc:  "check for unused results of calls to some functions",
	Run:  run,
	...
}

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

解析ドライバーは、一連の解析を実行し、それらが報告する診断情報を出力するvetのようなプログラムです。ドライバープログラムは、必要なAnalyzerのリストをインポートする必要があります。通常、各Analyzerは個別のパッケージに存在します。既存のドライバーに新しいAnalyzerを追加するには、リストに項目を追加します。

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

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

ドライバーは、名前、フラグ、ドキュメントを使用して、実行する解析を説明するオンラインヘルプを提供できます。Docコメントには、短い1行の要約と、オプションで説明の段落が含まれます。

[Analyzer](https://pkg.go.dev/golang.org/x/tools/go/analysis#Analyzer)型には、上記以外にもフィールドがあります。

type Analyzer struct {
	Name             string
	Doc              string
	Flags            flag.FlagSet
	Run              func(*Pass) (interface{}, error)
	RunDespiteErrors bool
	ResultType       reflect.Type
	Requires         []*Analyzer
	FactTypes        []Fact
}

Flagsフィールドは、解析の動作を制御する名前付き(グローバル)フラグ変数のセットを宣言します。vetとは異なり、解析フラグはコマンドラインのFlagSetに直接宣言されるわけではありません。フラグ変数を設定するのはドライバーの責任です。単一の解析aのドライバーは、そのフラグfをコマンドラインで-fとして直接公開するかもしれませんが、複数の解析のドライバーは、曖昧さを避けるためにフラグ名に解析名をプレフィックスとして付ける(-a.f)かもしれません。IDEはグラフィカルインターフェースを通じてフラグを公開する可能性があり、バッチパイプラインは設定ファイルからそれらを構成するかもしれません。フラグの動作例については、「findcall」アナライザーを参照してください。

RunDespiteErrorsフラグは、解析が型エラーのあるコードを処理できるかどうかを示します。処理できない場合、ドライバーはパースエラーや型エラーがあった場合にその解析をスキップします。オプションのResultTypeフィールドは、この解析によって計算され、他の解析で利用可能になる結果値の型を指定します。Requiresフィールドは、この解析が依存する解析のリストを指定し、それらの結果にアクセスできます。また、ドライバーが解析を実行できる順序を制約します。FactTypesフィールドについては、モジュール性のセクションで説明します。analysisパッケージは、Analyzerに対する基本的な健全性チェック(Requiresグラフが無効サイクルでないこと、ファクトおよび結果の型が一意であることなど)を実行するためのValidate関数を提供します。

最後に、Runフィールドには、ドライバーが単一パッケージに対して解析を実行するために呼び出す関数が含まれています。ドライバーはそれにPass型のインスタンスを渡します。

Pass

[Pass](https://pkg.go.dev/golang.org/x/tools/go/analysis#Pass)は、単一の作業単位、つまり特定のAnalyzerを特定のGoコードパッケージに適用することを表します。Passは、解析対象のパッケージに関する情報をAnalyzerのRun関数に提供し、ドライバープログラムに診断情報などを報告するための操作をRun関数に提供します。

type Pass struct {
	Fset         *token.FileSet
	Files        []*ast.File
	OtherFiles   []string
	IgnoredFiles []string
	Pkg          *types.Package
	TypesInfo    *types.Info
	ResultOf     map[*Analyzer]interface{}
	Report       func(Diagnostic)
	...
}

Fset、Files、Pkg、TypesInfoフィールドは、単一のGoパッケージの構文ツリー、型情報、ソース位置情報を提供します。

OtherFilesフィールドは、アセンブリのようなGo以外のファイルの名前を提供します。同様に、IgnoredFilesフィールドは、現在のビルド構成ではパッケージの一部ではないが、他のビルド構成ではパッケージの一部となる可能性のあるGoおよび非Goソースファイルの名前を提供します。これらのファイルのコンテンツはPass.ReadFileを使用して読み取ることができます。非Goファイルをロードし、それらに対する診断を報告する例については、「asmdecl」または「buildtags」アナライザーを参照してください。

ResultOfフィールドは、この解析が要求する(Analyzer.Requiresフィールドで表現される)アナライザーによって計算された結果を提供します。ドライバーは、要求されたアナライザーを先に実行し、それらの結果をこのマップで利用可能にします。各Analyzerは、Analyzer.ResultTypeフィールドで記述された型の値を返す必要があります。例えば、「ctrlflow」アナライザーは、パッケージ内の各関数に対する制御フローグラフを提供する*ctrlflow.CFGsを返します(golang.org/x/tools/go/cfgを参照)。「inspect」アナライザーは、他のアナライザーがパッケージの構文ツリーをより効率的にトラバースできるようにする値を返します。「buildssa」アナライザーは、SSA形式の中間表現を構築します。これらのアナライザーはそれぞれ、後続のアナライザーの機能を拡張しますが、コアAPIへの依存関係を追加しないため、解析ツールは必要な拡張機能にのみコストを支払います。

Report関数は、ソース位置に関連付けられたメッセージである診断情報を発行します。ほとんどの解析にとって、診断情報は主要な結果です。便宜上、Passは文字列をフォーマットして新しい診断情報を報告するためのヘルパーメソッドReportfを提供します。Diagnosticは次のように定義されます。

type Diagnostic struct {
	Pos      token.Pos
	Category string // optional
	Message  string
}

オプションのCategoryフィールドは、解析が複数の種類の診断情報を生成する場合にメッセージの種類を分類するための短い識別子です。

[Diagnostic](https://pkg.go.dev/golang.org/x/tools/go/analysis#Diagnostic)構造体には、その重大度を示すフィールドがありません。なぜなら、アナライザーとその診断情報の相対的な重要性に関する意見は、ユーザー間で大きく異なるからです。このフレームワークの設計では、各アナライザーに診断情報の重大度を特定する責任を負わせません。代わりに、ドライバーは、ユーザーの好みに応じて、生成したアナライザーとオプションのカテゴリに基づいて、診断情報のフィルタリングと優先順位付けをカスタマイズできるようにすると予想されます。

ほとんどのアナライザーは型付けされたGo構文ツリーを検査しますが、asmdeclやbuildtagのような一部のアナライザーは、Goソースファイルの生テキスト、あるいはアセンブリのような非Goファイルを検査します。生テキストファイルの行に対して診断情報を報告するには、次のシーケンスを使用します。

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 を用いたモジュール式解析

効率とスケーラビリティを向上させるために、大規模プログラムは通常、別コンパイルを使用して構築されます。プログラムの単位は個別にコンパイルされ、依存関係のいずれかが変更された場合にのみ再コンパイルされます。独立したモジュールは並列にコンパイルされる可能性があります。静的解析にも同じ技術を、同じ利点のために適用できます。そのような解析は「モジュール式」であると説明されます。

コンパイラの型チェッカーは、モジュール式静的解析の例です。私たちがGoプログラムに適用したい他の多くのチェッカーは、代替または非標準の型システムとして理解できます。例えば、vetのprintfチェッカーは、関数が「printfラッパー」型を持っているかどうかを推論し、そのような関数への呼び出しに対してより厳密なチェックを適用します。さらに、後続の解析パスが他のprintfラッパーを帰納的に識別するために使用できるように、どの関数がprintfラッパーであるかを記録します。診断情報(「Fはprintfラッパーである」など)自体は興味深いものではないが、興味深い結果(診断情報など)への踏み台となる結果はFactと呼ばれます。

解析APIは、解析が新しい型のFactを定義し、これらの型のFactを現在のパッケージ内で宣言されたオブジェクト(名前付きエンティティ)またはパッケージ全体に関連付け、オブジェクトまたはパッケージに関連付けられた指定された型の既存のFactをクエリできるようにします。

Factを使用するAnalyzerは、その型を宣言する必要があります。

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

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

ドライバープログラムは、解析対象パッケージの解析前に、その依存関係のFactが生成されることを保証し、Factをパッケージ間で(アドレス空間を越えて)伝播する責任を負います。したがって、Factはシリアライズ可能である必要があります。APIは、ドライバーがgobエンコーディングを使用することを要求します。これは効率的で堅牢な自己記述型バイナリプロトコルです。Fact型は、デフォルトのエンコーディングが不適切な場合、GobEncoder/GobDecoderインターフェースを実装できます。Factはステートレスであるべきです。シリアライズされたFactはビルド出力内に現れる可能性があるため、Factのgobエンコーディングは決定論的である必要があり、コンテンツアドレス可能なキャッシュを使用するビルドシステムでの誤ったキャッシュミスを防ぎます。ドライバーは、指定された解析パスによってエクスポートされたすべてのFactに対してgobエンコーダーを1回呼び出すため、複数のFactによって参照される共有データ構造のトポロジが保持されます。

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
}

Analyzerは、現在のパッケージまたはそのオブジェクトに関連付けられたFactのみをエクスポートできますが、現在のパッケージのインポート依存関係である任意のパッケージまたはオブジェクトからFactをインポートできます。

概念的には、ExportObjectFact(obj, fact)は、ペア(obj、TypeOf(fact))をキーとする隠しマップにfactを挿入し、ImportObjectFact関数はこのマップからエントリを取得し、その値をfactが指す変数にコピーします。このスキームは、factの具体的な型がポインタであると仮定しています。この仮定はValidate関数によってチェックされます。オブジェクトFactの動作例については、「printf」アナライザーを参照してください。

一部のドライバー実装(BazelやBlazeに基づくものなど)は、現在標準ライブラリのパッケージにアナライザーを適用していません。したがって、最良の結果を得るために、アナライザーの著者は標準パッケージで利用可能な解析Factに依存しないようにすべきです。例えば、printfチェッカーはlogパッケージの解析中にlog.Printfがprintfラッパーであることを推論できますが、このFactはアナライザーに組み込まれているため、標準パッケージに適用されないドライバーで実行された場合でもlog.Printfへの呼び出しを正しくチェックします。将来的にこの制限を解除したいと考えています。

Analyzer のテスト

analysistestサブパッケージは、Analyzerをテストするためのユーティリティを提供します。数行のコードで、testdataファイルのパッケージに対してアナライザーを実行し、期待されるすべての診断情報とFact(それ以上でもそれ以下でもない)を報告したことを確認できます。期待値は、入力コードの// want ...コメントを使用して表現されます。

スタンドアロンコマンド

アナライザーは、ドライバープログラムがインポートすることを想定したパッケージの形式で提供されます。vetコマンドはいくつかのアナライザーのセットをインポートしますが、ユーザーは追加のチェックを実行する独自のアナライザコマンドを定義したい場合があります。アナライザコマンド(単一のアナライザーまたはスイート全体用)を作成するタスクを簡素化するために、singlecheckerおよびmulticheckerサブパッケージを提供します。

singlecheckerパッケージは、1つのアナライザーを実行するコマンドのmain関数を提供します。慣例として、go/analysis/passes/findcallのような各アナライザーは、go/analysis/passes/findcall/cmd/findcallで定義されているようなsinglecheckerベースのコマンドを伴います。

package main

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

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

複数のアナライザーを提供するツールは、同様の方法でmulticheckerを使用し、アナライザーのリストを渡すことができます。

Index
Constants

このセクションは空です。

Variables

このセクションは空です。

Functions
func Validate
func Validate(analyzers []*Analyzer) error

Validateは、アナライザーが誤って設定されている場合にエラーを報告します。チェックには以下が含まれます:名前が有効な識別子であること。Docが空でないこと。Runがnilでないこと。Requiresグラフが無効サイクルでないこと。アナライザーのFact型が一意であること。各Fact型がポインタであること。

アナライザー名は、混乱を招く可能性がありますが、一意である必要はありません。

Types
type Analyzer

Analyzerは、解析関数とそのオプションを記述します。

type Diagnostic

Diagnosticは、ソースの場所または範囲に関連付けられたメッセージです。

Analyzerは様々な診断情報を返せます。オプションのCategory(定数であるべき)は、それらを分類するために使用できます。主にドキュメントの検索を容易にすることを目的としています。

すべてのPos値はPass.Fsetに対して解釈されます。Endが提供されている場合、診断情報はPosとEndの間の範囲に適用されると指定されます。

type Fact
type Fact interface {
	AFact() 
}

Factは、解析中に生成される中間的な事実です。

各Factは、名前付き宣言(types.Object)またはパッケージ全体に関連付けられます。単一のオブジェクトまたはパッケージは、複数の関連Factを持つことができますが、特定のFact型は1つだけです。

Factは、「決して返らない」のような述語を表しますが、「関数F」や「パッケージP」のような述語の主語を表すものではありません。

Factは、異なるアドレス空間にある場合でも、ある解析パスで生成され、別の解析パスで消費される可能性があります。パッケージPがQをインポートする場合、そのパッケージの解析中に生成されたQに関するすべてのFactは、Pの後の解析中に利用可能になります。Factは、ビルドシステムにおける型エクスポートデータに類似しています。エクスポートデータが複数のパスの別コンパイルを可能にするのと同様に、Factは「別解析」を可能にします。

各パス(a、p)は、pが直接インポートするパッケージに対してアナライザーaが生成したFactのセットから開始します。解析はFactをセットに追加でき、それらは順番にエクスポートされる可能性があります。アナライザーのRun関数は、Pass.Import{Object,Package}Factを呼び出すことでFactを取得し、Pass.Export{Object,Package}Factを使用して更新できます。

Factは、そのAnalyzerにとって論理的にプライベートです。異なるアナライザー間で値を渡すには、結果メカニズムを使用します。Analyzer.Requires、Analyzer.ResultType、およびPass.ResultOfを参照してください。

Fact型はポインタである必要があります。Factはencoding/gobを使用してエンコードおよびデコードされます。Factは、エンコーディングをカスタマイズするためにGobEncoder/GobDecoderインターフェースを実装できます。Factのエンコーディングは失敗すべきではありません。

Factはエクスポートされた後は変更されるべきではありません。

type Module v0.24.0 で追加

Moduleは、パッケージが属するモジュールを記述します。

type ModuleError v0.43.0 で追加
type ModuleError struct {
	Err string 
}

ModuleErrorは、モジュールのロードに関するエラーを保持します。

type ObjectFact

ObjectFactは、関連するFactを持つオブジェクトです。

type PackageFact

PackageFactは、関連するFactを持つパッケージです。

type Pass

Passは、特定のGoパッケージに特定のAnalyzerを適用するRun関数に情報を提供します。

これは、解析ロジックとドライバープログラムとの間のインターフェースを形成し、入力と出力の両方のコンポーネントを持っています。

コンパイラと同様に、1つのパスは別のパスによって計算された結果に依存する場合があります。

Run関数は、Pass関数を並行して呼び出すべきではありません。

func (*Pass) ReportRangef
func (pass *Pass) ReportRangef(rng Range, format string, args ...any)

ReportRangefは、提供された範囲を使用してDiagnosticを報告するヘルパー関数です。ast.Node値は範囲として渡すことができます。なぜなら、それらはRangeインターフェースを満たすからです。

func (*Pass) Reportf

Reportfは、指定された位置とフォーマットされたエラーメッセージを使用してDiagnosticを報告するヘルパー関数です。

type Range

Rangeインターフェースは範囲を提供します。これはast.Nodeと同等であり、満たされます。

type RelatedInformation struct {
}

RelatedInformationは、診断情報に関連する情報を含みます。例えば、変数の重複宣言をフラグ付けする診断情報には、既存の宣言ごとのRelatedInformationが含まれる場合があります。

type SuggestedFix
type SuggestedFix struct {
	
	
	
	Message   string
	TextEdits []TextEdit
}

SuggestedFixは、ユーザーがコードに適用することを選択できる、Diagnosticに関連付けられたコード変更です。通常、SuggestedFixは診断情報によってフラグ付けされた問題を修正することを目的としています。

TextEditsは重複してはならず、他のパッケージの編集を含んではなりません。編集は完全に順序付けされる必要はありませんが、順序は同じ位置での挿入がどのように適用されるかを決定します。

type TextEdit

TextEditは、PosとEndの間のコードを新しいテキストで置き換えることを表します。各TextEditは単一のファイルに適用されるべきです。EndはPosよりファイル内で前に来るべきではありません。