# CLI

يوفر Phasis ثلاثة ملفات تنفيذية رئيسية في `bin/`:

- **`bin/phasis`** — تشغيل ملفات JavaScript، وتقييم المصدر المُمرّر في سطر الأوامر، وتفريغ أشجار AST.
- **`bin/test262`** — تشغيل مجموعة اختبارات مطابقة ECMAScript الرسمية على Phasis.
- **`bin/wpt`** — تشغيل تجهيزات اختبارات Web Platform Tests على Phasis (URL والترميز وFetch والترويسات وBlob وAbortSignal والتدفقات وغيرها…).

بعد `composer require phasis/phasis`، تُربط `bin/phasis` و`bin/test262` من `vendor/bin/`. لا يعمل من هناك سوى `bin/phasis`: يحتاج `bin/test262` إلى وحدة git الفرعية `test262` وفئات الاختبار التي لا تتضمنها حزمة Composer، كما أن `bin/wpt` غير مضمّن إطلاقًا. شغّل كليهما من نسخة مستنسخة من مستودع Phasis.

## bin/phasis

```
phasis <file.js> | phasis -e '<source>' | phasis --ast <file.js>
```

هذه الصيغ الثلاث هي الواجهة بأكملها. لا توجد بيئة REPL أو إدخالات عبر stdin أو علامة للوحدات.

### تشغيل ملف

```bash
./vendor/bin/phasis script.js
```

ينفّذ `script.js` بوصفه برنامجًا نصيًا تقليديًا. عند انتهائه، تُطبع دفعة واحدة على stdout كل العناصر التي كتبها البرنامج باستخدام `console.log` (و`console.error` و`console.warn` وغيرها…). وإذا طرح البرنامج استثناءً، تُرسل رسالة الخطأ إلى stderr وتكون حالة الخروج 1.

