بوابة المطابقة

تُشغِّل بوابة المطابقة في src/apothem/conformity/gate.py الجزء الميكانيكي من بوابة ما قبل الإصدار ذات الخمسة عشر شريطًا (M1-M15) على كل مُنتَج يؤلّفه المُشغِّل.

تفترض الأوامر في هذه الصفحة وجود نسخة مسحوبة من Apothem، لذا ضَع PYTHONPATH=src قبل كل أمر تُشغِّله. وبعد التثبيت بالسكربت، استخدم PYTHONPATH="$HOME/.apothem/src" بدلًا من PYTHONPATH=src.

تشغيل البوابةCopy Anchor Link

البوابة استشارية افتراضيًا: تُبلِغ عن النتائج وتخرج بالرمز 0، لذا لا يحجبك التشغيل المحلّي أبدًا. أضِف --strict (أو اضبط APOTHEM_CONFORMITY_STRICT=1) للخروج برمز غير صفري عند وجود نتيجة حاجبة — وهو الوضع الذي يستخدمه CI وpre-commit لإفشال تغيير مخالف.

# Advisory: report every validator's findings across the repo, exit 0
PYTHONPATH=src python -m apothem.conformity.gate --all .

# Strict: exit non-zero (code 2) when a blocking finding is present
PYTHONPATH=src python -m apothem.conformity.gate --all --strict .

رموز الخروج: 0 نظيف (أو استشاري)، و2 حجب بسبب نتائج في الوضع الصارم، و3 خطأ في الاستخدام: راية أو اسم أداة تحقّق غير معروف، أو ملف غير موجود، أو دليل جذر غير موجود. يطبع --help الاستخدام الكامل ويخرج بالرمز 0. وتقبل كل أداة تحقّق مستقلّة الراية --help نفسها وتخرج بالرمز 3 عند راية غير معروفة أو جذر مفقود.

يُحَلّ الجذر النسبي مثل . إلى مسار مطلق قبل تشغيل أي أداة تحقّق، لذا يفحص --all . و--all "$PWD" الشجرة نفسها. تُبلِغ كل أداة تحقّق عن inspected — أي عدد الأهداف التي فحصتها — وينسخ --all ذلك العدد إلى كل مُدخَل في النتائج. وأداة التحقّق التي لم تفحص شيئًا تُبلِغ عن passed: false، لذا لا يمكن أن يجتاز دليل عمل خاطئ بصمت. أداتا التحقّق الخاصتان بحزم الخطّة هما إحدى حالات الاستثناء: تعيش حزم الخطّة في الشجرة .apothem/plans/ التي يتجاهلها git، لذا تُبلِغان عن empty_scope_expected: true على نسخة مسحوبة نظيفة وتجتازان مع ذلك. وتفعل أدوات التحقّق الخاصة بسير العمل الشيء نفسه عندما لا يكون للمشروع دليل .github/workflows/ بعد، وكذلك تفعل أداة التحقّق من عنوان الكوميت عندما لا يكون للجذر سجلّ كوميتات.

تبدأ ست أدوات تحقّق من جذر المستودع وتبحث في الشجرة كلها عن الملفات التي تفحصها:

agents-md-coverage-grep
agnosticism-grep
dynamism-grep
freshness-token-grep
plain-language-grep
reference-token-grep

تتخطّى هذه الأدوات نسخ git المسحوبة المتداخلة، مثل أشجار العمل والوحدات الفرعية والنسخ المستنسخة المتداخلة، وتتخطّى الأدلة التي تحوي الاعتماديات أو البيئات الافتراضية أو ذاكرات التخزين المؤقت أو مخرجات البناء، مثل node_modules وvenv وdist. ويتوقّف فحص الخطط الشاردة في no-global-plans-grep أيضًا عند نسخة مسحوبة متداخلة. وتشغيل أيٍّ من هذه الأدوات يُبلِغ عن النسخة المسحوبة التي وُجِّه إليها ولا شيء غيرها. أما أداة التحقّق التي تقرأ مجلدًا ثابتًا واحدًا، مثل naming-grep تحت src/apothem/، فتقرأ كل ما تحت ذلك المجلد.

أشرطة البوابةCopy Anchor Link

فحوص موجَّهةCopy Anchor Link

# List every registered validator
PYTHONPATH=src python -m apothem.conformity.gate --list

# Run one per-write validator against one file
PYTHONPATH=src python -m apothem.conformity.gate --check multi-surface-coherence src/apothem/rules/my-rule.md

# Run one standalone validator over a root directory
PYTHONPATH=src python -m apothem.conformity.gate --check naming-grep .

# Run every per-write validator against one file
PYTHONPATH=src python -m apothem.conformity.gate src/apothem/rules/my-rule.md

تأخذ أداة التحقّق الخاصة بكل عملية كتابة الملفَ المراد فحصه، أو --stdin لقراءة المحتوى من الدخل القياسي؛ ومن دون أيٍّ منهما تنتظر مُدخَلًا على الدخل القياسي، لذا مرِّر الملف عند تشغيلها من طرفية. وتأخذ أداة التحقّق المستقلّة دليلًا جذرًا (الدليل الحالي عند حذفه). ويُبيِّن --list المجموعة التي تنتمي إليها كل أداة تحقّق.

وضع --hook (python -m apothem.conformity.gate --hook) هو نقطة الدخول التي يستدعيها إطار العمل: يقرأ حمولة JSON لمُدخَلات الأداة من stdin ويُشغِّل سلسلة المطابِقات الخاصة بكل عملية كتابة على عملية الكتابة المعلّقة. هذا هو الشكل الذي يستدعيه خطّاف PreToolUse المنشور؛ ونادرًا ما تستدعيه يدويًا.

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

~/.claude      Claude Code
$CODEX_HOME    Codex (~/.codex when CODEX_HOME is not set)

اضبط APOTHEM_CONFORMITY_SCOPE على دليل لاستبدالهما:

# Run the per-write matcher chain against one project tree instead
export APOTHEM_CONFORMITY_SCOPE=/path/to/project

الخطّاف الذي يبدو أنه لا يفعل شيئًا يكون عادةً حالة خروج عن النطاق لا إخفاقًا — افحص هدف عملية الكتابة مقابل النطاقات أعلاه أولًا.

التكامل مع CICopy Anchor Link

تُشغِّل مهمّة الجودة في .github/workflows/ci.yml البوابة في الوضع الصارم (python -m apothem.conformity.gate --all . --strict) عند الدفع إلى main، وعند طلبات السحب إلى main التي تمسّ المسارات التي تراقبها تلك المهمّة. أما سير العمل المنفصل .github/workflows/conformity.yml فيُشغِّل مسح تجهيزات الاختبار (tests/conformity-scenarios/verify.py --strict).