DiffCatcher

🎯 الميزات الأساسية

• اكتشاف المستودعات: مسح متكرر للدلائل للبحث عن مستودعات Git مع مرشحات قابلة للتعديل
• تتبع الحالة: التقاط الحالة قبل/بعد السحب مع تجزئات الالتزام والرسائل وكشف التعديلات غير المرسلة
• إنشاء الفروق: إنشاء فرق تلقائي بين الإصدار الحالي والسابق وإنشاء فروق تاريخية مع قوائم الملفات
• استخراج العناصر: تحليل الفروق لتحديد الدوال، الهياكل، الكلاسات، الاستيرادات، والمزيد عبر أكثر من 10 لغات
• مقتطفات الكود: استخراج نصوص كاملة قبل/بعد مع اكتشاف الحدود ونوافذ السياق
• وضع العلامات الأمنية: 18 نمطًا أمنيًا مدمجًا (التشفير، المصادقة، الأسرار، حقن SQL، XSS، إلخ.)
• تقارير متعددة التنسيقات: مخرجات JSON وMarkdown ونص وSARIF مع نظرة عامة أمنية عبر المستودعات
• وضع الفرق بين الفروع: مقارنة أي مرجعين (فروع، علامات، التزامات) في مستودع واحد — مثالي لمراجعات طلبات السحب
• الأداء: معالجة متوازية مع أشرطة تقدم، تخزين مؤقت LRU، ووضع تدريجي

لماذا لا تستخدم bash فقط؟

سطر واحد مثل ls | while read line; do git -C "$line" diff HEAD~1 HEAD || true; done يُظهر الفروق الخام فقط. يضيف DiffCatcher اكتشافًا متكررًا، واستخراج عناصر الكود، واكتشاف الأنماط الأمنية، ومخرجات SARIF للتكامل المستمر/النشر المستمر، ومعالجة متوازية، وتجميع أمني عبر المستودعات. انظر المقارنة الكاملة أدناه.

📋 جدول المحتويات

• التثبيت
• بداية سريعة
• الاستخدام
  • المسح الأساسي
  • أوضاع السحب
  • خيارات الاستخراج
  • وضع العلامات الأمنية
  • ملف التكوين
  • نظام الإضافات
  • وضع الفرق بين الفروع (مراجعة طلب السحب)
  • مخرجات SARIF
  • الميزات المتقدمة
• هيكل التقرير
• التكوين
• الهيكل المعماري
• الاختبار
• التوثيق
• المساهمة

🚀 التثبيت

من المصدر

git clone https://github.com/Teycir/DiffCatcher.git
cd DiffCatcher
cargo build --release
./target/release/diffcatcher --help

المتطلبات

• Rust 1.70+
• Git 2.0+

⚡ بداية سريعة

# Scan all repos in a directory (fetch-only, no modifications)
diffcatcher ~/projects

# Pull updates and generate security report
diffcatcher ~/projects --pull -o ./report

# Diff two branches in a single repo (PR review mode)
diffcatcher ./my-repo --diff main..feature/auth -o ./pr-report

# Generate SARIF output for GitHub Code Scanning
diffcatcher ~/projects --summary-format sarif,json -o ./report

# Dry run to see what would be scanned
diffcatcher ~/projects --dry-run

# Fast scan with 8 parallel workers
diffcatcher ~/projects -j 8 --quiet

📖 الاستخدام

المسح الأساسي

# Scan with default settings (fetch-only)
diffcatcher <ROOT_DIR>

# Custom output directory
diffcatcher ~/projects -o ./my-report

# Include nested repos and follow symlinks
diffcatcher ~/projects --nested --follow-symlinks

# Skip hidden directories
diffcatcher ~/projects --skip-hidden

أوضاع السحب

# Fetch only (default - no working tree changes)
diffcatcher ~/projects

# Actually pull changes
diffcatcher ~/projects --pull

