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()内发生的所有功能和方法调用，并且在这些函数中的每个函数调用，直到没有呼叫为止。换句话说，它构建了一个静态的stacktrace。如果您要测试或文档有任何特定的功能和方法，例如知道是否调用了某些功能，他们的呼叫顺序和父/子女关系，则需要使用另一个特殊评论来标记相关功能： @trace 。

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

使用此statictrace可产生以下输出：

 Entrypoint: Registration
startRegistration
        processRegistration
                someRegistrationProcedure

您可以将此输出用作堆叠条件的快照，并将其从选择的测试库中使用它来确保流量在重构后不会发生变化。您还可以将堆叠条作为以文档目的输出作为mermaid图形（请参见下图）。

例子

• 输出结果作为缩进的文本类似于调试器stacktrace：

$ 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标签的所有功能调用的图。您应该将打印机类型作为第二个参数传递。打印机是代表任何可以打印的任何东西的接口（以一种或另一种方式显示静态分析）。当前，您无法提供自己的实现，但可以选择其中一个。