بُرهان | Burhan Engine

Evidence-first software diagnosis and repair verification for Python and TypeScript.

بُرهان محرك تشخيص وإثبات إصلاح يحوّل هدف المستخدم والكود ورسالة الخطأ إلى حالة BIR مترابطة، ثم يرتب فرضيات السبب الجذري باستخدام الأدلة بدل التخمين.

python -m pip install burhan-engine
burhan --help

• يشخّص الأخطاء ويعرض الأدلة والمخاطر المتبقية.
• ينشئ معاينة إصلاح صغيرة من دون تغيير الأصل افتراضيًا.
• يثبت انتقال الاختبار من الفشل إلى النجاح داخل Docker مع عزل وحدود موارد.

PyPI · Docker image · Releases · License · Security policy

هذه النسخة 0.7.1 توفر Burhan Evidence Gate: بوابة CI تطبق سياسة مؤسسية على إثبات الإصلاح وتصدر تقرير قرار منقحًا وقابلًا للأرشفة. التحليل يعمل محليًا ولا يرسل ملفات مشروعك إلى أي خدمة، وجامع المصادر يتصل فقط بمضيفي SWE-bench وGitHub المسموحين صراحة ولا يحتاج مفاتيح API.

حقوق النشر © 2026 مساهمو Burhan Engine. بُرهان برنامج حر ومفتوح المصدر مرخص بموجب AGPL-3.0-only. إذا وزعت نسخة معدلة، أو أتحت نسخة معدلة ليتفاعل معها المستخدمون عبر شبكة، فيجب أن تتيح لهم المصدر المقابل لتلك النسخة وفق شروط الترخيص.

البدء السريع (أسهل طريق)

1) تثبيت الأداة محليًا (PyPI/Editable)

python -m pip install burhan-engine
burhan --help

وللتطوير المحلي من المستودع:

python -m pip install -e .
burhan --version

2) تشغيل موحد بالأمر burhan

تحليل فقط:

burhan analyze --project PATH_TO_PROJECT --goal "شخّص الخطأ" --error-file PATH_TO_ERROR.txt

معاينة إصلاح:

burhan repair --project PATH_TO_PROJECT --goal "أصلح الخطأ بأقل تعديل" --error-file PATH_TO_ERROR.txt

إثبات الإصلاح:

burhan repair-proof --project PATH_TO_PROJECT --goal "أثبت الإصلاح" --error-file PATH_TO_ERROR.txt --trust-local-tests

3) تشغيل عبر Docker بدون إعداد Python محلي

اسحب الصورة المنشورة:

docker pull ghcr.io/mwthrc23-ui/burhan-engine:0.7.1

ثم شغّل أي أمر burhan داخلها (مع mount للمشروع):

docker run --rm -v "$PWD:/workspace" -w /workspace ghcr.io/mwthrc23-ui/burhan-engine:0.7.1 analyze --project examples/python-name-error --goal "شخّص الخطأ" --error-file examples/python-name-error/error.txt

Burhan Evidence Gate للفرق وCI

يشغّل ci-gate التحليل والإثبات بنفسه؛ لا يقبل ملف ProofResult يقدمه المستخدم. ثم يطبق سياسة JSON صارمة ويكتب تقريرًا لا يحتوي الكود أو رسالة الخطأ الخام أو فرق الرقعة أو أمر الاختبار أو stdout/stderr.

burhan ci-gate \
  --project . \
  --goal "أثبت الإصلاح دون تغيير الأصل" \
  --error-file failure.txt \
  --policy examples/ci-policy-v2.json \
  --report burhan-gate-report.json \
  --trust-local-tests \
  --test-program python \
  --test-arg app.py \
  --backend docker \
  --json

عقد رموز الخروج:

• 0: الإثبات اجتاز جميع قواعد السياسة.
• 1: التنفيذ صالح لكن الإثبات أو السياسة رفضا الإصلاح؛ يُكتب تقرير رفض عند تحديد --report.
• 2: إعداد أو بنية تحتية أو مسار تقرير غير صالح.

