مخطّط خط أنابيب CI/CD

الخريطة البنيوية لسير عمل البناء · التحقّق · النشر الذي يُشترَط اجتيازه لكلّ تغيير في منظومة Apothem. يُثبِّت هذا المستند سطح التصوير البصري. وتعيش ملفات سير عمل GitHub Actions التي يصفها في .github/workflows/ (مثل ci.yml وrelease.yml)، أمّا أدوات الإصدار فتعيش في scripts/release/.

شكل خط الأنابيبCopy Anchor Link

%%{ init: { "theme": "neutral" } }%%
%% verified: 2026-04-27 %%
%% provenance: pyproject.toml + scripts/dev/validate_ecosystem.py + scripts/dev/validate_hooks.py %%
%% cross-reference: site/content/docs/developer-guide.mdx (contributor workflow) %%
flowchart LR
    accTitle: CI/CD pipeline shape
    accDescr: Left-to-right flowchart of the apothem CI CD pipeline showing build, test, lint, type-check, security scan, docs build, package, sign, and publish stages with branch protection gates between them.
    subgraph Trigger["Trigger surface"]
        PR["Pull request opened or updated"]
        PUSH["Push to main"]
        TAG["Tag release vX.Y.Z"]
    end
    subgraph Static["Static analysis lane"]
        LINT["Ruff lint + format check"]
        TYPE["Mypy strict"]
        FRONT["Frontmatter validator"]
    end
    subgraph Test["Test lane"]
        PYTEST["pytest tests/hooks"]
        ECO["validate_ecosystem.py"]
        CHAOS["chaos_pass.py (CI quality job)"]
        BENCH["src/apothem/benchmarks/ (unit tests in CI, bench_hooks in metrics job)"]
    end
    subgraph Security["Security lane"]
        SECRETS["Secret scan"]
        SBOM["SBOM generation (tags only)"]
        LICENSE["License audit"]
    end
    subgraph Publish["Publish lane (tags only)"]
        SIGN["Signed-tag verification"]
        ATTEST["Provenance attestation"]
        RELEASE["Release notes from CHANGELOG.md"]
    end
    DOCS["Project website publish"]
    PR --> Static
    PR --> Test
    PR --> Security
    PUSH --> Static
    PUSH --> Test
    PUSH --> Security
    PUSH --> DOCS
    TAG --> Static
    TAG --> Test
    TAG --> Security
    TAG --> Publish
    Static --> GATE{All lanes green?}
    Test --> GATE
    Security --> GATE
    GATE -->|yes| MERGE[Merge / publish]
    GATE -->|no| BLOCK[Block · surface failures · request fix]
    Publish --> MERGE

أدوار المساراتCopy Anchor Link

• مسار التحليل الساكن — تغذية راجعة سريعة. يغطّي Ruff أسلوب Python ومجموعةً منتقاةً من القواعد؛ ويفرض mypy انضباط الأنواع عند strict؛ ويعمل مُتحقِّق frontmatter بوصفه بوّابة لامتثال مخطّط القِطَع للقواعد والمهارات والعمّال المُفوَّضين والأوامر. لا يقع markdownlint في هذا المسار: فخطّاف pre-commit الخاص به يعمل في CI ضمن سير عمل Markdown Lint عند تغيّر ملفات Markdown (راجع اصطلاحات Markdown).
• مسار الاختبار — يختبر pytest tests/hooks بيئة تشغيل الخطّافات عبر مصفوفة الأحداث الكاملة؛ وvalidate_ecosystem.py هو البوّابة البنيوية الأساسية لاتّساق القِطَع المتقاطعة؛ ويعمل chaos_pass.py في مهمّة الجودة في CI عند عمليات الدفع وطلبات السحب إلى main (مُصفّاة بحسب المسارات) لرصد التدهور تحت مدخلات متدهورة. ويعمل مُشغِّلو قياس الأداء لكل صنف تحت src/apothem/benchmarks/ في CI عبر مجموعة pytest وعبر مهمّة metrics. ويجمع كل تشغيل كامل لـ pytest في CI الملفَّ tests/unit/test_benchmarks.py، الذي يستدعي كل مُشغِّل ما عدا bench_install.py. وتُشغِّل مهمّة metrics الملفَّ scripts/dev/collect_metrics.py، الذي يُشغِّل bench_hooks.py --json ويسجّل النتيجة بوصفها hook_e2e_ms. ولا يقيس bench_tests.py وbench_install.py التشغيلات الفعلية إلا عبر make benchmarks. ولا يوجد أي سير عمل يُشغِّل make benchmarks.
• مسار الأمن — يلتقط gitleaks في ci.yml بيانات الاعتماد المُودَعة عن طريق الخطأ. ويفشل تدقيق التراخيص (license-audit.yml) عند وجود ترخيص اعتمادية خارج قائمة السماح الخاصة به، ويعمل أسبوعيًا وعند تغيّر ملفات الاعتماديات أو التراخيص. وتعمل بوابة REUSE (reuse.yml) عند كل تغيير وتفشل عندما يخلو ملف من سطر الترخيص أو يتعذّر تحليل تعبير SPDX. ويولّد release.yml SBOM لكل إصدار موسوم.
• مسار النشر — تُشغَّل سير عمل الإصدار عند دفع الوسوم، ويمكن أيضًا إعادة تشغيل ناشِري npm وVS Code يدويًا عبر الإرسال اليدوي لوسم موجود. ويؤكّد التحقّق من الوسم الموقَّع منشأ فرع الإصدار، وتُشتقّ ملاحظات الإصدار من تنسيق Keep-A-Changelog في CHANGELOG.md. وينشر موقع المشروع من site/dist/ إلى هدف GitHub Pages عند الدفع إلى main الذي يمسّ مدخلات بنائه، أو عند الإرسال اليدوي.

التهيئة الملموسةCopy Anchor Link

توجد ملفات سير العمل الفعلية (.github/workflows/ci.yml، .github/workflows/release.yml، وغيرها) في المستودع. يُعرِّف هذا المخطّط الشكل المعياري الذي تعكسه كلّ تهيئة مستقبلية.

مراجع متقاطعة موثوقةCopy Anchor Link

• pyproject.toml — مصدر الحقيقة لتهيئة Ruff / mypy / pytest.
• scripts/dev/validate_ecosystem.py — البوّابة الرئيسية لما بين القِطَع.
• scripts/dev/validate_hooks.py — التحقّق البنيوي الخاصّ بالخطّافات.
• scripts/dev/chaos_pass.py — مسح خصومي لكلّ خطّاف مُهيَّأ.
• src/apothem/benchmarks/ — مُتحقِّقو ميزانية وقت التشغيل حسب الصنف.
• site/content/docs/developer-guide.mdx — سير عمل المُساهِم الموجَّه للمُشغِّل.
• CHANGELOG.md — مصدر ملاحظات الإصدار.