البداية

ثبِّت، ونادِ، واقرأ المخرجات.

مدخلان: الحزمة الكاملة بالنص القرآني المُضمَّن، ونواةٌ بلا مصحفٍ لمن يأتي بنصّه الخاص.

التثبيت والاستيراد

npm install ghunna

// full package: includes the Tanzil Uthmani text (about 730 KB in the ESM build)
import { annotateVerse, getVerseText } from "ghunna";

// corpus-free core (about 34 KB): annotate your own text
import { annotate, tokenize, RULE_META } from "ghunna/core";

كلتا الصيغتين تُشحن بـ ESM وCJS مع تصريحات الأنواع كاملةً. ولا اعتماديّات وقت التشغيل.

استنباط أحكام آية

const result = annotateVerse(36, 52);
// result.text         the verse text (Tanzil Uthmani); ranges index into it by codepoint
// result.annotations  Annotation[]
// result.riwayah      "hafs-shatibiyyah"

وكلُّ موضعٍ على هذه الصورة:

{
  rule: RuleId;                  // e.g. "ikhfa-haqiqi"; 41 identifiers, see the catalog
  name: { arabic; transliteration; english };
  range: [start, end];           // codepoint indices into text, end exclusive
  trigger: { letters; description };
  derivation: string;            // filled template, English; derivationAr in RULE_META
  citation: { text: "tuhfah" | "jazariyyah"; lines: number[] };
  waqfDependent: boolean;
  appliesIn?: "wasl" | "waqf";   // present in mode "both"
  confidence: "certain" | "flagged";
}

النطاقات مؤشِّراتُ نقاطٍ رمزية (codepoints) لا وحدات UTF-16. فكرِّر النص بـ [...text] أو ما يكافئه قبل التقطيع.

كيف تبدو الآية كاملةً

المخرَج نصٌّ واحدٌ مع قائمةٍ مسطَّحةٍ من المواضع، لا إخراجٌ حرفًا حرفًا. لسورة يس، الآية ٥٢:

قَالُوا۟ يَٰوَيْلَنَا مَنۢ بَعَثَنَا مِن مَّرْقَدِنَا هَٰذَا مَا وَعَدَ ٱلرَّحْمَٰنُ وَصَدَقَ ٱلْمُرْسَلُونَ

الآية ١٠٨ نقاطٍ رمزية، ويُرجِع النداء ٢٦ موضعًا. مختارٌ منها، مع النص الذي يقتطعه كلُّ نطاق:

ثلاث ملاحظات. الموضع يغطّي الحرف مع حركاته، وحيث يتعلّق الحكم بحرفٍ بعده (كالإقلاب والإدغام) يغطّي النطاق الحرفين معًا. والمواضع تتداخل بحرّية: فراء ٱلرَّحْمَٰنُ المشدَّدة تقع داخل ثلاثة أحكامٍ معًا: إدغام لام التعريف، وتفخيم الراء، وإخفاء تكريرها. والحروف التي لا حكم لها تُقرأ مُظهَرةً وحسب؛ فالمحرّك لا يُخرِج موضعًا إلا حيث ينطبق حكم.

العرض حرفًا حرفًا

للسؤال عمّا ينطبق على حرفٍ واحد، رشِّح المواضع بحسب الموقع. وتفعل annotationsAt ذلك تمامًا:

import { annotateVerse, annotationsAt } from "ghunna";

const { text, annotations } = annotateVerse(36, 52);
const cps = [...text];               // codepoints, not UTF-16 units

annotationsAt(annotations, 74);       // the ra of al-Rahman:
// [lam-shamsiyyah, ra-takrir, ra-tafkhim]

// a full letter-by-letter breakdown:
cps.map((ch, i) => ({ ch, rules: annotationsAt(annotations, i).map((a) => a.rule) }));

قطِّع النطاقات بـ [...text].slice(start, end) لا بـ text.slice(): فالنطاقات مؤشِّرات نقاطٍ رمزية، وتقطيع UTF-16 يُفسِد أيَّ نصٍّ فيه حروفٌ خارج المستوى الأساسي.

سياق التلاوة

أحكامٌ عدّةٌ لا تكون إلا عند الوقف، وأحكامٌ عدّةٌ تزول به. فيأخذ المحرّك سياق التلاوة خيارًا لا افتراضًا:

annotateVerse(1, 7,   { mode: "stop" });     // waqf at verse end
annotateVerse(2, 255, { mode: "both" });     // union; per-mode spans carry appliesIn
annotateVerse(36, 52, { stopAt: 5 });        // stop after word 5, resume at word 6
annotateVerse(1, 2,   { startFresh: true }); // utterance start: hamzat al-wasl vowel rules

والحال الافتراضية هي الوصل بما بعده. ودلالاتُ كلِّ حالٍ مُبيَّنةٌ في نموذج الوقف.

عقد الإدخال

• الإدخال نصٌّ عربيٌّ عثمانيٌّ مشكولٌ بترميز تنزيل العثماني، والمصحف المُضمَّن هو ذلك النص نفسه منقولًا كما هو.
• تُحفَظ رتبة العلامات المركَّبة، فلا تُطبِّق التطبيع NFC على الإدخال؛ فالتطبيع يعيد ترتيب العلامات ويُتلِف فروقًا يعتمد عليها المُقطِّع.
• النقاط الرمزية المجهولة، والعلامات بلا حرفٍ حامل، والإدخال الفارغ تُطلِق TokenizeError. والفشلُ صريحٌ بالتصميم: هذا هو القرآن، والمحرّك لا يُخمِّن بصمت.
• حيث تنقل المصادر وجهين جائزين لموضعٍ، يُخرَج الموضع بـ confidence: "flagged" بدل الاختيار الصامت لأحدهما.

ما وراء الاستنباط

تُصدِّر الحزمة أيضًا اللبنات: tokenize (نموذج الحروف: الحروف والكلمات والكراسي والحركات)، وRULE_META (جدول الأحكام الكامل بالأسماء والإحالات وقالبَي الاستنباط)، وdescribeLetter وLETTER_PROFILES (مخرج كلِّ حرفٍ وصفاته، بالإحالة إلى أبيات الجزرية)، وgetWaqfMarks (علامات الوقف المطبوعة في مصحف حفصٍ بوصفها بيانات)، وHAFS_SHATIBIYYAH (معطيات الرواية، ومنها مواضع السكت الأربعة المنقولة). والواجهة كاملةً في مرجع الواجهة.