سياسة البوابة محدودة إلى 64 KiB، ترفض الحقول والقيم المكررة أو المجهولة، ولا تسمح بتعطيل اكتمال المسح أو ثبات المشروع الأصلي. تقرير JSON يحمل بصمة للسياسة وبصمة ذاتية للمحتوى، ويربط بصمات منقحة لأمر الاختبار وبيئة التشغيل وmanifest كامل لمدخلات المشروع دون كشف قيمها الخام. يمكن للسياسة تثبيت الأمر والبيئة عبر allowed_command_fingerprints وallowed_runtime_fingerprints لمنع استبدال الاختبار باختبار أضيق أو تغيير Docker digest. هذه البصمات checksums لكشف التغيير وليست توقيعًا رقميًا أو إثباتًا لهوية المنشئ. مسار --report يجب أن يكون ملفًا جديدًا بلاحقة .json، ولا يستبدل ملفًا أو رابطًا رمزيًا موجودًا.

سياسة المثال مثبتة للأمر python app.py ولصورة Python المبينة أدناه. إذا تغير الأمر أو digest، احسب القيم الجديدة من الدالتين burhan.policy.fingerprint_command وfingerprint_runtime وحدّث السياسة المحمية. كما يبني الإثبات manifest مؤطرًا قبل التحليل وبعده (حتى 15,000 عنصر و10,000 ملف و250 MB)، ويرفض التشغيل إذا تغير المشروع بين التحليل والإثبات أو تغير المحتوى أو البنية أو الصلاحيات أثناء الاختبار. ملفات الأسرار لا تُقرأ؛ يسمح Docker/V2 بمراقبة metadata لها لأن المشروع الأصلي غير مركب داخل الحاوية، بينما يرفض local/V1 المشروع إذا اكتشف ملف أسرار لأنه لا يستطيع تقديم ضمان قوي دون قراءته. ويُرفض أي هدف داخل مجلد مستبعد من المسح قبل تشغيل الاختبار، كما تقبل صورة Docker صيغة OCI آمنة مثبتة فقط ولا يمكن أن تبدأ كخيار CLI.

مهم في Pull Requests غير الموثوقة: لا تحمل السياسة من فرع المساهم. انسخها من فرع محمي أو من RUNNER_TEMP بعد التحقق من بصمتها، ثم ارفع التقرير كـartifact. اجعل workflow نفسه فحصًا إلزاميًا ومحميًا عبر GitHub Ruleset حتى لا يستطيع PR تعديل خطوة البوابة وتجاوزها. الإعداد الافتراضي يتطلب V2 وDocker؛ تشغيل local/V1 مخصص فقط لمشروع واختبارات موثوقة لأنه ليس عزلًا أمنيًا.

يجب كذلك فصل أداة بُرهان الموثوقة عن المستودع الجاري تحليله: في workflow المحمي ثبّت نسخة منشورة ومثبتة من burhan-engine أو wheel من بناء محمي، ولا تثبّت بُرهان من checkout الخاص بالـPR. في البيئات عالية الحساسية استخدم --require-hashes مع بصمة wheel المنشورة.

مثال GitHub Actions مختصر:

- name: Install Burhan and preload pinned proof image
  env:
    BURHAN_DOCKER_IMAGE: python@sha256:57cd7c3a7a273101a6485ba99423ee568157882804b1124b4dd04266317710de
  run: |
    python -m pip install --only-binary=:all: --no-deps "burhan-engine==0.7.1"
    docker pull "$BURHAN_DOCKER_IMAGE"
- name: Load protected Burhan policy
  env:
    BASE_SHA: ${{ github.event.pull_request.base.sha }}
    EXPECTED_POLICY_SHA256: ${{ vars.BURHAN_POLICY_SHA256 }}
  run: |
    git fetch origin "$BASE_SHA" --depth=1
    git show "$BASE_SHA:examples/ci-policy-v2.json" > "$RUNNER_TEMP/burhan-policy.json"
    actual="$(sha256sum "$RUNNER_TEMP/burhan-policy.json" | cut -d ' ' -f 1)"
    test -n "$EXPECTED_POLICY_SHA256" && test "$actual" = "$EXPECTED_POLICY_SHA256"
