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

يمكنك حذف خيار -p عن طريق إنشاء ملف .env مع متغير TS_PROJECT_CONFIG .

 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

يمكنك استخدام هذا الإخراج كقطعة من stacktrace ، واستخدامه من مكتبة الاختبار الخاصة بك لضمان عدم تغيير التدفق بعد إعادة إعادة البناء. يمكنك أيضًا إخراج StackTrace كرسوم بيانية mermaid لأغراض الوثائق (انظر الصورة أدناه).

أمثلة

• إخراج النتيجة كنص بادئة مشابهة لـ Debugger Stacktrace:

$ statictrace

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

• إخراج النتيجة المطبوعة كرسوم بيانية حورية البحر إلى ملف Markdown: 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 . يجب أن تمرر نوع الطابعة كوسيطة ثانية. الطابعة هي واجهة تمثل أي شيء يمكن أن يطبع (يعرض التحليل الثابت يؤدي بطريقة أو بأخرى). لا يمكنك حاليًا توفير تطبيقاتك الخاصة ولكن يمكنك اختيار أحد التطبيقات الافتراضية.