amarna

عمارنا

Amarna هو محاذاة ثابتة ولينتر للغة البرمجة القاهرة.

سمات

• يعثر
• التحليل المترجم-التخصص في قانون القاهرة وعقود ستاركنيت
• يدعم إنشاء القواعد المحلية والعالمية
• تصدر AST المحسّنة لملف القاهرة
• تصدير التحليل الثابت إلى تنسيق SARIF.

الاستخدام الأساسي

تحليل مشروع القاهرة في الدليل الحالي وتصدير نتائج SARIF إلى ملف:

amarna . -o out.sarif

تحليل ملف واحد file.cairo وتصدير نتائج SARIF إلى ملف:

amarna file.cairo -o out.sarif

قم بتحليل file.cairo ملف واحد.

amarna file.cairo -s

اندماج

• لتكامل عمل github ، استخدم Amarna-action.

القواعد المدعومة حاليا

#	قاعدة	ما يجده	تأثير	دقة
1	العمليات الحسابية	جميع استخدامات العمليات الحسابية +، -، *، و /	معلومات	عالي
2	الحجج غير المستخدمة	وسيطات الوظائف التي لا تستخدم في الوظائف التي تظهر فيها	تحذير	عالي
3	الواردات غير المستخدمة	الواردات غير المستخدمة	معلومات	عالي
4	ديكورات ضبابية	ديكورات رمز ضبابية	معلومات	عالي
5	وظائف غير مستخدمة	الوظائف التي لا تسمى أبدا	معلومات	واسطة
6	رموز الخطأ	مكالمات الوظائف التي لها قيم إرجاع يجب فحصها	معلومات	عالي
7	الاستخدام غير المتناسق	يؤكد أن يستخدم نفس الثابت بطرق مختلفة ، على سبيل المثال ، assert_le(amount, BOUND) و assert_le(amount, BOUND - 1)	تحذير	عالي
8	المتاجر الميتة	المتغيرات التي يتم تعيين قيم ولكنها لا تستخدم قبل بيان الإرجاع	معلومات	واسطة
9	الفائض غير المقيد	استدعاءات الوظيفة التي تتجاهل أعلام الفائض التي تم إرجاعها ، على سبيل المثال ، uint256_add	تحذير	عالي
10	قيمة إرجاع عنوان المتصل	استدعاء الوظائف إلى وظيفة get_caller_address .	معلومات	عالي
11	تصادم متغير التخزين	@storage_var مع نفس الاسم. (تم إهمالها)	تحذير	عالي
12	استيراد وظيفة ضمنية	الوظيفة مع Decoratorexternal @external, @view, @l1_handler التي يتم استيرادها ضمنيًا. (تم إهمالها)	معلومات	عالي
13	وظيفة العرض غير المنفذة	تعديل الحالة داخل وظيفة @view	معلومات	عالي
14	متغير غير مؤكد	المتغيرات المحلية التي لم يتم تهيئتها أبدًا.	معلومات	عالي

الاستخدام

تحليل مشروع القاهرة في الدليل الحالي ونتائج التصدير إلى ملف:

amarna . -o out.sarif

تحليل ملف واحد deleverage.cairo وتصدير نتائج إلى ملف:

amarna deleverage.cairo -o deleverage.sarif

قم بتحليل code.cairo ملف واحد.

amarna code.cairo -s

تحليل ملف القاهرة وإخراج AST المستردة في png :

amarna file.cairo -png

تحليل ملف القاهرة مع قاعدة unused_import:

amarna file.cairo --rules=unused-imports

قم بتحليل ملف القاهرة باستخدام جميع القواعد باستثناء قاعدة ANTITHMELT-ADD:

amarna file.cairo --except-rules=arithmetic-add

قائمة المساعدة الكاملة هي:

 usage: amarna [-h] [-p] [-o OUTPUT] [-s] [-png] [-rules RULES] [-exclude-rules EXCLUDE_RULES] [-show-rules] [-disable-inline] -f

Amarna is a static-analyzer for the Cairo programming language.

positional arguments:
  -f                    the name of the .cairo file or directory with .cairo files to analyze

optional arguments:
  -h, --help            show this help message and exit
  -p, --print           print output
  -o OUTPUT, --output OUTPUT
                        file to write the output results in sarif format
  -s, -summary, --summary
                        output summary
  -png, --png           save a png with the AST of a file
  -rules RULES, --rules RULES
                        Only run this set of rules. Enter rule names comma-separated, e.g., dead-store,unused-arguments
  -exclude-rules EXCLUDE_RULES, --exclude-rules EXCLUDE_RULES
                        Exclude these rules from the analysis. Enter rule names comma-separated, e.g., dead-store,unused-arguments
  -show-rules, --show-rules
                        Show all supported rules and descriptions.
  -disable-inline, --disable-inline
                        Disable rules with inline comments. The comments should be the first line and of the form: # amarna: disable=rulename1,rulename2

تنسيق ملف SARIF

يعد تنسيق ملف SARIF تنسيقًا قياسيًا لأدوات التحليل الثابت ويمكن عرضه في VSCODE مع الامتداد الرسمي.

تثبيت

pip install amarna

كيف تعمل القواعد

يمكن أن تكون قواعد التحليل الثابت:

• القواعد المحلية ، التي تحلل كل ملف بشكل مستقل.
• قواعد التجميع ، التي تحلل كل ملف بشكل مستقل وجمع البيانات لاستخدامها في قواعد ما بعد العملية.
• يمكن لقواعد ما بعد العملية ، والتي يتم تشغيلها بعد تحليل جميع الملفات استخدام البيانات التي تم جمعها في قواعد التجمع.

أمثلة على هذه:

• القواعد المحلية: ابحث عن جميع العمليات الحسابية في ملف
• قواعد التجمع: جمع جميع الوظائف المعلنة ، ودعا الوظائف
• قواعد ما بعد العملية: ابحث عن وظائف غير مستخدمة باستخدام البيانات التي تم جمعها ، أي الوظائف التي تم الإعلان عنها ولكن لم يتم استدعاؤها أبدًا.

القاعدة المسموح بها ، denylist والتعليقات المضمنة

أسماء الحكم

الحصول على أسماء القواعد التي تم تنفيذها حاليًا مع:

 amarna --show-rules

القاعدة المسموح بها

قم بتشغيل Amarna بمجموعة محددة من القواعد باستخدام

 amarna --rules=rule1,rule2 .

سيقوم الأمر التالي بتشغيل قاعدة unused-imports فقط وطباعة النتيجة الموجزة

 amarna --rules=unused-imports . -s

حكم Denylist

قم بتشغيل Amarna بجميع القواعد باستثناء مجموعة محددة من القواعد باستخدام

 amarna --exclude-rules=arithmetic-add,arithmetic-sub . -s

القاعدة المضمنة تعطيل التعليقات

يمكنك تغيير السطر الأول من ملف القاهرة لتعطيل قاعدة محددة على هذا الملف. على سبيل المثال ، إضافة الخط

 // amarna: disable=arithmetic-div,arithmetic-sub,arithmetic-mul,arithmetic-add

كخط أول من file.cairo وتشغيل Amarna مع

amarna directory/ --disable-inline -s

لن الإبلاغ عن أي قاعدة حسابية لملف file.cairo .