# المنسّق

يوفر Phasis منسّق JavaScript أصليًا مبنيًا على محلّله الخاص. يعيد طباعة المصدر وفق دلالات تخطيط متوافقة مع prettier، بالكامل في PHP: بلا Node.js، ولا حزم منسّق مفسّرة، ولا عمليات خارجية.

## formatSource

```php
public static function formatSource(
    string $source,
    string $sourceType = 'script',
    ?FormatOptions $options = null,
): string
```

نقطة الدخول التي تنفّذ كل شيء باستدعاء واحد ضمن `Phasis\Formatter\Formatter`. يحدد `$sourceType` اللغة: `script` أو `module` لـ JavaScript، أو `json`، أو `css`. يحلل JavaScript المصدر وفق الهدف المحدد، ثم يعيد ربط التعليقات ويطبعه ضمن عرض الطباعة المعيّن.

```php
use Phasis\Formatter\Formatter;
use Phasis\Formatter\FormatOptions;

$formatted = Formatter::formatSource(
    "const a={x:1,y:2};",
    'script',
    new FormatOptions(useTabs: true, singleQuote: true),
);
// "const a = { x: 1, y: 2 };\n"
```

المصدر غير الصالح يطلق `Phasis\Exceptions\SyntaxError` نفسه الذي يطلقه المحلّل، مع رقم السطر والعمود والإزاحة.

## FormatOptions

تحاكي خيارات التخطيط خيارات prettier 3.x، وتستخدم القيم الافتراضية لـ prettier:

| الخيار          | الافتراضي    | المعنى                                                        |
| --------------- | ---------- | -------------------------------------------------------------- |
| `printWidth`    | `80`       | عرض السطر المستهدف الذي يُضبط التخطيط ليلائمه.                |
| `tabWidth`      | `2`        | عدد المسافات لكل مستوى إزاحة (والعرض المقاس لعلامة الجدولة).     |
| `useTabs`       | `false`    | استخدم علامات الجدولة بدلًا من المسافات للإزاحة.                            |
| `semi`          | `true`     | الفواصل المنقوطة للعبارات.                                          |
| `singleQuote`   | `false`    | تفضيل `'` على `"` عندما يتطلب ذلك عددًا أقل من محارف الهروب.              |
| `trailingComma` | `'all'`    | `'all'`، أو `'es5'`، أو `'none'`.                                 |
| `bracketSpacing`| `true`     | المسافات داخل أقواس الكائن: `{ a }` مقابل `{a}`.             |
| `arrowParens`   | `'always'` | `'always'` أو `'avoid'` لدوال الأسهم ذات المعامل الواحد.  |

## CSS

ينسّق `formatSource($css, 'css')` أوراق الأنماط وفق تخطيط الأوراق في prettier: محدد واحد في كل سطر ضمن قوائم المحددات، وتصريح واحد في كل سطر، وتوحيد المسافات حول أدوات الربط والقيم، وملء قوائم القيم البسيطة، ووضع عناصر قوائم الفواصل الخاصة بالظلال والتدرجات كلٌّ في سطر، وإبقاء وسائط الدوال كلها في سطر واحد أو نقلها كلها، والحفاظ على الأسطر الفارغة والتعليقات، وترك المقدمات دون تغيير لقواعد at غير المعروفة مثل `@apply` في Tailwind. تُفصل المحددات المركبة الطويلة عند أدوات الربط التابعة، وتُلف وسائط الفئات الزائفة الطويلة داخل الأقواس.

## JSON

يعيد `formatSource($json, 'json')` استخدام محلّل JavaScript وطابعاته مع قواعد json الخاصة بـ prettier: تبقى المفاتيح محاطة بعلامات اقتباس، وتظل السلاسل محاطة بعلامات اقتباس مزدوجة بصرف النظر عن `singleQuote`، ولا تظهر الفواصل اللاحقة مطلقًا، وتبقى تعليقات `//` داخل المستند.

## دلالات التخطيط

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

## التعليقات

تُجمع التعليقات أثناء تقسيم النص إلى رموز (`Parser::setCollectComments(true)`، وهي متاحة لأدوات التطوير عبر المحلّل) ثم يعاد ربطها بالشجرة كمرفقات سابقة أو لاحقة أو متدلية. تحتفظ تعليقات السطر بأسطرها، وتظل التعليقات اللاحقة في السطر نفسه مع عباراتها، وتبقى الأسطر الفارغة المحيطة بالتعليقات، كما يعاد ضبط إزاحة كتل `/** ... */` مع محاذاة هامش `*` الخاص بها.

## الضمانات

تتحقق ثلاثة ثوابت في كل مخرجات التنسيق، وتفرضها مجموعة الاختبارات:

- يُعاد تحليل المخرجات إلى برنامج مكافئ (باستثناء المواقع).
- تبقى كل التعليقات في المدخل ضمن المخرجات.
- التنسيق تكراري ثابت: إعادة تنسيق المخرجات المنسقة لا تغيّر شيئًا.

## الأداء

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