--base/--target (وجميع الخيارات الأخرى) تُطبق بنفس الطريقة على كل مستودع في القائمة، لذا فإن وضع المستودعات المتعددة يناسب بشكل أفضل عندما تختلف جميعها مقابل نفس المرجع (مثل main للجميع). المستودعات ذات الاصطلاحات المختلفة تحتاج إلى تشغيلات منفصلة.

الخيارات

ماذا تفحص

• --base, -b (لا شيء): المرجع للاختلاف منه، مثل main أو HEAD~3. إذا تُرك فارغًا، يقوم zairo بفحص التغييرات غير المسجلة بدلاً من ذلك.
• --target, -t (لا شيء): المرجع للاختلاف إليه. يتطلب --base؛ إذا تُرك فارغًا (مع تعيين --base)، فإنه يختلف مقابل شجرة العمل الخاصة بك.
• --depth, -d (1): عدد القفزات من المستدعين/المستدعَين لسحبها إلى الرسم البياني للتأثير حول كل تغيير.
• --language, -l (تلقائي): فرض لغة بدلاً من ترك Trailmark يكتشفها تلقائيًا.

فحص LLM

• --graph-only (مغلق): تخطَّ فحص الثغرات وقم فقط ببناء الرسم البياني للتأثير — لا نتائج، ولا report.sarif.
• --model (gemini/gemini-2.5-pro): أي سلسلة نماذج LiteLLM.
• --concurrency, -c (5): طلبات LLM المتوازية، ضمن فحص مستودع واحد.
• --batch-size (1): تجميع هذا العدد من العقد في طلب LLM واحد بدلاً من استدعاء واحد لكل عقدة — طلبات أقل (يساعد في حدود معدل المزود)، على حساب عزل الأعطال المشترك: استجابة سيئة/غير صحيحة تفشل كل عقدة في تلك الدفعة، وليس عقدة واحدة فقط. يبقى التخزين المؤقت لكل عقدة على أي حال.
• --max-tokens (4096): ميزانية الإخراج لكل طلب. نماذج التفكير تستهلك هذا على التفكير الداخلي أيضًا، لذا ارفعه إذا رأيت استجابات فارغة.
• --cache / --no-cache (التخزين المؤقت مفعل): تخطَّ إعادة فحص الكود غير المتغير منذ آخر تشغيل (مخزن مؤقتًا بواسطة تجزئة المحتوى في <output>/.llm_cache.json).
• --tokens (مغلق): طباعة عدد الرموز التي استخدمها الفحص فعليًا (ضربات التخزين المؤقت لا تُحتسب، لأنها لم تُجرِ أي استدعاء).

الإخراج والبوابة

• --output, -o (zairo_out): أين تذهب التقارير. وضع المستودعات المتعددة: يحصل كل مستودع على <output>/<repo-slug>/ الخاص به، بالإضافة إلى rollup.* مدمج هنا أيضًا.
• --fail-on (لا شيء): الخروج برمز غير صفري إذا ظهرت نتيجة عند أو فوق هذه الخطورة (low/medium/high/critical). يظهر خطأ إذا تم دمجه مع --graph-only (لا يوجد شيء للبوابة عليه). وضع المستودعات المتعددة: يُفحص عبر جميع المستودعات مجتمعة. انظر بوابة CI / PR.
• --verbose, -v (مغلق): طباعة ما يحدث خطوة بخطوة (أوامر git، إعداد شجرة العمل، تقدم الفحص لكل عقدة).
• --debug, -vv (مغلق): كل ما يطبعه --verbose، بالإضافة إلى الطلب الدقيق المُرسل إلى LLM واستجابته الخام لكل عقدة — مكتوب إلى <output>/debug.log (لكل مستودع في وضع المستودعات المتعددة)، لأنه كثير جدًا للطباعة على وحدة التحكم.

وضع المستودعات المتعددة فقط