- name: Run Burhan Evidence Gate
  env:
    BURHAN_DOCKER_IMAGE: python@sha256:57cd7c3a7a273101a6485ba99423ee568157882804b1124b4dd04266317710de
  run: |
    burhan ci-gate --project . --goal "أثبت الإصلاح" \
      --error-file "$RUNNER_TEMP/failure.txt" \
      --policy "$RUNNER_TEMP/burhan-policy.json" \
      --report "$RUNNER_TEMP/burhan-report.json" \
      --trust-local-tests --test-program python --test-arg app.py \
      --backend docker --docker-image "$BURHAN_DOCKER_IMAGE" --json
- name: Upload Burhan report
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: burhan-evidence-report
    path: ${{ runner.temp }}/burhan-report.json

تجربة كاملة بنقرة واحدة

يشغّل الأمر التالي التجربة على نسخة مؤقتة: تحليل الخطأ، معاينة patch، تطبيقه، ثم تشغيل الكود المصحح. لا يغيّر ملف المثال الأصلي.

git clone https://github.com/mwthrc23-ui/burhan-engine.git
cd burhan-engine
powershell -ExecutionPolicy Bypass -File scripts\try-burhan.ps1

ما يعمل الآن

• فهرسة آمنة ومحدودة لملفات Python وTypeScript/JavaScript وبعض ملفات الإعداد والتوثيق.
• استبعاد .env والمفاتيح الخاصة ومجلدات .git وnode_modules والبناء والتغطية.
• استخراج رموز Python عبر AST، واستخراج أولي لرموز TypeScript/JavaScript.
• تشخيص أخطاء Python: NameError وUnboundLocalError وAttributeError وModuleNotFoundError / ImportError وSyntaxError وTypeError (عدد وسطاء غلط، كائن غير قابل للاستدعاء، عملية غير مدعومة، عام) وValueError وIndexError وKeyError وZeroDivisionError وRecursionError وFileNotFoundError / OSError.
• تشخيص أخطاء TypeScript: TS2304 (اسم غير معروف) وTS2322 (تعارض نوع) وTS2339 (خاصية مفقودة) وTS2345 (نوع وسيط غير متوافق) وTS2554 (عدد وسطاء غلط).
• اقتراح رمز قريب عند وجود خطأ إملائي في اسم Python أو TypeScript.
• إخراج بشري عربي أو JSON يتضمن BIR والأدلة والثقة والطاقة وزمن التحليل.
• رقم قضية ثابت وبصمة SHA-256 ومدى اكتمال المسح والمخاطر المتبقية.
• استخراج القيود الصريحة من الهدف، مثل «لا تغيّر الواجهة».
• أمر repair ينشئ unified diff ويمنحه درجة V0 بعد فحص النطاق والسطر وصياغة Python؛ يدعم إصلاح NameError وUnboundLocalError عند توفر رمز بديل قريب.
• أمر repair-proof يعيد الاختبار نفسه قبل الرقعة وبعدها داخل نسخة مؤقتة.
• يمنح V2 عند تحقق fail-to-pass داخل Docker بشبكة معطلة وحدود موارد وملفات للقراءة فقط.
• المعاينة هي الوضع الافتراضي؛ الكتابة تحتاج الخيار الصريح --apply.
• التوقف وطلب دليل إضافي بدل اختراع سبب غير مدعوم.
• قراءة حالات RepairEpisode الموثقة مسبقًا من SQLite؛ إدخال ملفات JSON عبر CLI معطل مؤقتًا حتى يمكن إعادة إثباتها وربطها بالحالة والرقعة.
• البحث عن حالات مشابهة حسب النوع والرمز لأكثر من 11 نوع خطأ مصنّف.
• ربط نتائج ذاكرة الإصلاح بالتشخيص الجديد عبر analyze --memory.
• جمع حالات حقيقية محدودة من SWE-bench Verified مع الوصف والرقعة ورقعة الاختبار وFAIL_TO_PASS، مع تصنيف تلقائي لأنواع الأخطاء (attribute_error_candidate، name_error_candidate، module_error_candidate، إلخ).
• جمع حزمة BugsInPy المحددة مع commit والرقعة وأمر الاختبار، من دون تنفيذ أي كود وارد من المصدر.
• جمع Pull Request محدد من GitHub مع الوصف والرقع كـsource_record خام غير مرقى، مع كشف تلقائي لنوع الخطأ من وصف PR.
• فصل source_records الخام عن repair_episodes الموثقة، ومنع الحالة غير المصنفة من الظهور كإصلاح موثوق.
• حفظ تغيرات المصدر كسجل نسخ append-only يعتمد على SHA-256 بدل استبدال الدليل السابق بصمت.
• استرجاع رقعة واختبار مشابهين عبر source-search مع وسم صريح بأنها مرشحة لم تُختبر محليًا.
• شجرة الكود code-tree: أمر يعرض هيكل المشروع الهرمي (مجلدات وملفات ورموز) نصًا أو JSON، مع تضمين دوال الأصناف بشكل متداخل داخل عقدة الصنف.
• تضمين شجرة الكود في التحليل: يُرفق أمر analyze شجرة الكود تلقائيًا بنتيجة التحليل؛ استخدم --code-tree لعرضها في المخرجات البشرية.

