دليل التطوير

الإعداد

# Clone and install dev dependencies
git clone https://github.com/f5-sales-demo/api-specs.git
cd api-specs
make dev-install

# Install Spectral CLI (required for linting stages)
npm install -g @stoplight/spectral-cli

يقوم make dev-install بإنشاء بيئة افتراضية في .venv/ ويثبّت المشروع مع الحزم الإضافية للتطوير (pytest، ruff، mypy).

متغيرات البيئة

يتطلب التحقق المباشر من واجهة برمجة التطبيقات ما يلي:

export F5XC_API_URL="https://example-tenant.console.ves.volterra.io"
export F5XC_API_TOKEN="your-api-token"

بدون هذه المتغيرات، يعود make validate إلى وضع التشغيل التجريبي (dry-run).

تشغيل خط الأنابيب

خط الأنابيب الكامل

make all
# Runs: download → validate → spectral-lint → reconcile → spectral-gate → release

المراحل الفردية

make download        # Fetch upstream specs
make validate        # Run live API tests (requires API token)
make validate-dry    # Dry run (no API calls)
make spectral-lint   # Spectral discover mode on original specs
make reconcile       # Apply fixes from both reports
make spectral-gate   # Spectral quality gate on reconciled specs
make release         # Build release package

التوثيق

make docs-generate   # Regenerate docs/01-validation-report.mdx from reports
make docs            # Build full documentation site
make docs-serve      # Local dev server with hot reload

تشغيل الاختبارات

make test           # pytest with coverage
make lint           # ruff check + format check
make typecheck      # mypy type checking
make ci-test        # All three (used in CI)

تعمل خطافات ما قبل الالتزام (pre-commit hooks) تلقائيًا عند كل التزام إذا تم تثبيتها:

make pre-commit-install   # Install git hooks
make pre-commit           # Run all hooks manually

هيكل المشروع

scripts/
  download.py           # Stage 1: Fetch specs from F5
  validate.py           # Stage 2: Live API testing
  spectral_lint.py      # Stage 3/5: Spectral linting adapter
  reconcile.py          # Stage 4: Apply fixes to specs
  release.py            # Stage 6: Package release
  generate_docs.py      # Generate MDX from reports
  utils/
    auth.py             # F5 XC API authentication
    constraint_validator.py  # Constraint testing + Discrepancy types
    report_generator.py      # Report formatting
    schemathesis_runner.py   # Schemathesis test orchestration
    spec_loader.py           # Spec I/O + JSON formatting

config/
  validation.yaml       # Pipeline configuration
  endpoints.yaml        # Baseline endpoints for live testing

spectral/
  functions/
    f5-path-params.js   # Custom Spectral function

docs/                   # Starlight MDX documentation
tests/                  # pytest test suite
release/specs/          # Output: reconciled spec files
reports/                # Output: validation and Spectral reports

إضافة طريقة إصلاح جديدة

لإضافة إصلاح تلقائي جديد لـ Spectral إلى أداة التوفيق (reconciler):

أضف القاعدة إلى .spectral.yaml مع مستوى الخطورة المطلوب.
فعّل الإصلاح التلقائي في config/validation.yaml تحت spectral.auto_fix:
```
spectral:
  auto_fix:
    your-new-rule: true
```

أضف طريقة الإصلاح إلى SpecReconciler في scripts/reconcile.py:

def _fix_your_rule(self, spec: dict, discrepancy: Discrepancy) -> dict | None:
    """Fix description."""
    # Modify spec in place
    # Return spec if changed, None if no change needed
    return spec

سجّلها في موزّع _apply_spectral_fix:

spectral_fixers = {
    # ... existing fixers ...
    "spectral:your-new-rule": self._fix_your_rule,
}

أضف اختبارات تغطي طريقة الإصلاح الجديدة.

إضافة قاعدة Spectral جديدة

لإضافة قاعدة Spectral مخصصة مع دالة JavaScript:

أنشئ الدالة في spectral/functions/your-rule.js. قم بتصدير دالة افتراضية تستقبل (targetVal, options, context) وتُرجع مصفوفة من كائنات {message, path}.

سجّلها في spectral-pipeline.yaml:

functions:
  - f5-path-params
  - your-rule

rules:
  your-rule:
    description: "What it checks"
    message: "{{error}}"
    severity: error
    given: "$.paths[*]"
    then:
      function: your-rule

خط أنابيب التكامل المستمر (CI)

يعمل سير عمل GitHub Actions (validate-and-release.yml) في الحالات التالية:

مجدول: يوميًا في الساعة 6 صباحًا بتوقيت UTC
الدفع إلى main: عند تغيير scripts/ أو config/ أو pyproject.toml
التشغيل اليدوي: مع خيارات للإصدار الإجباري أو التشغيل التجريبي

يحتوي سير العمل على أربع مهام:

validate — تنزيل المواصفات، تشغيل التحقق، فحص Spectral، التوفيق، بوابة جودة Spectral
check-release-needed — مقارنة تجزئات المحتوى لتحديد ما إذا كان الإصدار مطلوبًا
release — تجميع وإنشاء إصدار GitHub (فقط إذا تغيّر المحتوى)
update-docs — إعادة إنشاء 01-validation-report.mdx وفتح طلب سحب (PR) إذا تغيّر

تقوم مهمة notify بإنشاء تذكرة (issue) على GitHub إذا فشلت أي مهمة.

سير عمل الفروع وطلبات السحب

تتبع جميع التغييرات النمط التالي: تذكرة -> فرع -> طلب سحب -> نجاح CI -> دمج.

أسماء الفروع: feature/<issue>-desc، fix/<issue>-desc، docs/<issue>-desc
يجب أن تربط طلبات السحب بتذكرة (Closes #N في الوصف)
فحوصات CI المطلوبة: Check linked issues و Lint Code Base
يُفضّل الدمج بالضغط (squash merge)؛ تُحذف الفروع تلقائيًا بعد الدمج

راجع CONTRIBUTING.md للاطلاع على قواعد سير العمل الكاملة.