• --repos-file (لا شيء): مسار مستودع واحد لكل سطر (التعليقات # مسموحة)، مدمج مع أي مستودعات مُعطاة مباشرة.
• --repo-concurrency (1): عدد المستودعات لفحصها في وقت واحد. إجمالي طلبات LLM قيد التنفيذ يمكن أن يصل إلى --concurrency × --repo-concurrency، لذا انتبه لحدود معدل مزودك. فوق 1، يطبع التقدم سطر ملخص واحد لكل مستودع عند الاكتمال بدلاً من التفاصيل الحية خطوة بخطوة.
• --continue-on-error / --stop-on-error (متابعة): استمر في فحص بقية القائمة، أو توقف، عندما يفشل مستودع واحد. في كلتا الحالتين، أي مستودع فاشل لا يزال يفشل رمز الخروج الإجمالي.

شغّل zairo --help في أي وقت للحصول على نفس هذه القائمة من سطر الأوامر.

ملفات الإخراج

• report.json (دائمًا): الرسم البياني الخام للتأثير (العقد، الحواف، وأي نتائج مرفقة)، كبيانات.
• report.html (دائمًا): عارض رسوم بيانية تفاعلي قائم بذاته للتبعيات (Cytoscape.js). انقر على عقدة لرؤية نتائجها.
• report.sarif (إلا إذا تم استخدام --graph-only): النتائج بصيغة SARIF 2.1.0، لفحص كود GitHub أو أي مستهلك SARIF آخر. يُكتب دائمًا، حتى لفحص نظيف (سجل فارغ لكن صالح)، حتى تتمكن واجهة الفحص من وضع علامة على التنبيهات المُبلَّغ عنها سابقًا كمحلولة. تُجمَّع النتائج في قواعد حسب CWE عندما يضع النموذج وسمًا لها، بحيث تنهار المشكلات المتكررة من نفس النوع في قاعدة واحدة بدلاً من قاعدة جديدة لكل صياغة مختلفة.

وضع المستودعات المتعددة ينتج نفس الملفات الثلاثة لكل مستودع، بالإضافة إلى rollup.json / rollup.html / rollup.sarif: حالة كل مستودع وعدد الخطورة، جدول لوحة تحكم يربط بتقارير كل مستودع، وكل نتائج SARIF لكل المستودعات مدمجة في سجل متعدد التشغيلات.

الكود المحذوف

دالة/فئة/وحدة مُزالة بالكامل (وليس مجرد تعديل) تظهر مع ذلك في report.html، بحالة deleted: عقدة متقطعة وباهتة تشير إلى مكان وجودها سابقًا. رسم Trailmark البياني لا يمكنه تمثيل هذا بمفرده (إنه يعكس فقط الشجرة كما هي الآن)، لذا يكتشف zairo الحذف بشكل منفصل: كما يحلل الملفات المتغيرة كما كانت موجودة عند --base (أو HEAD، إذا لم يُعطَ --base) ويقارن مجموعتي الرموز. الدالة المحذوفة لا تُرسل أبدًا إلى ماسح LLM (لا يوجد كود حي متبقٍ لفحصه)، لذا تحمل فقط اسمها ونوعها وموقعها السابق، ولا تحمل نتائج أبدًا.

بوابة CI / PR

--fail-on <low|medium|high|critical> يخرج برمز غير صفري إذا وُجدت أي نتيجة عند أو فوق تلك الخطورة (عبر جميع المستودعات مجتمعة، في وضع المستودعات المتعددة)، بحيث يمكن لخطوة CI حظر الدمج عليها. بعض الأمور الجديرة بالمعرفة:

• يظهر خطأ إذا تم دمجه مع --graph-only (لن يكون هناك شيء للبوابة عليه).
• لا يكتم أبدًا إخراج SARIF: لا يزال يُكتب حتى عند فشل البوابة، بحيث تعكس واجهة الفحص الحالة الحالية في كلتا الحالتين.

انظر examples/github-actions/zairo-pr-scan.yml لسير عمل كامل لفحص PR: يشغّل zairo على فرق PR، ويرفع report.sarif إلى فحص كود GitHub، ويفشل المهمة إذا فشلت البوابة.