دليل إثبات JSON (وصفات القالب)

نظرة سريعة

ما: مخرجات أداة الجسر إلى بوابة القرار باستخدام ملفات JSON/YAML واستعلامات JSONPath لماذا: تجنب تنفيذ الشيفرة التعسفية مع تمكين البوابات لأي أداة يمكنها إصدار JSON من: المطورون الذين يدمجون الأدوات (الاختبارات، أدوات التدقيق، الماسحات) مع بوابة القرار المتطلبات المسبقة: أساسيات الشرط (انظر condition_authoring.md)

---

لماذا دليل JSON؟

يوفر الموفر المدمج json إمكانية قراءة ملفات JSON/YAML المحلية وتقييم تعبيرات JSONPath. وهذا يمنحك:

1. عدم تنفيذ الشيفرة في بوابة القرار: DG تقرأ فقط العناصر.
2. تكامل غير مرتبط بالأدوات: يمكن أن يتم التحكم في أي أداة تصدر JSON/YAML.
3. التقييم الحتمي: نفس الملف + نفس JSONPath -> نفس الدليل.

---

أساسيات JSONPath

يستخرج JSONPath القيم من مستند JSON.

JSONPath	المعنى	المثال
$	كائن الجذر	$ (الوثيقة بالكامل)
.field	الوصول إلى حقل الكائن	$.version -> "1.2.3"
.nested.field	الوصول إلى حقل متداخل	$.summary.failed -> 0
[index]	عنصر المصفوفة	$.items[0] -> العنصر الأول
[*]	جميع عناصر المصفوفة	$.items[*].id -> جميع المعرفات
..field	النزول التكراري	$..errors -> جميع حقول errors

مثال على وثيقة JSON:

{
  "version": "1.0",
  "summary": { "failed": 0, "passed": 128 },
  "items": [
    { "id": 1, "status": "pass" },
    { "id": 2, "status": "fail" }
  ]
}

استعلامات مثال:

• $.version -> "1.0"
• $.summary.failed -> 0
• $.items[*].id -> [1, 2]

---

سلوك مطابقة مزود JSON

موفر json يتصرف كما يلي:

• إذا تم حذف params.jsonpath -> يُرجع الوثيقة الكاملة بتنسيق JSON/YAML.
• إذا تطابق JSONPath مع قيمة واحدة -> يُرجع تلك القيمة.
• إذا تطابق JSONPath مع قيم متعددة -> يُرجع مصفوفة من القيم المطابقة.
• إذا لم يتطابق JSONPath مع أي شيء -> يُرجع EvidenceResult.error مع الرمز jsonpath_not_found و value = None.
• إذا كان JSONPath غير صالح -> يُرجع EvidenceResult.error مع الرمز invalid_jsonpath و value = None.

المزود لا يعيد JSON null للمسارات المفقودة؛ بل يعيد لا قيمة (value = None).

---

ملف مزود JSON وقواعد التحليل

• حد حجم الملف: max_bytes (الافتراضي 1_048_576). الحجم الزائد يعيد size_limit_exceeded.
• دعم YAML: مفعل عندما يكون allow_yaml = true وامتداد الملف هو .yaml/.yml.
• Root restriction: root and root_id are required. File paths are relative to root. قيود الجذر: root و root_id مطلوبان. مسارات الملفات هي نسبية لـ root. المسارات المطلقة تعيد absolute_path_forbidden؛ الهروب يعيد path_outside_root.
• المراسي: تستخدم المراسي الدليلية file_path_rooted مع root_id و path النسبي.
• أخطاء التحليل: JSON غير صالح -> invalid_json; YAML غير صالح -> invalid_yaml; YAML معطل -> yaml_disabled.

جميع أخطاء الملف/JSONPath تُعاد عبر EvidenceResult.error (وليس أخطاء JSON-RPC).

---

نمط سير العمل: أداة -> JSON -> بوابة

1. Run tool (outside DG) -> emit JSON file
2. Define condition (json.path + comparator + expected)
3. scenario_next -> DG reads file, extracts value, evaluates condition

مثال على الشرط:

{
  "condition_id": "tests_ok",
  "query": {
    "provider_id": "json",
    "check_id": "path",
    "params": { "file": "test-results.json", "jsonpath": "$.summary.failed" }
  },
  "comparator": "equals",
  "expected": 0,
  "policy_tags": []
}

---

قوالب الوصفات

هذه أمثلة، وليست معايير. استخدمها كنقاط انطلاق.

القالب 1: نتائج الاختبار

أداة الإخراج (مثال):

{
  "summary": { "failed": 0, "passed": 128 },
  "tool": "tests",
  "version": "1.0"
}

