statictrace

statictrace

日本語

要件

node.js 14.15.0以降。

インストール

インストール

npm install @yumemi-inc/statictrace

statictraceがプロジェクトごとに、またはグローバルにインストールできます。

ソースからビルド

 pnpm install
pnpm run build

ts-node ：

 pnpx ts-node src/lib.ts -p /absolute/path/to/tsconfig.json

CLIとして使用します

 statictrace -- -p /absolute/path/to/tsconfig.json

TS_PROJECT_CONFIG変数を使用して.envファイルを作成することにより、 -pオプションを省略できます。

 TS_PROJECT_CONFIG=/absolute/path/to/tsconfig.json

その他のオプション

• u, --use <printer> （オプション）：デフォルトのプリンタータイプ（ textまたはmermaid ）のいずれかを選択します。

使用法

statictrace 、開発者によって明示的に示唆されているポイントからコードの静的分析を開始します。たとえば、以下のように登録フローを分析する場合は、フローが始まる関数にJSDOCヒントを追加する必要があります： @entrypoint YourFlowName 。

 /**
 * @entrypoint Registration
 */
function startRegistration ( ) {
  processRegistration ( ) ;
  finishRegistration ( ) ;
  untracedFunction ( ) ;
  cleanupSomething ( ) ;
}

これを行うだけでは出力は生成されませんが、 statictrace 、 startRegistration()内で発生するすべての機能とメソッド呼び出しを内部的に追跡し、呼び出しがなくなるまでそれらの関数内のすべての関数呼び出しを追跡します。言い換えれば、静的なスタックトレースを構築します。テストまたは文書化する特定の機能と方法がある場合、たとえば、いくつかの関数が呼び出されているかどうか、その呼び出し順序、親と子の関係を知るために、関連する機能を別の特別なコメントでマークする必要があります： @trace 。

 /** @trace */
function processRegistration ( ) {
  someRegistrationProcedure ( ) ;
}

このstatictraceを使用すると、次の出力が生成されます。

 Entrypoint: Registration
startRegistration
        processRegistration
                someRegistrationProcedure

この出力をスタックトレースのスナップショットとして使用し、選択したテストライブラリから使用して、例えばリファクタリング後にフローが変化しないことを保証できます。ドキュメントの目的で、Stacktraceをmermaidグラフとして出力することもできます（下の写真を参照）。

例

• 結果をデバッガースタックトレースと同様のインデントテキストとして出力します。

$ statictrace

=======================
Entrypoint: SomeEntrypoint
begin
        funcA
                funcC
        beingNestedEntrypoint
                funcA
                        funcC
                funcB
        funcB

• 結果を人魚グラフとしてマークダウンファイルに出力しました： statictrace -u mermaid > graphs.md

これは、人魚のグラフのレンダリング方法です。

プログラムでAPIを使用します

 const { run } = require ( './build/lib' ) ;
const output = run ( '/absolute/path/to/tsconfig.json' , 'text' ) ;
// ...do something with output 

run(pathToTsConfig: string, printerType: "text" | "mermaid"): any

すべてのプロジェクトファイルをロードし、 @entrypointまたは@traceタグでマークされたすべての機能呼び出しのグラフを作成します。 2番目の引数としてプリンタータイプを渡す必要があります。プリンターは、印刷できるものを表すインターフェイスです（静的分析結果を何らかの形で表示します）。現在、独自の実装を提供することはできませんが、デフォルトの実装のいずれかを選択できます。