statictrace

statictrace

日本語

Exigences

Node.js 14.15.0 ou version ultérieure.

Installation

Installer

npm install @yumemi-inc/statictrace

Vous pouvez installer statictrace par projet ou dans le monde.

Construire à partir de la source

 pnpm install
pnpm run build

ts-node :

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

Utiliser comme CLI

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

Vous pouvez omettre l'option -p en créant un fichier .env avec une variable TS_PROJECT_CONFIG .

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

Autres options

• u, --use <printer> (facultatif): Choisissez l'un des types d'imprimantes par défaut ( text ou mermaid ).

Usage

statictrace commence une analyse statique de votre code à partir d'un point explicitement laissé entendre par un développeur. Par exemple, si vous souhaitez analyser le flux d'enregistrement comme ci-dessous, vous devez ajouter un indice JSDOC à la fonction où le flux commence: @entrypoint YourFlowName .

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

Le simple fait de faire cela ne produit pas de sortie, mais statictrace suit en interne tous les appels de fonction et de méthode qui se produisent dans startRegistration() et chaque fonction des appels de ces fonctions jusqu'à ce qu'il n'y ait pas d'appels. En d'autres termes, il construit un StackTrace statique. S'il existe des fonctions et des méthodes particulières que vous souhaitez tester ou documenter, par exemple pour savoir si certaines fonctions sont appelées, leur ordre d'appel et leur relation parent / enfant, vous devez marquer des fonctions pertinentes avec un autre commentaire spécial: @trace .

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

Avec ce statictrace produit la sortie suivante:

 Entrypoint: Registration
startRegistration
        processRegistration
                someRegistrationProcedure

Vous pouvez utiliser cette sortie comme un instantané d'un StackTrace et l'utiliser à partir de votre bibliothèque de test de choix pour garantir que le flux ne change pas après la refactorisation par exemple. Vous pouvez également publier le StackTrace sous forme de graphiques mermaid à des fins de documentation (voir l'image ci-dessous).

Exemples

• Sortie le résultat en tant que texte en retrait similaire à un débogueur StackTrace:

$ statictrace

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

• Sortie le résultat imprimé en tant que graphiques de sirène dans un fichier de marque: statictrace -u mermaid > graphs.md

C'est à quoi ressemblent les graphiques de sirène rendus:

Utiliser API programmatiquement

 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

Chargez tous les fichiers du projet et créez un graphique de tous les appels de fonction marqués avec des balises @entrypoint ou @trace . Vous devez passer un type d'imprimante comme deuxième argument. Une imprimante est une interface qui représente tout ce qui peut imprimer (afficher l'analyse statique résulte d'une manière ou d'une autre). Actuellement, vous ne pouvez pas fournir vos propres implémentations, mais vous pouvez choisir l'une des par défaut.