شرط:

{
  "condition_id": "tests_ok",
  "query": {
    "provider_id": "json",
    "check_id": "path",
    "params": { "file": "report.json", "jsonpath": "$.summary.failed" }
  },
  "comparator": "equals",
  "expected": 0,
  "policy_tags": []
}

عدم تطابق النوع (السلوك الدقيق):

{ "summary": { "failed": "0" } }

• قيمة الدليل هي سلسلة؛ المتوقع هو رقم.
• equals تعيد false (ليس unknown).

القالب 2: عتبة التغطية

أداة الإخراج (مثال):

{ "coverage": { "percent": 92 } }

شرط:

{
  "condition_id": "coverage_ok",
  "query": {
    "provider_id": "json",
    "check_id": "path",
    "params": { "file": "coverage.json", "jsonpath": "$.coverage.percent" }
  },
  "comparator": "greater_than_or_equal",
  "expected": 85,
  "policy_tags": []
}

عدم تطابق النوع لمقارنات الترتيب:

{ "coverage": { "percent": "92%" } }

• قيمة الدليل هي string، وليست رقمًا أو تاريخ RFC3339.
• greater_than_or_equal يُرجع غير معروف.

القالب 3: ملخص فحص الأمان

أداة الإخراج (مثال):

{ "summary": { "critical": 0, "high": 0, "medium": 2 } }

شرط:

{
  "condition_id": "no_critical",
  "query": {
    "provider_id": "json",
    "check_id": "path",
    "params": { "file": "scan.json", "jsonpath": "$.summary.critical" }
  },
  "comparator": "equals",
  "expected": 0,
  "policy_tags": []
}

القالب 4: عدد الموافقات على المراجعة

أداة الإخراج (مثال):

{ "reviews": { "approvals": 2 } }

شرط:

{
  "condition_id": "approvals_ok",
  "query": {
    "provider_id": "json",
    "check_id": "path",
    "params": { "file": "reviews.json", "jsonpath": "$.reviews.approvals" }
  },
  "comparator": "greater_than_or_equal",
  "expected": 2,
  "policy_tags": []
}

القالب 5: علامات بوليانية صريحة

أداة الإخراج (مثال):

{ "checks": { "lint_ok": true, "format_ok": true } }

شرط:

{
  "condition_id": "lint_ok",
  "query": {
    "provider_id": "json",
    "check_id": "path",
    "params": { "file": "quality.json", "jsonpath": "$.checks.lint_ok" }
  },
  "comparator": "equals",
  "expected": true,
  "policy_tags": []
}

---

تصحيح أدلة JSON بدقة

استخدم evidence_query لأخطاء المزودين

scenario_next لا تُرجع قيم الأدلة أو أخطاء المزود بشكل افتراضي. إذا كان التغذية الراجعة مسموحًا بها، يمكن لـ scenario_next أن تُرجع ملخصات تتبع/أدلة. لتصحيح أخطاء الأدلة بصيغة JSON:

1. استدعِ evidence_query بنفس query وأي context صالح.
2. افحص EvidenceResult.error و evidence_anchor.

رموز أخطاء مزود JSON الشائعة

تأتي هذه الرموز من مزود json المدمج:

• params_missing, params_invalid
• file_not_found, file_open_failed, file_read_failed
• size_limit_invalid, size_limit_exceeded
• invalid_json, invalid_yaml, yaml_disabled
• invalid_jsonpath, jsonpath_not_found
• invalid_root, path_outside_root

قد تعيد مزودون آخرون provider_error (وهو غلاف حول الفشل الداخلي).

---

إرشادات التصميم (أنماط JSON المستقرة)

• احتفظ بالملخصات مسطحة ومستقرة.
• يفضل استخدام المتغيرات العددية (الأرقام، القيم المنطقية) لسهولة المقارنة.
• تجنب التداخل العميق ($.a.b.c.d) ما لم يكن ذلك مطلوبًا.
• قم بتضمين حقل version إذا كنت تتحكم في المخطط وتتوقع التطور.

---

مسارات التعلم المتقاطعة

• getting_started.md -> condition_authoring.md -> هذا الدليل
• هذا الدليل -> provider_development.md (عندما لا يكون JSON كافياً)
• هذا الدليل -> llm_native_playbook.md (عمليات التحقق المسبق)

---

معجم

JSONPath: لغة استعلام لاستخراج القيم من مستندات JSON. Comparator: عامل يقارن الأدلة بالقيم المتوقعة. Evidence: مخرجات المزود بالإضافة إلى البيانات الوصفية (التجزئات، المراجع، الأخطاء). Condition: تعريف فحص الأدلة في سيناريو.