انتقل إلى المحتوى الرئيسي

إعداد بوابات جودة C++ في Cursor: 3 عمليات فحص آلية

Cursor C++ Quality Gate

يتطلب تطوير C++ رقابة جودة صارمة. يوضح لك هذا الدليل كيفية إعداد ثلاث عمليات فحص آلية في Cursor يتم تشغيلها قبل كل عملية التزام: إصدارات البناء المستهدفة وبناءات Sanitizer والتحليل الثابت باستخدام cppcheck. إلى جانب خطاف Git pre-push، تضمن عمليات الفحص هذه أن يكون الكود الخاص بك جاهزًا دائمًا للإنتاج.

عمليات الفحص الثلاث​

فحص 1: البناء المستهدف​

يقوم بتجميع الكود الخاص بك بنفس الإعدادات الموجودة في بيئة النشر الخاصة بك.

فحص 2: بناء Sanitizer​

يقوم بتشغيل AddressSanitizer (ASan) و UndefinedBehaviorSanitizer (UBSan) للتقاط أخطاء الذاكرة والسلوك غير المحدد.

فحص 3: التحليل الثابت​

يستخدم cppcheck للعثور على الأخطاء وانتهاكات الأسلوب والمشكلات المحتملة دون تشغيل الكود.

المتطلبات الأساسية​

قم بتثبيت الأدوات المطلوبة:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y build-essential cmake cppcheck

# macOS
brew install cmake cppcheck

# Windows (عبر MSYS2 أو WSL)
pacman -S mingw-w64-x86_64-cmake mingw-w64-x86_64-cppcheck

هيكل المشروع​

my-cpp-project/
├── src/
│   ├── main.cpp
│   └── utils.cpp
├── include/
│   └── utils.h
├── tests/
│   └── test_main.cpp
├── CMakeLists.txt
├── .cursor/
│   └── quality-gate.sh
└── .git/hooks/
    └── pre-push

الخطوة 1: تكوين CMake​

أنشئ CMakeLists.txt مع ملفات تعريف البناء:

cmake_minimum_required(VERSION 3.14)
project(MyProject CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# ملفات المصدر
add_executable(myapp
    src/main.cpp
    src/utils.cpp
)

target_include_directories(myapp PRIVATE include)

# ملف تعريف البناء المستهدف (مشابه للإنتاج)
add_library(target_profile INTERFACE)
target_compile_options(target_profile INTERFACE
    -O2
    -DNDEBUG
    -Wall
    -Wextra
    -Werror
)

# ملف تعريف بناء Sanitizer
add_library(sanitizer_profile INTERFACE)
target_compile_options(sanitizer_profile INTERFACE
    -O1
    -g
    -fsanitize=address,undefined
    -fno-omit-frame-pointer
)
target_link_options(sanitizer_profile INTERFACE
    -fsanitize=address,undefined
)

# تطبيق ملفات التعريف
option(USE_SANITIZER "Build with sanitizers" OFF)
if(USE_SANITIZER)
    target_link_libraries(myapp sanitizer_profile)
else()
    target_link_libraries(myapp target_profile)
endif()

# الاختبارات
enable_testing()
add_executable(myapp_tests tests/test_main.cpp)
target_link_libraries(myapp_tests target_profile)
add_test(NAME unit_tests COMMAND myapp_tests)

الخطوة 2: برنامج نصي لبوابة الجودة​

أنشئ .cursor/quality-gate.sh:

#!/bin/bash
set -e

PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
BUILD_DIR="$PROJECT_ROOT/build"
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # بدون لون

echo "=========================================="
echo "  Cursor C++ Quality Gate"
echo "=========================================="

# تنظيف دليل البناء
rm -rf "$BUILD_DIR"
mkdir -p "$BUILD_DIR"

# فحص 1: البناء المستهدف
echo -e "\n${YELLOW}[1/3] البناء المستهدف${NC}"
echo "جاري البناء بإعدادات الإنتاج..."
mkdir -p "$BUILD_DIR/target"
cd "$BUILD_DIR/target"
cmake ../.. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)
echo -e "${GREEN}البناء المستهدف: نجح${NC}"

# تشغيل الاختبارات
echo "جاري تشغيل الاختبارات..."
ctest --output-on-failure
echo -e "${GREEN}الاختبارات: نجحت${NC}"

# فحص 2: بناء Sanitizer
echo -e "\n${YELLOW}[2/3] بناء Sanitizer${NC}"
echo "جاري البناء باستخدام AddressSanitizer و UBSan..."
mkdir -p "$BUILD_DIR/sanitizer"
cd "$BUILD_DIR/sanitizer"
cmake ../.. -DCMAKE_BUILD_TYPE=Debug -DUSE_SANITIZER=ON
make -j$(nproc)

echo "جاري التشغيل مع Sanitizer..."
./myapp || {
    echo -e "${RED}اكتشف Sanitizer أخطاء!${NC}"
    exit 1
}
echo -e "${GREEN}بناء Sanitizer: نجح${NC}"

# فحص 3: التحليل الثابت
echo -e "\n${YELLOW}[3/3] التحليل الثابت (cppcheck)${NC}"
cd "$PROJECT_ROOT"

cppcheck \
    --enable=all \
    --suppress=missingIncludeSystem \
    --error-exitcode=1 \
    --inline-suppr \
    --check-config \
    -I include \
    src/ \
    tests/ \
    2>&1 | tee "$BUILD_DIR/cppcheck-report.txt"

