statictrace

statictrace

日本語

Requisitos

Node.js 14.15.0 ou posterior.

Instalação

Instalar

npm install @yumemi-inc/statictrace

Você pode instalar statictrace por projeto ou globalmente.

Construir a partir da fonte

 pnpm install
pnpm run build

ts-node :

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

Use como CLI

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

Você pode omitir a opção -p criando um arquivo .env com uma variável TS_PROJECT_CONFIG .

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

Outras opções

• u, --use <printer> (opcional): escolha um dos tipos de impressora padrão ( text ou mermaid ).

Uso

statictrace inicia a análise estática do seu código a partir de um ponto que é explicitamente sugerido por um desenvolvedor. Por exemplo, se você deseja analisar o fluxo de registro, como abaixo, precisará adicionar uma dica JSDOC à função onde o fluxo começa: @entrypoint YourFlowName .

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

Apenas fazer isso não produz saída, mas statictrace rastreia internamente todas as chamadas de função e método que ocorrem no startRegistration() e todas as funções são chamadas nessas funções até que não haja chamadas. Em outras palavras, ele constrói uma pilha estática. Se houver alguma função e métodos específicos que você deseja testar ou documentar, por exemplo, para saber se algumas funções são chamadas, sua ordem de chamada e relacionamento pai/filho, você precisa marcar funções relevantes com outro comentário especial: @trace .

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

Com este statictrace produz a seguinte saída:

 Entrypoint: Registration
startRegistration
        processRegistration
                someRegistrationProcedure

Você pode usar essa saída como um instantâneo de um Stacktrace e usá -lo na sua biblioteca de testes de opção para garantir que o fluxo não mude após a refatoração. Você também pode produzir o Stacktrace como gráficos mermaid para fins de documentação (veja a figura abaixo).

Exemplos

• Saia o resultado como texto recuado semelhante a um depurador Stacktrace:

$ statictrace

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

• Saia o resultado impresso como gráficos de sereia para um arquivo de marcação: statictrace -u mermaid > graphs.md

É assim que os gráficos de sereia renderizados se parecem:

Use API programaticamente

 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

Carregue todos os arquivos de projeto e crie um gráfico de todas as chamadas de função marcadas com tags @entrypoint ou @trace . Você deve passar por um tipo de impressora como um segundo argumento. Uma impressora é uma interface que representa qualquer coisa que possa imprimir (exibir a análise estática resultar de uma maneira ou de outra). Atualmente, você não pode fornecer suas próprias implementações, mas pode escolher um dos padrão.