# Force pull with stash/pop for dirty repos
diffcatcher ~/projects --pull --force-pull

# Use rebase strategy
diffcatcher ~/projects --pull --pull-strategy rebase

# Skip fetch/pull entirely (historical diffs only)
diffcatcher ~/projects --no-pull

خيارات الاستخراج

# Skip element extraction (raw diffs only)
diffcatcher ~/projects --no-summary-extraction

# Extract elements but skip code snippets
diffcatcher ~/projects --no-snippets

# Adjust snippet context and limits
diffcatcher ~/projects --snippet-context 10 --max-snippet-lines 300

# Limit elements per diff
diffcatcher ~/projects --max-elements 1000

وضع العلامات الأمنية

# Skip security tagging
diffcatcher ~/projects --no-security-tags

# Include test files in security analysis
diffcatcher ~/projects --include-test-security

# Use custom security patterns
diffcatcher ~/projects --security-tags-file ./custom-patterns.json

ملف التكوين

يمكن لـ DiffCatcher تحميل التكوين المحلي للمشروع تلقائيًا من:

• <ROOT_DIR>/.diffcatcher.toml (افتراضي)
• ملف مخصص عبر --config <FILE>
• تعطيله بـ --no-config

مثال:

output = "reports-local"
no_pull = true
history_depth = 2
summary_formats = ["json", "txt"]
no_security_tags = false

[plugins]
security_pattern_files = ["plugins/security-extra.json"]
extractor_files = ["plugins/extractors.json"]

لا تزال أعلام سطر الأوامر تتجاوز قيم التكوين عند ضبطها صراحةً.

نظام الإضافات

يدعم DiffCatcher نوعين من الإضافات:

• إضافات الأنماط الأمنية عبر --security-plugin-file <FILE> (قابل للتكرار)
• إضافات الاستخراج عبر --extractor-plugin-file <FILE> (قابل للتكرار)

تنسيق إضافة الأمان يطابق JSON الخاص بـ --security-tags-file (version، mode، tags).

تنسيق إضافة الاستخراج:

{
  "version": 1,
  "extractors": [
    {
      "name": "policy-rule",
      "kind": "Config",
      "regex": "^policy\\s+([A-Za-z_][A-Za-z0-9_]*)"
    }
  ]
}

وضع الفرق بين الفروع (مراجعة طلب السحب)

# Diff two branches in a single repo
diffcatcher ./my-repo --diff main..feature/auth

# Diff specific commits
diffcatcher ./my-repo --diff abc123..def456

# Diff with SARIF output for CI integration
diffcatcher ./my-repo --diff origin/main..HEAD --summary-format sarif -o ./pr-report

العلم --diff BASE..HEAD يتجاوز اكتشاف المستودع وسحب البيانات — فهو يقارن مباشرة بين مرجعين (فروع، علامات، أو تجزئات التزامات) ويشغل مسار الاستخراج الكامل + وضع العلامات الأمنية على النتيجة.

مخرجات SARIF

# Generate SARIF alongside other formats
diffcatcher ~/projects --summary-format sarif,json,md

# SARIF-only for CI/CD upload
diffcatcher ~/projects --summary-format sarif -o ./report

عند تضمين sarif في --summary-format، يتم كتابة ملف results.sarif في جذر التقرير. يتبع هذا الملف معيار SARIF 2.1.0 ويتكامل مع فحص كود GitHub، وعارض SARIF لـ VS Code، وAzure DevOps، وأدوات أخرى متوافقة مع SARIF.

الميزات المتقدمة

# Incremental mode (skip unchanged repos)
diffcatcher ~/projects --incremental -o ./report

# Filter by branch pattern
diffcatcher ~/projects --branch-filter "main"

# Adjust history depth
diffcatcher ~/projects --history-depth 5

# JSON output for CI/CD
diffcatcher ~/projects --quiet --json > result.json

# Verbose output with discovered paths
diffcatcher ~/projects --verbose

📁 هيكل التقرير