echo -e "${GREEN}التحليل الثابت: نجح${NC}"

# ملخص
echo -e "\n=========================================="
echo -e "${GREEN}اجتازت جميع بوابات الجودة!${NC}"
echo "=========================================="
echo "أدوات البناء: $BUILD_DIR/"
echo "التقرير: $BUILD_DIR/cppcheck-report.txt"

اجعله قابلاً للتنفيذ:

chmod +x .cursor/quality-gate.sh

الخطوة 3: خطاف Git Pre-Push​

أنشئ .git/hooks/pre-push:

#!/bin/bash

echo "جاري تشغيل بوابة الجودة قبل الدفع..."

if [ -f ".cursor/quality-gate.sh" ]; then
    bash .cursor/quality-gate.sh
    exit $?
else
    echo "تحذير: لم يتم العثور على برنامج نصي لبوابة الجودة"
    exit 0
fi

اجعله قابلاً للتنفيذ:

chmod +x .git/hooks/pre-push

الخطوة 4: التكامل مع Cursor​

الإضافة إلى مهام Cursor​

أنشئ .vscode/tasks.json (يستخدم Cursor نظام مهام VS Code):

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "C++ Quality Gate",
      "type": "shell",
      "command": "bash",
      "args": [".cursor/quality-gate.sh"],
      "group": {
        "kind": "test",
        "isDefault": true
      },
      "presentation": {
        "echo": true,
        "reveal": "always",
        "focus": false,
        "panel": "shared"
      },
      "problemMatcher": ["$gcc"]
    },
    {
      "label": "Quick Build",
      "type": "shell",
      "command": "cmake",
      "args": ["--build", "build/target", "--parallel"],
      "group": "build"
    },
    {
      "label": "Run Sanitizer Build",
      "type": "shell",
      "command": "bash",
      "args": ["-c", "mkdir -p build/sanitizer && cd build/sanitizer && cmake ../.. -DUSE_SANITIZER=ON && make -j$(nproc) && ./myapp"],
      "group": "test"
    }
  ]
}

اختصارات لوحة المفاتيح​

أضف إلى .vscode/keybindings.json:

[
  {
    "key": "ctrl+shift+q",
    "command": "workbench.action.tasks.runTask",
    "args": "C++ Quality Gate"
  }
]

فهم إخراج Sanitizer​

AddressSanitizer (ASan)​

يكتشف:

  • الاستخدام بعد التحرير
  • تجاوز سعة المخزن المؤقت للكومة
  • تجاوز سعة المخزن المؤقت للمكدس
  • تجاوز سعة المخزن المؤقت العام
  • الاستخدام بعد الإرجاع
  • الاستخدام بعد النطاق
  • التحرير المزدوج
  • تسربات الذاكرة

مثال على الإخراج:

==12345==ERROR: AddressSanitizer: heap-buffer-overflow
READ of size 4 at 0x602000000014 thread T0
    #0 0x5555555551a9 in main src/main.cpp:15

UndefinedBehaviorSanitizer (UBSan)​

يكتشف:

  • تجاوز سعة العدد الصحيح الموقع
  • القسمة على صفر
  • إلغاء مرجع المؤشر الفارغ
  • الوصول إلى مؤشر غير محاذاة
  • عمليات الإزاحة غير الصالحة

مثال على الإخراج:

src/utils.cpp:42:15: runtime error: signed integer overflow

تخصيص cppcheck​

تعليقات الإخفاء​

في الكود الخاص بك:

// cppcheck-suppress unusedFunction
void debugHelper() {
    // يتم استخدام هذا في إصدارات التصحيح فقط
}

// cppcheck-suppress knownConditionTrueFalse
if (x == x) {  // فحص NaN المتعمد
    // معالجة NaN
}

ملف التكوين​

أنشئ cppcheck-suppressions.txt:

unusedFunction:*test*
missingIncludeSystem
unmatchedSuppression

قم بتحديث البرنامج النصي:

cppcheck \
    --enable=all \
    --suppressions-list=cppcheck-suppressions.txt \
    --error-exitcode=1 \
    src/ tests/

تكامل CI/CD​

GitHub Actions​

name: C++ Quality Gate

on: [push, pull_request]

jobs:
  quality-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y build-essential cmake cppcheck
      
      - name: Run Quality Gate
        run: bash .cursor/quality-gate.sh

استكشاف الأخطاء وإصلاحها​

المشكلةالحل
بناء Sanitizer بطيء جدًااستخدم -O1 بدلاً من -O0 للحصول على عمليات بناء أسرع
إيجابيات خاطئة من cppcheckأضف تعليقات إخفاء أو ملف تكوين
الخطاف لا يعملتأكد من أن .git/hooks/pre-push قابل للتنفيذ
نفاد الذاكرة أثناء البناءقلل من المهام المتوازية: make -j2 بدلاً من -j$(nproc)

مرجع سريع​

# تشغيل بوابة الجودة الكاملة
bash .cursor/quality-gate.sh

# البناء المستهدف السريع فقط
mkdir -p build && cd build && cmake .. && make -j$(nproc)

# التشغيل مع Sanitizer
mkdir -p build-san && cd build-san && cmake .. -DUSE_SANITIZER=ON && make -j$(nproc) && ./myapp

# تشغيل cppcheck فقط
cppcheck --enable=all --error-exitcode=1 src/

الموارد ذات الصلة​