شجرة الكود

تُبنى شجرة الكود عند كل تحليل وتُضمَّن في نتيجة analyze. يمكن عرضها مستقلة بأمر code-tree، أو مضمّنة مع التحليل باستخدام --code-tree.

عرض الشجرة المستقلة

burhan code-tree --project PATH_TO_PROJECT

تضمينها مع أمر التحليل

burhan analyze --project PATH_TO_PROJECT --goal "شخّص الخطأ" --error-file error.txt --code-tree

مثال على الإخراج (الدوال متداخلة داخل الأصناف):

\-- my-project [directory]
    |-- src [directory]
    |   \-- app.py
    |       |-- MyClass [class]
    |       |   |-- __init__ [function]
    |       |   \-- process [function]
    |       \-- helper [function]
    \-- tests [directory]
        \-- test_app.py

لتحديد أقصى عمق للشجرة:

burhan code-tree --project PATH_TO_PROJECT --depth 2

لإخراج JSON قابل للمعالجة:

burhan code-tree --project PATH_TO_PROJECT --json

ذاكرة الإصلاح

النطاق الأول مقيد عمدًا إلى:

Python + pytest + AttributeError

أمرا memory-add وmemory-promote معطلان مؤقتًا. لا يقبل CLI ملفات RepairEpisode أو ProofResult المقدمة من المستخدم بوصفها دليلًا موثوقًا حتى يستطيع ProofRunner إعادة تنفيذ اختبار AttributeError وربط النتيجة بالحالة والرقعة نفسها. يبقى البحث في قاعدة موثقة مسبقًا متاحًا. يجب أن يشير --database إلى قاعدة موجودة ومعبأة من مسار موثوق؛ لا ينشئ المثال بيانات:

ابحث عن حالة مشابهة:

python -m burhan memory-search `
  --database C:\path\to\preverified-memory.sqlite3 `
  --error-file examples\repair-memory\error.txt `
  --language python `
  --framework pytest `
  --dependency demo-client

اربط الذاكرة بتحليل مشروع جديد:

python -m burhan analyze `
  --project examples\repair-memory\project `
  --goal "شخّص الخطأ باستخدام ذاكرة الإصلاح" `
  --error-file examples\repair-memory\error.txt `
  --memory C:\path\to\preverified-memory.sqlite3 `
  --dependency demo-client

ملفات المثال المرفقة اصطناعية وموسومة source_type=synthetic، وليست منسوبة إلى GitHub ولا تُحمّل تلقائيًا في الذاكرة الموثوقة.

جمع الأخطاء الحقيقية

