واجهة سطر الأوامر Zero: check وrun وbuild وtest وfix وexplain

ماذا تُقدّم لك واجهة سطر الأوامر

الملف التنفيذي zero هو سلسلة أدوات التطوير الكاملة. لا يوجد مدير حزم منفصل، ولا مُنسّق، ولا مُحلّل ساكن (linter)، ولا مُشغّل اختبارات — كلّها أوامر فرعية لـ zero. هذا يُبقي المساحة السطحية صغيرة ومتوقّعة، وهذا هو الهدف.

قائمة قصيرة بالأوامر التي ستلمسها أكثر:

الأمر	ماذا يفعل
zero check	فحص أنواع المصدر دون إنتاج ملف تنفيذي.
zero run	الترجمة والتشغيل في خطوة واحدة.
zero build	الترجمة إلى ملف تنفيذي أصلي.
zero test	تشغيل أهداف الاختبار في الحزمة.
zero fix	تطبيق خطط الإصلاح المهيكلة أو معاينتها.
zero explain	البحث عن شرح نصّي لرمز تشخيص.
zero new	إنشاء حزمة جديدة من قالب.
zero --version	طباعة إصدار سلسلة الأدوات.

كلّ واحد منها يقبل --json لإصدار مخرجات قابلة للقراءة آليًا بدلًا من النصّ المُنسَّق للبشر.

zero check

الحصان الذي يحمل أكبر حمل. zero check يُشغّل فحوصات المترجم الساكنة — التحليل، وفحص الأنواع، واستنتاج القدرات والتأثيرات، واكتشاف الاستيرادات المفقودة — ويتوقّف قبل توليد الشيفرة. هو سريع، وهذا مهم لأن الوكلاء والمحرّرات تستدعيه باستمرار.

zero check hello.0

مخرجات نظيفة (لا شيء يُطبع، خروج بـ 0) يعني أن الملف سليم. الأخطاء تخرج كنصّ مقروء للبشر افتراضيًا. أضف --json وستحصل على الشكل المهيكل الذي يستهلكه الوكلاء:

zero check hello.0 --json

{
    "ok": false,
    "diagnostics": [
        {
            "code": "NAM003",
            "message": "unknown identifier",
            "line": 3,
            "repair": { "id": "declare-missing-symbol" }
        }
    ]
}

شكل التشخيص موثَّق بالكامل في تشخيصات JSON. لاحظ حقل code المستقرّ — NAM003 تعني دومًا "مُعرِّف غير معروف"، بغضّ النظر عن إصدار المترجم.

يمكنك أيضًا توجيه check إلى مجلد حزمة بدلًا من ملف واحد:

zero check ./my-package

سيقرأ zero.json، ويمشي شجرة المصدر، ويُبلِّغ عن كل مشكلة في كل هدف.

zero run

‏run يُترجم وينفّذ في خطوة واحدة. الأفضل عندما تُكرّر العمل على برنامج صغير ولا تهتم بإنتاج ملف تنفيذي على القرص.

zero run hello.0

مكافئ لتشغيل zero build ثم استدعاء الملف التنفيذي المُنتَج، باستثناء أن المنتج يُرمى. مخرجات البرنامج (stdout) تُمرَّر إلى stdout الخاص بطرفيتك — استدعاءات world.out.write في برنامجك تظهر على شاشتك.

إذا احتاج برنامجك إلى وسائط، مرّرها بعد --:

zero run greet.0 -- Alice

يُعطي زمن التشغيل البرنامج وصولًا إلى هذه الوسائط عبر قدرة World نفسها التي تكشف الإدخال/الإخراج.

zero build

عندما تريد منتجًا قابلًا للشحن، استخدم build:

zero build hello.0

يُنتج المترجم ملفًا تنفيذيًا أصليًا بجانب ملف مصدرك (أو تحت مجلد البناء الخاص بالحزمة إن كنت تعمل داخل حزمة). تستطيع تشغيله مثل أي برنامج آخر — لا حاجة إلى زمن تشغيل منفصل لأن ملفات Zero التنفيذية مكتفية ذاتيًا.