يُحلَّل الملف دائمًا على أنه برنامج نصي تقليدي؛ لذلك يفشل الملف الذي يتضمن `import` / `export` أو `await` في المستوى الأعلى بخطأ SyntaxError. لتشغيل وحدة ES، استخدم `Engine::evalAsModule()` من PHP (راجع مرجع [API](https://phasis.inline0.dev/ar/docs/api#evalasmodule)) أو اجمع الكود أولًا.

### تقييم المصدر

```bash
./vendor/bin/phasis -e 'console.log(Math.PI * 2)'
# 6.283185307179586
```

تُقيّم الوسيطة بوصفها برنامجًا نصيًا كاملًا. لا تُطبع سوى مخرجات `console`؛ أما قيمة التعبير الأخير فلا تُطبع، لذا لا يطبع `phasis -e '1 + 2'` شيئًا.

### تفريغ AST

```bash
./vendor/bin/phasis --ast script.js
./vendor/bin/phasis -e 'a + b' --ast
```

يطبع شجرة التحليل بصيغة JSON (مع إزاحة بمقدار مسافتين). يفيد ذلك في تصحيح مشكلات المحلل اللغوي أو بناء أدوات تستند إلى Phasis. للوصول البرمجي، استخدم [المحلل اللغوي API](https://phasis.inline0.dev/ar/docs/parser).

## bin/test262

يشغّل `bin/test262` [مجموعة اختبارات test262 الرسمية](https://github.com/tc39/test262) على Phasis. ويفيد كإطار لاختبارات التراجع عند المساهمة بتغييرات. تُنتج اللقطة الكاملة للمجموعة في `COMPAT.md` بواسطة `bin/compat-report` ذي الصلة، الذي تشغّله مصفوفة CI يدويًا على دفعات.

### تشغيل فئة واحدة

```bash
./bin/test262 --category built-ins/Array
```

### تشغيل المجموعة كاملة

```bash
./bin/test262 --jobs 4
```

### الإعدادات

يقرأ المشغّل `config/support.php` من جذر المشروع. وقائمة `test262_skipped_features` فيه فارغة: لا تُتخطى أي ميزة من test262، بما في ذلك `tail-call-optimization`. ويسرد الملف أيضًا الفئات والاختبارات التي يجب تشغيلها بمعزل عن غيرها.

المجموعة نفسها هي وحدة git الفرعية `test262`؛ شغّل `git submodule update --init test262` بعد الاستنساخ. ومن دونها، ينهي المشغّل عمله برسالة "test262 suite not found".

### أعلام أخرى مفيدة

| العلم | الغرض |
|---|---|
| `--failures` | طباعة سطر لكل اختبار فاشل |
| `--limit N` | التوقف بعد أول N اختبارًا |
| `--jobs N` | تشغيل N اختبارًا بالتوازي |
| `--files-from file` | تشغيل الاختبارات المدرجة في `file` فقط |
| `--json` | إصدار ملخص قابل للقراءة آليًا على stdout |
| `--no-progress` | إخفاء سطر التقدم |

راجع [قسم التوافقية](https://phasis.inline0.dev/ar/docs/compatibility) للاطلاع على أحدث لقطة.

## bin/wpt

يشغّل `bin/wpt` تجهيزات اختبارات Web Platform Tests المستوردة إلى `tests/Wpt/fixtures/`. وتشمل مجموعة الاختبارات URL والترميز وatob/btoa وstructuredClone والأداء وHeaders وBlob/File وAbortController/Signal وEventTarget وFormData وWHATWG Streams والواجهة الكاملة لـ `crypto`/`SubtleCrypto` و`fetch`/`Request`/`Response` و`XMLHttpRequest`/`XMLHttpRequestUpload` و`WebSocket`. راجع [واجهات Web APIs](https://phasis.inline0.dev/ar/docs/compatibility/web-apis) للاطلاع على جدول نسبة النجاح لكل مجال.

### تشغيل جميع التجهيزات المستوردة

```bash
./bin/wpt
```

### تشغيل فئة واحدة

```bash
./bin/wpt --category headers
./bin/wpt --category streams
./bin/wpt --category blob
```

### مخرجات الاختبارات الفرعية

```bash
./bin/wpt --category abort --verbose
```

يطبع كل اختبار فرعي (PASS / FAIL) داخل كل تجهيز، مع رسائل التأكيد عند الإخفاق.

### مخرجات JSON

```bash
./bin/wpt --json
```

ملخص نجاح/فشل قابل للقراءة آليًا لاستخدامه في مسارات CI أو التحليل النصي.

### ملاحظات

- تبدأ التجهيزات التي تتعامل مع Fetch تلقائيًا خادم اختبارات WPT المضمّن عند `tests/Wpt/fetch-server.php` على `127.0.0.1:8765`، ثم توقفه بعد ذلك.
- ينفّذ الجسر المساعد في `tests/Wpt/testharness-shim.js` واجهة WPT API التي تستخدمها التجهيزات المستوردة فحسب (نحو 400 سطر مقابل نحو 3K سطر في `testharness.js` الكامل).
- توجد التجهيزات المصدرية في `tests/Wpt/upstream/` (نسخة sparse-checkout مستثناة من git من [web-platform-tests/wpt](https://github.com/web-platform-tests/wpt)). لاستيراد المزيد، انسخ ملفات `.any.js` من `upstream/<area>/` إلى `fixtures/<category>/`، وسيتعرف عليها المشغّل تلقائيًا.

## رموز الخروج

ينهي `bin/phasis` عمله بأحد رمزين:

| الرمز | المعنى |
|---|---|
| `0` | نجاح — اكتمل تشغيل البرنامج (وكذلك بعد `--ast`) |
| `1` | أي حالة أخرى: استثناء JS غير ملتقط، أو خطأ نحوي، أو ملف مفقود، أو وسيطات غير صالحة |

تُطبع أخطاء البرنامج على stderr. وتُطبع الوسيطات غير الصالحة والملفات المفقودة سطر الاستخدام على stderr.

## حدود الموارد

يعمل `bin/phasis` بإعدادات المحرك الافتراضية ولا يتضمن أعلامًا للحدود: سقف مكدس استدعاءات JS يبلغ 4,096 إطارًا، وحارسًا للإغلاقات المحوّلة يبلغ 8,192 إطارًا، وقيمة `maxLoopIterations` الافتراضية البالغة 100,000، التي تنطبق فقط على الكود الذي يشغّله المفسّر المتبع لبنية الشجرة (راجع [API: setLimit](https://phasis.inline0.dev/ar/docs/api#setlimit)). لا يوجد حد زمني؛ لذا أَحِط الأمر بـ `timeout` إذا كان من المحتمل ألا ينتهي البرنامج النصي.