اجمع أول 100 سجل من SWE-bench Verified. لا يُحفظ منها في النطاق الحالي إلا ما يحتوي رسالة AttributeError، وتبقى الحالات في جدول خام حتى مراجعة السبب وإعادة التحقق:

$env:PYTHONPATH = "$PWD\src"
python -m burhan source-import-swebench `
  --database data\repair-memory.sqlite3 `
  --offset 0 `
  --length 100

اجمع حالة BugsInPy محددة. تُحفظ الرقعة وأمر الاختبار كنص ولا يشغّل بُرهان run_test.sh:

python -m burhan source-import-bugsinpy `
  --database data\repair-memory.sqlite3 `
  --project PySnooper `
  --bug 1

اجمع Pull Request محددًا من GitHub. هذا يحفظ الوصف ورقع الملفات ورقع الاختبارات إن وجدت، لكنه يبقى unclassified لأن GitHub وحده لا يثبت سبب الخطأ ولا نجاح الاختبار:

python -m burhan source-import-github-pr `
  --database data\repair-memory.sqlite3 `
  --repo astropy/astropy `
  --pr 7336

استرجع نمطًا مشابهًا لخطأ جديد:

python -m burhan source-search `
  --database data\repair-memory.sqlite3 `
  --error "AttributeError: 'NoneType' object has no attribute 'to'" `
  --json

يعيد JSON الوصف وsolution_patch وtest_patch وأمر الاختبار والمصدر. الحقل proposal_status=source_candidate_not_locally_verified يمنع الخلط بين رقعة مصدر سابقة وإصلاح ثبت نجاحه على مشروعك الحالي. ويُخزن root_cause_status=unknown عندما لا يصرح المصدر بالسبب بدل اختلاقه. دليل SWE-bench المستورد موسوم SOURCE_ATTESTED وليس V2 محليًا.

للتجربة المتسلسلة:

powershell -ExecutionPolicy Bypass -File scripts\try-source-memory.ps1

ترخيص مجموعة البيانات وترخيص المشروع الأصلي حقلا مصدر منفصلان؛ لا يفترض بُرهان أن ترخيص SWE-bench ينطبق على رقعة المستودع الأصلي.

تحليل فقط

يتطلب Python 3.11 أو أحدث.

git clone https://github.com/mwthrc23-ui/burhan-engine.git
cd burhan-engine
$env:PYTHONPATH = "$PWD\src"
python -m burhan analyze `
  --project examples\python-name-error `
  --goal "أصلح الخطأ بأقل تعديل" `
  --error-file examples\python-name-error\error.txt

لإخراج JSON أضف --json.

معاينة إصلاح

python -m burhan repair `
  --project examples\python-name-error `
  --goal "أصلح الخطأ بأقل تعديل ولا تغيّر الواجهة" `
  --error-file examples\python-name-error\error.txt

لا يكتب هذا الأمر شيئًا. لتطبيق التعديل بعد مراجعة الفرق:

python -m burhan repair `
  --project PATH_TO_PROJECT `
  --goal "أصلح الخطأ بأقل تعديل" `
  --error-file PATH_TO_ERROR.txt `
  --apply

إثبات الإصلاح داخل Docker

شغّل التجربة الجاهزة:

docker pull "python@sha256:57cd7c3a7a273101a6485ba99423ee568157882804b1124b4dd04266317710de"
powershell -ExecutionPolicy Bypass -File scripts\try-repair-proof.ps1

أو شغّل الأمر مباشرة:

$env:PYTHONPATH = "$PWD\src"
python -m burhan repair-proof `
  --project examples\python-name-error `
  --goal "أثبت الإصلاح دون تغيير الأصل" `
  --error-file examples\python-name-error\error.txt `
  --trust-local-tests `
  --backend docker `
  --docker-image "python@sha256:57cd7c3a7a273101a6485ba99423ee568157882804b1124b4dd04266317710de" `
  --test-program python `
  --test-arg app.py `
  --json

يشترط V2 أن يطابق فشل البداية الخطأ والرمز والموقع اللذين شخّصهما بُرهان، ثم ينجح الاختبار نفسه بعد الرقعة داخل الحاوية، وأن تبقى بصمة الملف الأصلي كما هي. لا يطبق الأمر الرقعة على مشروع المستخدم، ولا ينسخ ملفات الأسرار الشائعة إلى مساحة الإثبات. صورة Docker المثبتة بـsha256 إلزامية، ويستخدم التشغيل --pull never لمنع تبدّلها أثناء الإثبات. خيار --trust-local-tests إلزامي لأن الاختبار نفسه كود تنفيذي، ولا يشغّل بُرهان اختبارات السجلات الخارجية تلقائيًا.

ويمكن تثبيت الأمر محليًا في بيئة افتراضية:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .
burhan analyze --help

الاختبارات

$env:PYTHONPATH = "$PWD\src"
python -m unittest discover -s tests -v

نموذج BIR الحالي

تتكون الحالة من عقد وحواف غير قابلة للتغيير:

• عقد: هدف، قيد، ملف، رمز، حدث خطأ، فرضية، ودليل.
• حواف: يعرّف، يستجيب إلى، يتطلب، ويدعم.
• كل قضية تحمل بصمة للمدخلات ومصدرًا يوضح إصدار المحرك وعدد الملفات وحالة اكتمال المسح.
• كل فرضية تحمل طاقة أقل كلما زادت الأدلة وقل حجم التغيير وعدم اليقين.

هذه دالة ترتيب هندسية مستوحاة من نموذج أقل طاقة؛ ليست تنفيذًا كموميًا بعد.

درجات الإثبات

شهادة V0 الحالية تعني أن:

• الملف المستهدف داخل المشروع.
• الرمز يظهر مرة واحدة فقط في السطر الذي حدده التتبع.
• التعديل يغير هذا الرمز وحده.
• ملف Python الناتج ينجح في تحليل AST.

لا تعني V0 أن السلوك صحيح أو أن اختبارات المشروع نجحت.

• V1: فشل مطابق للتشخيص انتقل إلى النجاح في نسخة محلية مؤقتة موثوقة.
• V2: الانتقال نفسه تحقق داخل Docker بصورة مثبتة ببصمة، مع --network none وقيود موارد وإسقاط capabilities وmount للقراءة فقط.
• لا تثبت V1/V2 السبب الجذري وحده؛ بل تثبت أن الرقعة غيّرت نتيجة الاختبار المحدد من الفشل إلى النجاح.

الحدود الحالية

• يطبق الإصلاح حاليًا فقط لخطأ اسم Python عندما يوجد رمز بديل قريب وموقع سطر واضح.
• تحليل TypeScript للرموز أولي ولا يستخدم Tree-sitter أو TypeScript compiler بعد.
• إثبات Docker الحالي يحتاج صورة تحتوي أداة الاختبار المطلوبة؛ صورة Python الافتراضية مناسبة لاختبارات python المباشرة، بينما يحتاج pytest إلى صورة تتضمن pytest.
• بيانات SWE-bench Verified تحمل رقعة واختبارات معيارية، لكن استيرادها لا يعني أنها نجحت على كود المستخدم الحالي.
• سجلات BugsInPy غالبًا لا تتضمن وصفًا صريحًا للخطأ أو السبب، ولذلك تبقى unclassified حتى المراجعة.
• لا يوجد نموذج لغوي أو QUBO/Ising backend في هذه النسخة.
• هدف أقل من ثانية يخص أول تشخيص في مشروع ضمن حدود المسح، وليس ضمان حل نهائي لكل مشكلة.

المرحلة التالية

1. استعادة بوابة الترقية بإعادة إثبات AttributeError وربط ProofResult بالحالة والرقعة، مع سبب من المصدر أو مراجعة بشرية موثقة وإثبات V2.
2. إعادة نتيجة الاختبار إلى BIR كدليل جديد قابل للاسترجاع.
3. بناء صورة تحقق pytest مثبتة بالاعتماديات وdigest.
4. إضافة فهرسة متزايدة بـTree-sitter وLSP.