ملفات Zero التنفيذية صغيرة. هدف التصميم في المشروع هو ملفات تنفيذية أقل من 10 كيلوبايت للبرامج البسيطة، ويتحقّق ذلك بتجاوز سلسلة أدوات LLVM وإصدار مسارات شيفرة مدمجة مباشرة.

zero test

شغّل أهداف الاختبار في الحزمة:

zero test

تعيش الاختبارات إلى جانب المصدر تحت src/، مُعلَنة كأهداف اختبار في zero.json الخاص بالحزمة. يكتشفها المُشغّل، ويُنفّذ كلًا منها، ويُصدر نجاح/فشل. مع --json، تكون المخرجات مهيكلة لكل اختبار — اسم وحالة ومدّة وتشخيصات ملتقطة — لكي تستهلكها الوكلاء وأدوات الـ CI.

حزم Zero تشرح كيف تُعلن أهداف الاختبار في zero.json.

zero fix

‏fix يستهلك بيانات الإصلاح التي يُنتجها check --json. يأتي في وضعَين:

zero fix --plan --json   # عرض الخطة المهيكلة دون تطبيقها
zero fix                 # تطبيق الخطة على المصدر مباشرة

تبدو الخطة هكذا (الشكل توضيحي):

{
    "diagnostic": { "code": "NAM003", "line": 3 },
    "plan": {
        "id": "declare-missing-symbol",
        "edits": [
            { "kind": "insert", "line": 1, "text": "fun answer() -> i32 { return 42 }\n" }
        ]
    }
}

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

zero explain

‏explain هو الجانب النصّي من نظام التشخيص:

zero explain NAM003

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

• يُنقّح إنسان ويريد إجابة أطول من الرسالة المضمَّنة.
• يصطدم وكيل برمز تشخيص لم يكن ضمن بيانات تدريبه ويريد سياقًا إضافيًا.

الرمز نفسه مستقرّ عبر إصدارات المترجم، لذا تبقى الشروحات المُخزَّنة صالحة.

zero new

أنشئ حزمة جديدة:

zero new cli hello

يُنشئ هذا مجلد hello/ فيه بيان zero.json وملف انطلاق src/main.0. الوسيط الأول (cli هنا) يختار قالبًا — تطبيق سطر أوامر تنفيذي في هذه الحالة. حزم Zero تشرح التخطيط بالتفصيل.

عادة استخدام --json

تقريبًا كل أمر يدعم --json. إن كنت تبني أدوات، أو واجهة استدعاء للوكلاء، أو خط CI حول Zero، اجعل JSON هو الافتراضي. هو:

• مستقرّ. المخطّط مُرقَّم والفريق يعامله كعقد.
• كامل. ستحصل على حقول ليست في الإخراج البشري (نطاقات دقيقة، ومُعرِّفات خطط إصلاح، وبيانات رسم بياني للاعتماديات).
• قابل للتحليل. لا حاجة لتعابير نمطية على نصّ إنجليزي لاستخراج رقم سطر.

أما للبشر، اترك --json معطّلًا — النصّ المنسّق هو ما تريده في الطرفية.

أوامر مفيدة أخرى

بعض الأوامر الأقل استخدامًا تستحق المعرفة:

• zero graph --json — يُصدر رسم اعتماديات الحزمة كبيانات مهيكلة. مفيد لفهم ما يعتمد على ماذا، وللوكلاء الذين يريدون الاستدلال على مواقع الاستدعاء قبل لمسها.
• zero size --json — يُبلّغ بحجم المنتجات المُترجَمة على القرص، مُفصَّلًا حسب الهدف. مفيد عندما تهتمّ ببصمة الملف التنفيذي (وهذا هدف من أهداف تصميم Zero).
• zero --version — يطبع إصدار سلسلة الأدوات. ثبّت هذا في مكان ما إذا كنت تعمل في فريق — Zero قبل الإصدار 1.0 وتغييرات كاسرة تحدث فعلًا.

التالي: حزم Zero

ملف .0 واحد كافٍ لـ hello-world. أما المشاريع الحقيقية فتستخدم حزمًا فيها بيان zero.json ومجلد src/. حزم Zero يُبيّن كيفية إنشاء حزمة ويشرح كل حقل.