arafix 0.8.0__tar.gz

arafix-0.8.0/.gitignore

@@ -0,0 +1,26 @@
+__pycache__/
+*.py[cod]
+*$py.class
+dist/
+build/
+*.egg-info/
+.eggs/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+.env
+.coverage
+htmlcov/
+.tox/
+.nox/
+broken.pdf
+out.txt
+multi_demo.pdf
+multi.pdf
+*.pdf
+!tests/**/*.pdf
+!examples/**/*.pdf
+.DS_Store
+Thumbs.db

arafix-0.8.0/CHANGELOG.md

@@ -0,0 +1,394 @@
+# سجلّ التغييرات
+
+## 0.8.0
+
+**الدرجة البنيوية** — أعمدة RTL، ترويسة/تذييل، جداول من هندسة الجليفات.
+
+**جاهزية النشر:** `py.typed`، وصف إنجليزي على PyPI، README ثنائي اللغة،
+`DEPLOY.md` / `CONTRIBUTING.md`، مصنّفات أوضح.
+
+**إصلاح CI (macOS):**
+
+- بعض الخطوط تُخرج `U+066C` (فاصل الآلاف `٬`) بدل الفاصلة العربية
+  `U+060C` (`،`). طيٌّ سياقيّ في `hygiene`.
+- أشكال التشكيل المعزولة (`U+FE78`…) كانت تُفكَّك إلى **مسافة + علامة**؛
+  صارت العلامة وحدها. (طيّ التشكيل PF **مبكراً في hygiene يُفسد** العكس —
+  يبقى مؤجّلاً بعد الاتجاه.)
+- اختبار التكامل يتسامح بسقوط التشكيل على بعض خطوط macOS، ويرفض
+  ``نشُرت`` (عنقودٌ خاطئ).
+- ``test_measured_not_asserted``: CER دون 1٪ على الحروف (ignore_diacritics)؛
+  CER الكامل دون 5٪ لأن Arial على macOS يُسقط ~5 علامات تشكيل من SAMPLE.
+
+### المشكلة
+
+القراءة الهندسية كانت تضمّ كل جليفات السطر الأفقي معاً. في صحيفة
+بعمودين يخرج «يسار+يمين» سطراً واحداً ممسوخاً. والجداول تُسطَّح.
+والترويسة تختلط بالجسد.
+
+### الحل: `layout.py` — تقسيم بالميزاب لا بمراكز الأسطر
+
+1. **ميازب أفقية (gutters)** على الجليفات أولاً → أعمدة حقيقية  
+2. **ترتيب قراءة RTL** (الأيمن فالأيسر) — قابل لـ `ltr`  
+3. **شريط ترويسة/تذييل** (٨٪ أعلى/أسفل) يُعزل قبل الأعمدة  
+4. **جداول** من محاذاة خلايا داخل العمود → Markdown + `page.tables`  
+5. **`repair_per_block`**: كل سطر/خلية تُشخَّص وحدها ثم يُعاد التجميع  
+
+```python
+from arafix import extract_pdf, PipelineConfig, LayoutConfig
+
+doc = extract_pdf("paper.pdf", PipelineConfig(
+    layout="auto",           # linear | columns | full
+    layout_config=LayoutConfig(reading_order="rtl"),
+))
+doc.pages[0].n_columns
+doc.all_tables
+```
+
+```bash
+arafix extract paper.pdf --layout full --reading-order rtl -v --tables
+python examples/make_multicolumn_pdf.py multi.pdf
+```
+
+`layout="auto"` (الافتراضي): صفحة عمود واحد تبقى كما في 0.7 — بلا مفاجآت.
+`PageResult.layout` / `.blocks` / `.tables` للبنية الكاملة.
+
+## 0.7.0
+
+طبقةُ الاسترجاع تصير **قابلة للتركيب** — نظافة استخراج، كتلٌ مستقلة،
+معجم وثيقة، وجسر MarkItDown. بلا كسرٍ لوعد النواة صفر-التبعيّات.
+
+### بوابة النظافة (`hygiene`)
+
+محرّكات PDF تُخرج `U+00A0` بدل المسافة و`U+00AD` بدل الشرطة — فتفشل
+مقارنةُ السلاسل وCER يظنّ الخطأ عربياً وهو ترميز. صارت:
+
+| الأثر | العلاج |
+|---|---|
+| NBSP ومسافات يونيكود | → مسافة عادية |
+| soft hyphen | → `-` |
+
+مرحلة `Stage.HYGIENE` تُبلَّغ في التقرير. تُطفأ بـ
+`PipelineConfig(enable_hygiene=False)` إن كنت تقيس المحرّك لا تريد إخفاءه.
+**اختبارات تكامل PDF على ويندوز خضراء.**
+
+### `repair_blocks` / `fix_table`
+
+كل كتلة (خلية، سطر، تسمية) تُشخَّص وحدها. خليةٌ معكوسة لا تعكس جارةً
+سليمة. يقبل `str` و`TextBlock` و`(id, text)` و`dict`.
+
+```python
+from arafix import repair_blocks, fix_table, TextBlock
+fix_table([["…", "OK"]])
+```
+
+وأمر CLI: `arafix blocks` (stdin: سطر = كتلة).
+
+### معجم الوثيقة الداخليّ
+
+`harvest_document_lexicon` + `PipelineConfig(harvest_document_lexicon=True)`
+(افتراضيّ في `extract_pdf` و`repair_blocks`): كلمات الصفحة/الكتلة
+الصحيحة تحسم «المجالت» في غيرها — بلا ملف معجم خارجيّ.
+
+### MarkItDown
+
+- entry point: `markitdown.plugin` → `arafix`
+- `pip install "arafix[markitdown]"` ثم `MarkItDown(enable_plugins=True)`
+- `fix_markitdown(result)` و`fix_any` و`wrap_callable` في
+  `arafix.adapters` / `arafix.integrations`
+- [INTEGRATING.md](INTEGRATING.md)
+
+الاختبارات: ١٥٥ ← +٣٠ تقريباً.
+
+## 0.6.0
+
+بنشمارك خارجيّ جادّ (٣٠ تكراراً، فتراتُ ثقة، اختبارات Welch، cProfile)
+بثمانِ توصيات. **القياسُ على صفحةٍ واقعية قلبَ أولويّاتِه.**
+
+### عنقُ الزجاجة واحدٌ لا ثمانية
+
+على صفحةٍ من ٣١٩٥ محرفاً — لا على سلالم اصطناعية:
+
+| | تصنيفُ التقرير | القياس/صفحة | لأطروحةٍ من ٣٠٠ صفحة |
+|---|---|---|---|
+| `cer` | حرج | **٢٤٦٢ ms** | **١٢ دقيقة ونصف** ☠️ |
+| `diagnose` | أولوية عالية | ٦٫٥ ms | ٢ ثانية |
+| `repair_text` | أولوية عالية | ٧٫٣ ms | ٢٫٢ ثانية |
+| `decode_glyph_name` | عنق زجاجة | ١٫٢ **µs**/نداء | لا شيء |
+
+والمفارقة موجعة: `arafix eval` — الأداةُ المضافة في 0.4.0 **لإثبات
+النزاهة** — كانت غير صالحةٍ للاستعمال على الأطاريح التي بُنيت لأجلها.
+
+### العلاج: مايرز الشعاعية-البِتّية (410×)
+
+**خوارزميّ لا تبعيّة.** استُبدلت المصفوفة الكاملة بخوارزمية مايرز
+(1999): تُمثَّل حالةُ عمودٍ كاملٍ بعددٍ صحيح، ويُحسب التالي بعملياتٍ
+بِتّية عليه. وهنا تنقلب قلّةُ حيلة بايثون فضيلةً — أعدادُه غير محدودة
+الدقّة، فعرضُ «الكلمة» عندنا طولُ النمط كلّه لا ٦٤ بِتّاً.
+
+    cer/صفحة:  2462 ms → 6.1 ms        أطروحة:  745 ث → 1.9 ث
+
+ومعها اقتطاعُ البادئة واللاحقة المشتركتين (O(n)، وأكثرُ النصّ متطابق).
+**والمسافةُ مضبوطةٌ لا تقريبية.**
+
+### تصنيفُ المحارف: مجموعاتٌ مبنيّةٌ مسبقاً (5.5×)
+
+`is_arabic` و`is_presentation_form` تُناديان مرّةً لكل محرف. استُبدل
+بمسح النطاقات فحصُ عضويةٍ في `frozenset` — ١٫٢٤ ms ← ٠٫٢٢ ms على صفحة.
+(قدّر التقرير «١٫٢–٢×»؛ القياس ٥٫٥×.) والمجموعتان مبنيّتان من النطاقات
+**نفسها**، وثمنُهما ٦٤ كيلوبايت لـ١٢٣٢ نقطة. ولا مجموعةَ لـ PUA عمداً:
+١٣٧ ألف نقطة ثمنٌ لا يشتري شيئاً.
+
+    diagnose/صفحة:  6.5 ms → 2.3 ms      repair_text: 7.3 → 3.3
+
+### الضامن: الذكاءُ يُختبَر بالبلاهة
+
+مايرز والمجموعاتُ كلاهما ذكيّ، والسرعةُ بلا ضبطٍ لا قيمة لها. فبقي في
+الشيفرة تنفيذان مرجعيّان بليدان — `levenshtein_reference` و`in_ranges` —
+**لا للاستعمال بل ليكونا محكّاً**:
+
+- اختبارٌ عشوائيّ: ٣٠٠٠ زوجٍ ضدّ المرجع + حالاتٌ حديّة.
+- تصنيفُ المحارف مقارَنٌ بالمرجع على **كل نقطة كودٍ في يونيكود**
+  (١٬١١٤٬١١٢) — لا على عيّنة.
+
+### ما رُدّ — بالقياس لا بالرأي
+
+- **«أضف RapidFuzz» (حرج عندهم)**: قيسَت فكانت أسرع ١١× من مايرز. ورُدّت:
+  ١٫٧ ث ← ٠٫١٦ ث لأطروحة، لأحدٍ لا وجود له. **غلطةُ `arafix[ocr]` عينها.**
+- **«مسارٌ سريع في `grapheme_clusters`» (عالٍ عندهم، «١٫٣–٢×»)**: القياس
+  يقول **أبطأ** في الحالين (٠٫٢٦←٠٫٢٧ مع التشكيل، ٠٫٢٤٧←٠٫٣١٦ بدونه).
+- **«مسحٌ واحد في `diagnose`» (عالٍ)**: يوفّر ~١ ثانية على أطروحةٍ كاملة.
+  ثمنُه ازدواجُ معرفةِ النطاقات — والمجموعاتُ حقّقت المكسب بلا ازدواج.
+- **«Rust/Cython»، «ضبط GC»، «مسار reverse بلا regex»**: نسبُ GC كلها
+  ≈١٫٠ (ضوضاء)، والباقي أقلّ من ثانيةٍ للأطروحة.
+
+### وثلاثةُ عيوبٍ في البنشمارك نفسه
+
+١. **يتوّج الخطأ.** «الأسرع: `reverse_visual_line` / `naive[::-1]`» —
+   والتقريرُ نفسه يصنّفها `comparable: False` لأنها «تُفسد الأرقام
+   ودلالةَ الأقواس». مَن يقيس السرعةَ بلا ضبطٍ يتوّج البليد؛ وهذه
+   المكتبةُ قائمةٌ أصلاً على أن `[::-1]` خطأ.
+٢. **`memory_winner: rapidfuzz peak=0.0`** — صفرُ بايت مستحيل. `tracemalloc`
+   لا يرى ما تخصّصه امتداداتُ C خارج مخصِّص بايثون. أثرُ قياسٍ يُعرَض فوزاً.
+٣. **`detect_mojibake` مقابل «stdlib» مُعلَّمٌ `passed: false`** — وانظر
+   المخرجات: نحن نُعطي `السلام`، و«القرين» يُعيد الموجيبيك كما هو. **القرينُ
+   أخفق لا نحن**، و`ftfy` وافقنا حرفاً بحرف. وسمُ «اختلاف» بلا قولٍ مَن
+   المصيب يقلب النتيجة.
+
+الاختبارات: ١٤٢ ← ١٥٥.
+
+## 0.5.0
+
+مراجعةٌ خارجية بثمانِ ملاحظات. فُحصت بالتشغيل: **أربعٌ صحّت، وأربعٌ لا.**
+
+### صحّت — والأولى فاضحة
+
+**١. الثقة كانت رقماً بلا معنى.** كانت `_confidence` تضرب كلَّ شاهدٍ في
+«كفاية العيّنة»، فتُخرج **٠٫٥٢ لتشخيصٍ قاطع** (فحصُ نطاقٍ حتميّ على
+«ﻣﺮﺣﺒﺎ»)، و**٠٫٤٤ لنصٍّ سليم**. والمكتبة التي تُصدر شهادات ثقة لا
+تُصدَّق إن كانت شهادتُها لا تفرّق بين اليقين والظنّ.
+
+القسمة صارت ثلاثيّة، و`Diagnosis.defect_confidence` يفصل ثقةَ كل علّة:
+
+| الشاهد | الثقة | لماذا |
+|---|---|---|
+| قاطع (نطاقٌ أو اختبارٌ جبريّ) | **١٫٠ دائماً** | فحصُ نطاقٍ على ٥ محارف قاطعٌ كفحصه على ٥٠٠٠ |
+| ظنّيّ (الاتجاه) | بدرجة شاهده | |
+| «سليم» — شهادةُ نفي | ٠٫٣ ← ٠٫٩ بالحجم | **وحدَها** يحكمها الحجم. وسقفُها ٠٫٩ عمداً: غيابُ العلّة ليس برهانَ سلامة |
+
+**٢. `diagnose` كان أعمى بشاهدين من ثلاثة** — والملاحظة صحيحةٌ في
+نتيجتها خاطئةٌ في تعليلها. لم يكن يُضعف شاهد الوصل (فهو يستقبل النصّ
+الخام فيه الأشكال)، بل يُعمي الشاهدين **الحرفيين**: التاء المربوطة
+مخبوءةٌ خلف `U+FE93`، وهي أقواها وزناً (٠٫٥٠). قِسناه: `0.79` بشاهدٍ
+واحد مقابل `0.927` بالثلاثة. فصار `diagnose` يطبّع المفردات داخلياً
+للشواهد الحرفية ويُبقي الخام شاهداً على الوصل — ولا يزال لا يكتب شيئاً.
+
+وكشف اختبارُنا الجديد ثغرةً في الإصلاح نفسه: مسارا الموجيبيك والصفحة
+الفارغة كانا يعودان مبكراً فيتخطّيان حاسب الثقة. **لا مخرجَ يتخطّاه الآن.**
+
+**٣. حزمة `arafix[ocr]` كانت وعداً بلا سند** — تجرّ `pytesseract` ولا
+كودَ يستعمله. حُذفت. لا نبيع تبعيّةً مقابل نيّة. والدرجة ٤ مُعلَّمة `✗
+غير منفَّذة` في سلّم الـ README نفسه لا في الحواشي.
+
+**٤. تغطيةُ «لا تمسّ السليم» والكشيدة ضعيفة.** كان الاختبار جملةً واحدة
+نظيفة — والمحايداتُ والتشكيلُ والكشيدة هي مواطنُ الأذى. صار ٩ حالات
+تشمل الأقواس والتشكيل والنسب والشرطات، و٤ اختباراتٍ للكشيدة.
+
+### لم تصحّ
+
+- **«الدرجة ٣ لم تُختبر كفايةً»**: مغطّاة بـ `decode_glyph_name` وبناء
+  الخريطة واستخراج الخطوط من PDF حقيقيّ. والقصورُ الحقيقيّ فيها مُعلَنٌ
+  سلفاً (خطوط CID) لا مخفيّ.
+- **«التسمية تُضعف الثقة»**: ليست عطباً بل حالةٌ نُشهرها في أول الـ README.
+- **«الدوال المنفصلة خطرة»**: صحيحٌ أن `fold_presentation_forms` ثم
+  `fix_order` يُعطب. لكن إخفاءها يُكلّف التركيب، والخطر موثّقٌ في
+  الـ docstring و**مُخلَّدٌ اختباراً** (`test_the_bug_reproduced_if_order_is_wrong`).
+  و`repair_text` هو المدخل المُوثَّق.
+- **«الاختبارات ملفّان فقط»**: العددُ ليس مقياساً. والقصورُ الحقيقيّ
+  (الأعمدة المتعدّدة والجداول) مُعلَنٌ في «حدودٌ مُعلَنة»، و`arafix eval
+  --compare` موجودٌ ليقيسه المستعمل على ملفاته.
+
+الاختبارات: ١١٩ ← ١٤٢.
+
+## 0.4.0
+
+بحثَ مستعملٌ عن الاسم على GitHub فوجد أربعة مستودعات تحمله. قراءتُها
+أفادت أمرين: تضاربُ اسمٍ حقيقيّ، وثغرةٌ في نزاهتنا.
+
+### القياس (`arafix eval`)
+
+الأربعةُ كلها تحمل `evaluate` ونحن لم نكن نحمله. وكان قولنا «٠ إخفاق من
+١٢» مقيساً على ملفاتٍ **ولّدناها بأنفسنا** — أي يقارب الاختبار الدائريّ
+الذي عبناه على أنفسنا في 0.3.0. ثغرةٌ في النزاهة قبل الميزات.
+
+- وحدة `arafix.evaluate`: `cer`، `wer`، `levenshtein` (بصفّين لا بمصفوفة:
+  الذاكرة O(min) — صفحةُ أطروحة ٣٠٠٠ محرف والمصفوفة تسع ملايين خانة)،
+  `evaluate_text`، `evaluate_pdf`، `compare_extractors`.
+- `arafix eval file.pdf --truth truth.txt --compare` يقيس **كل المسارات
+  على ملفك أنت** ويرتّبها. أوّلُ رقمٍ لنا::
+
+      pymupdf      CER  0.00%   WER  0.00%
+      mupdf-bidi   CER 30.51%   WER 48.48%
+
+- بلا تبعيّات (لا `jiwer`)، ويعدّ الترقيم والتشكيل افتراضياً: تجاهلُهما
+  يرفع الدرجة كذباً ويمحو أصدق ما يقيسه الاختبار.
+- يسرد أسوأ السطور: المعدّل يقول «٣٪ خطأ» ولا يقول أين.
+
+### التسمية
+
+`arafix` شاغرٌ على PyPI، **مأخوذٌ على GitHub بأربعة مستودعات**، وأحدها
+(`AraFix-V3.0`) يوفّر حزمةً عليا اسمها `arafix` بالحرف. التضارب حقيقيّ
+لا نظريّ: من ثبّت الاثنين، آخرُهما يفوز بـ `import arafix` صامتاً.
+أُضيف تنبيهٌ في الـ README وقسمُ «التسمية والجيران». بدائل شاغرة:
+`warraq` (الورّاق)، `qirtas`، `raqim`، `tanqih`.
+
+### الجيران
+
+- ثلاثةٌ من الأربعة مشروعٌ واحد (V1→V3): غلافُ نموذج HuggingFace يصحّح
+  التشكيل والأخطاء الصوتية. لا تقاطع.
+- `CAMeL-Lab/arafix_ocr` (NYU أبوظبي): تصحيحُ OCR بـ n-gram. **متكامل لا
+  منافس** — يبدأ من حيث تنتهي درجتُنا الرابعة.
+- ما زال ينقصنا: نموذجٌ لغويّ يحسم «المجالت» بدل المعجم الساذج، وإخراجُ
+  PDF قابل للبحث.
+
+الاختبارات: ١٠٦ ← ١١٩.
+
+## 0.3.0
+
+سأل مستعملٌ سؤالاً بسيطاً: «هل تبقى الأقواس حول كلمتها أم ينقلب أحدها؟»
+فكشف السؤالُ **ثلاثة أعطاب**، لا واحداً.
+
+### قياسٌ أوّلاً
+
+على ١٢ سطراً فيها ترقيم، مرّرناها في ملف PDF حقيقيّ:
+
+| المسار | الإخفاق |
+|---|---|
+| `get_text()` — بِدي MuPDF | ٩ من ١٢ |
+| القراءة الهندسية + arafix | ٠ من ١٢ |
+
+الحروف تخرج سليمةً والمحايدات مبعثرة::
+
+    (مقدمة الدراسة)   →  ()مقدمة الدراسة
+    الفقرة [أ-ج] هنا  →  ج[ هنا-الفقرة ]أ
+    توقف!             →  !توقف
+
+و«؟» و«؛» تنجوان وحدهما — لأنهما عربيّتان (صنف AL) لا محايدتين.
+
+### العطب ١: بِدي المحرّك يبعثر المحايدات
+
+- محرّك PyMuPDF صار يقرأ **تيار الرسم الخام** ومواضع الجليفات، ويترك
+  الدرجة ٢ تعكس بمنطقنا (`bidi="geometry"`، وهو الافتراضيّ الآن).
+- ونقرأ بـ `get_texttrace` لا `rawdict`: الأخير يعيد ترتيب محارفه ببِدي
+  MuPDF قبل تسليمها، فلا تيارَ فيه أصلاً (أوّلُ محرفٍ يأتي من أقصى اليمين).
+- ولكلٍّ من ربط العنقود وترتيبه شاهدٌ مختلف: **الربط من التيار** (الهندسة
+  تكذب: العلامة عرضُها صفر فتُرسَم عند القلم بعد أن تجاوز حرفَها، فـ x
+  عندها هو x للحرف التالي)، **والترتيب من الهندسة**.
+- `bidi="mupdf"` باقٍ للمقارنة.
+
+### العطب ٢: العكس كان على المحارف لا العناقيد
+
+    أولاً  →  أوًلا        ثانياً.  →  ثانيا.ً
+
+علامة التشكيل عرضُها صفر وتشترك في موضع حرفها. أُضيف `grapheme_clusters`
+وصار `reverse_visual_line` يعكس العناقيد ويحفظ داخلها (`cluster_aware`).
+
+### العطب ٣: أشكال التشكيل الفاصلة كانت تُطبَّع مبكراً
+
+    نُشرت  →  نشُرت        المتغيّر  →  المتغيرّ
+
+`U+FE79` («ضمّةٌ بشكلٍ فاصل») فئتها `Lo` لا `Mn` — محرفٌ قائم بذاته.
+وتطبيعُها يحيلها علامةً لاصقة، فتنقلب وحدةُ العكس. جريمةُ الرباط نفسها
+بثوبٍ آخر.
+
+- استُبدل بمعيار «طول التفكيك» معيارُ **تغيُّر بنية العنقود**
+  (`_changes_cluster_structure`). ومعيار الطول كان يُعمي عن هذا الصنف:
+  تفكيك `U+FE79` هو [كشيدة + ضمّة]، ونحن نطرح الكشيدة فيعود الطول واحداً.
+- `DEFERRED_PF_TO_BASE` (٤٨٩) = رباطات (٤٨٣) + تشكيلٌ فاصل (٦).
+- `expand_ligatures` → `expand_deferred_forms` (الاسم القديم باقٍ للتوافق).
+
+### وأعطابٌ صغرى كشفها السؤال نفسه
+
+- `GDP_2024` كان يخرج `2024_GDP`: الشرطة السفلية لم تكن في المقطع اللاتينيّ.
+- «توقف!» لم تكن تُعكس: حارسُ كفاية العيّنة كان يردّ **البرهان** كما يردّ
+  الإحصاء. وهويّة الوصل برهانٌ، والبرهان لا يحتاج عيّنة — فأُعفي وحده.
+
+### الأقواس: الجواب
+
+تبقى حول كلمتها، **بشرط المرآة**. القوس يُخزَّن بجليفه المرسوم، وجليفُ
+أقصى اليسار في سطرٍ عربيّ هو «(» وإن كان المحرف المنطقيّ هناك «)». فالعكس
+وحده يعطي «)مقدمة(». والمرآة تشمل `() [] {} <> «» “”` — ولا تشمل `؟ ؛ ! .
+, - _` فليست مِرآتية، ومرآتُها تخريب.
+
+الاختبارات: ٦٩ ← ١٠٦.
+
+## 0.2.0
+
+### إصلاح عطبٍ جوهريّ: انقلاب رباط لام-ألف
+
+بلّغ مستعملٌ أن كلماتٍ تخرج هكذا: `االنترنيت`، `المجالت`، `األطاريح`،
+`اإلجراء`. العطب كان **في المكتبة**، ونتيجةً مباشرة لقرارها المعماري
+الخامس («التطبيع قبل الاتجاه»).
+
+**السبب.** «ﻻ» جليفٌ واحد في PDF — والرباط في العربية إلزاميّ لا
+اختياريّ. كانت الدرجة ١ تفكّه إلى حرفين، ثم تعكس الدرجةُ ٢ السطرَ
+فتعكس الحرفين معه: «لا» ← «ال».
+
+**الإصلاح.**
+
+- شُطِّر التطبيع حول الاتجاه: `١أ مفردات ← ٢ اتجاه ← ١ب رباطات`.
+  الرباط يبقى ذرّةً حتى يستقرّ الترتيب. (`fold_simple_forms`،
+  `expand_ligatures`)
+- قُسِم `PF_TO_BASE` إلى `SIMPLE_PF_TO_BASE` (٢٤٨) و`LIGATURE_PF_TO_BASE`
+  (٤٨٣) بمعيارٍ **مشتقّ** لا مكتوبٍ بيد: طولُ التفكيك. فالعطب لم يكن في
+  لام-ألف وحدها بل في ٤٨٣ رباطاً.
+
+### عطبٌ ثانٍ انكشف تحت الأول: عمى الكاشف بعد التطبيع
+
+التطبيع يمحو صيغ الوصل، وهي شاهدُ كاشف الاتجاه. فكان يفتح عيناً
+(التاء المربوطة) ويفقأ أخرى.
+
+- صار `detect_visual_order` يقبل `shaped_source=` فيقرأ الطبقتين معاً.
+- استُبدل بفحص طرفَي الكلمة **هويّةُ الوصل**:
+  `joins_forward(a) == joins_backward(b)` لكل متجاورين — لا تتخلّف في
+  نصٍّ منطقيّ، فخرقُها برهانُ انعكاس. شاهدٌ لا تماثليّ: يدحض ولا يُزكّي.
+  (الفحص القديم كان يُفلت كلماتٍ كـ«الإجراء».)
+
+### جديد
+
+- `arafix.lamalef` — ترقيع رجعيّ لنصٍّ أعطبته أداةٌ أخرى:
+  قاطعٌ حتميّ (ألفان متجاورتان) + مدخل `lexicon=` للمُبهَم.
+- `Defect.LAM_ALEF_TRANSPOSED`، `Stage.EXPAND_LIGATURES`،
+  `Stage.REPAIR_LAM_ALEF`، `PipelineConfig.lexicon`.
+
+### سبب فوات العطب
+
+مولّد العيّنات لم يكن يُنتج رباطات — أي أن ٤٥ اختباراً خضراء كانت
+تختبر المكتبة على عالمٍ لا «لا» فيه. أُضيف `ligate()` إلى المولّد،
+وأُضيفت الكلمات الأربع المُبلَّغ عنها اختباراتٍ دائمة، وفخاخٌ يجب ألّا
+تُمسّ («أفعالهم لا تطابق أقوالهم»، «قال»، «جمال»، «لآلئ»).
+
+الاختبارات: ٤٠ ← ٦٩. الـ doctests: ٦ ← ١٠.
+
+## 0.1.0
+
+الإصدار الأول. الدرجات ٠–٣.

arafix-0.8.0/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing
+
+Thanks for caring about Arabic text integrity.
+
+## Highest-value contributions (in order)
+
+1. **PDFs that break us** — with a short note of expected vs actual text  
+2. **Layout edge cases** — multi-column, tables, headers  
+3. **New extractors** — implement `Extractor` + `@register`  
+4. **Stronger order signals** — pure functions in `diagnose.py`  
+5. **Docs** — English or Arabic clarifications  
+
+## Dev setup
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check src tests examples
+```
+
+## Rules of the house
+
+- **Do not invent characters** (especially CID fonts). Prefer explicit failure.
+- **Do not “fix just in case.”** Every stage needs a signal.
+- Prefer a new **named test** that documents a *decision*, not a line of code.
+- Core stays **dependency-free**. Optional extras only.
+
+## PR tips
+
+- Keep diffs focused.
+- Add CHANGELOG notes under a future version heading if you touch user-visible behavior.
+- Run the suite before pushing.
+
+License: MIT (see [LICENSE](LICENSE)).

arafix-0.8.0/DEPLOY.md

@@ -0,0 +1,127 @@
+# Deploy checklist — arafix 0.8.0 → PyPI
+
+You are shipping an **Alpha**. That is honest and correct. This file is the
+short path from “green on your machine” to “live on PyPI.”
+
+## Pre-flight (already done in-tree)
+
+- [x] Version `0.8.0` in `pyproject.toml` and `src/arafix/__init__.py`
+- [x] `CHANGELOG.md` has `## 0.8.0`
+- [x] Tests pass (`pytest`)
+- [x] `ruff check src tests examples`
+- [x] `python -m build` + `twine check --strict dist/*`
+- [x] English blurb on README + English `description`
+- [x] `src/arafix/py.typed` (PEP 561)
+- [x] MIT license, classifiers, CLI entry point, optional extras
+
+## Your steps (need your accounts)
+
+### 1) GitHub repo
+
+```text
+https://github.com/bio-colab/arafix   (public)
+```
+
+Push this tree to `main`. Ensure workflows exist:
+
+- `.github/workflows/ci.yml`
+- `.github/workflows/publish.yml`
+
+### 2) GitHub Environments
+
+*Settings → Environments → New environment*
+
+| Name | Required reviewers |
+|---|---|
+| `testpypi` | optional |
+| `pypi` | **yes — you** |
+
+### 3) Pending publishers (PyPI + TestPyPI)
+
+[PyPI → Publishing → Add pending publisher](https://pypi.org/manage/account/publishing/)
+
+| Field | Value |
+|---|---|
+| Project name | `arafix` |
+| Owner | `bio-colab` |
+| Repository | `arafix` |
+| Workflow name | `publish.yml` |
+| Environment | `pypi` |
+
+Repeat on [test.pypi.org](https://test.pypi.org) with environment `testpypi`.
+
+> **Critical:** a pending publisher does **not** reserve the name. Configure
+> then publish the same day.
+
+### 4) Local smoke (optional but smart)
+
+```bash
+cd arafix   # package root (where pyproject.toml lives)
+python -m pip install -e ".[dev]"
+pytest
+ruff check src tests examples
+python -m build
+python -m twine check --strict dist/*
+```
+
+### 5) TestPyPI
+
+GitHub Actions → **publish** → Run workflow → target: **testpypi**
+
+Then:
+
+```bash
+pip install --index-url https://test.pypi.org/simple/ \
+            --extra-index-url https://pypi.org/simple/ \
+            arafix
+arafix --version
+python -c "from arafix import repair_text; print(repair_text('\ufee3\ufeae\ufea3\ufe92\ufe8e').text)"
+```
+
+### 6) Real PyPI
+
+```bash
+# versions already 0.8.0 — bump only if you change code after TestPyPI
+git tag v0.8.0
+git push origin main --tags
+gh release create v0.8.0 --title "0.8.0" --notes-file CHANGELOG.md
+```
+
+Approve the `pypi` environment in Actions. Done.
+
+### 7) After live
+
+```bash
+pip install -U "arafix[pdf]"
+arafix --version
+```
+
+Update the README badge if you add a PyPI version shield:
+
+```markdown
+[![PyPI](https://img.shields.io/pypi/v/arafix.svg)](https://pypi.org/project/arafix/)
+```
+
+## What not to claim on the PyPI page
+
+- “Full OCR for scanned PDFs” — stage 4 is not shipped
+- “Perfect every multi-column magazine” — layout is heuristic
+- “Production-stable 1.0” — classifier is Alpha
+
+Do claim: graded Arabic recovery, zero-dep core, evidence-based diagnosis,
+optional PDF + layout.
+
+## If something fails
+
+| Symptom | Fix |
+|---|---|
+| Twine rejects README | Ensure README renders; re-run `twine check --strict` |
+| OIDC / publisher error | Workflow name must be exactly `publish.yml` |
+| Version already exists | Bump to `0.8.1` in both files + CHANGELOG |
+| Name taken | See RELEASING.md rename options (`warraq`, …) |
+
+## One-liner philosophy for the release notes
+
+> arafix 0.8 recovers broken Arabic from native PDFs: diagnose with evidence,
+> repair presentation forms / visual order / lam-alef, clean PDF artifacts,
+> and read multi-column pages right-to-left — without a fake OCR dependency.