explain は、CC Safety Net がコマンドを解析する過程を手順ごとに表示します。コマンドがブロックまたは許可される理由や、カスタムルールの適用のされ方を確かめるときに使います。
explain のオプション
--json のスキーマ、ExplainResult のフィールド、TraceStep の全種類は、explain トレースリファレンスを参照してください。
ダッシュで始まるコマンドを explain する
-- でオプションの解析が終わり、その後ろはすべてコマンドとして扱われます。そのため explain -- --help はヘルプを出力せず、リテラルのコマンド --help を解析します。| や && などのシェル演算子をコマンドに残すには、コマンド全体を 1 つの引数として引用符で囲みます。
explain の終了コード
explain は、結果がブロックでも許可でも 0 で終了します。終了コードではなく result フィールドを読んでください。1 で終了するのは、不明なオプションや存在しない --cwd パスなどのオプションエラーの場合と、解析を拒否したコマンドの場合です。
explain が解析を拒否するコマンド
CC Safety Net の解析上限を超えるコマンドや、echo ${ のようにパーサーが構文を受け付けないコマンドは、explain が解析を拒否します。このとき 1 行のエラーを出力して 1 で終了します。--json を付けると、標準出力にはエラーオブジェクトだけが出力されます。